Whale Data MCP Server

@predge/whale-data-mcp

MCP server that exposes the Predge Whale Data x402 API (Polymarket whale trades + smart-money signals) as tools. Payment is handled under the hood: each paid tool call signs a USDC micropayment via an x402 client — the agent just calls the tool and gets data back. You supply a funded buyer key.

Defaults to Base mainnet (the live Predge API is mainnet-only). Paid tools spend real USDC — typically $0.005–$0.03/call, hard-capped at MAX_PRICE_USD ($0.05 by default) before any money moves. Use a dedicated, low-balance buyer wallet.

Install (one command)

Claude Code:

claude mcp add predge-whale-data \
  -e BUYER_PRIVATE_KEY=0xYOUR_FUNDED_BASE_MAINNET_KEY \
  -e X402_NETWORK=base \
  -- npx -y @predge/whale-data-mcp

Claude Desktop / Cursor / any MCP client — add to the client's MCP config:

{
  "mcpServers": {
    "predge-whale-data": {
      "command": "npx",
      "args": ["-y", "@predge/whale-data-mcp"],
      "env": {
        "BUYER_PRIVATE_KEY": "0xYOUR_FUNDED_BASE_MAINNET_KEY",
        "X402_NETWORK": "base"
      }
    }
  }
}

That's it — the agent gets 8 tools (7 paid routes + 1 free discovery tool). No API keys, no account; the buyer key pays USDC per call on Base. Fund it with a few dollars of USDC (the facilitator pays gas, so no ETH needed).

Tools

Every paid result includes a note with the on-chain settle tx.

Config (env)

Testnet

To exercise the payment path without real money, point PREDGE_BASE_URL at a Base-Sepolia deployment of the API and set X402_NETWORK=base-sepolia; fund the buyer from faucet.circle.com. (The public prod API is mainnet-only, so testnet needs your own deployment.)

Safety

• Price cap — MAX_PRICE_USD is enforced in the payment selector, so an over-cap call is refused before any money moves (no wasted request).
• Network guard — the client only pays a requirement on the configured network; it won't accidentally settle a mainnet requirement while in testnet mode (or vice-versa).
• No key handling beyond env — the server reads BUYER_PRIVATE_KEY from env, never logs it, and never sends it anywhere but the local signer. Use a dedicated low-balance wallet and keep the key out of version control.

Run from source

git clone https://github.com/predgeAI/whale-data-mcp.git
cd whale-data-mcp && npm install && npm run build
# then point your MCP client's "command" at node with args ["/abs/path/whale-data-mcp/dist/index.js"]

Verify locally

npm run inspect                                        # list tools (no payment)
node dist/dev-list-tools.js predge_list_endpoints      # free call against prod
# paid call (spends real USDC on mainnet):
BUYER_PRIVATE_KEY=0x… X402_NETWORK=base node dist/dev-list-tools.js predge_whales_latest '{"limit":2}'