{
  "markdown": "# @predge/whale-data-mcp\n\nMCP server that exposes the **Predge Whale Data** x402 API (Polymarket whale\ntrades + smart-money signals) as tools. Payment is handled **under the hood**:\neach paid tool call signs a USDC micropayment via an x402 client — the agent\njust calls the tool and gets data back. You supply a funded buyer key.\n\n> **Defaults to Base mainnet** (the live Predge API is mainnet-only). Paid tools\n> spend **real USDC** — typically $0.005–$0.03/call, hard-capped at\n> `MAX_PRICE_USD` ($0.05 by default) *before* any money moves. Use a dedicated,\n> low-balance buyer wallet.\n\n## Install (one command)\n\n**Claude Code:**\n\n```bash\nclaude mcp add predge-whale-data \\\n  -e BUYER_PRIVATE_KEY=0xYOUR_FUNDED_BASE_MAINNET_KEY \\\n  -e X402_NETWORK=base \\\n  -- npx -y @predge/whale-data-mcp\n```\n\n**Claude Desktop / Cursor / any MCP client** — add to the client's MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"predge-whale-data\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@predge/whale-data-mcp\"],\n      \"env\": {\n        \"BUYER_PRIVATE_KEY\": \"0xYOUR_FUNDED_BASE_MAINNET_KEY\",\n        \"X402_NETWORK\": \"base\"\n      }\n    }\n  }\n}\n```\n\nThat's it — the agent gets **19 tools** (18 paid routes + 1 free discovery tool).\nNo API keys, no account; the buyer key pays USDC per call on Base or Solana. Fund it\nwith a few dollars of USDC (the facilitator pays gas, so no ETH/SOL needed).\n\n**ElizaOS** — add to your character file (via [`@fleek-platform/eliza-plugin-mcp`](https://github.com/fleek-platform/eliza-plugin-mcp)):\n\n```json\n{\n  \"plugins\": [\"@fleek-platform/eliza-plugin-mcp\"],\n  \"settings\": {\n    \"mcp\": {\n      \"servers\": {\n        \"predge\": {\n          \"type\": \"stdio\",\n          \"command\": \"npx\",\n          \"args\": [\"-y\", \"@predge/whale-data-mcp\"],\n          \"env\": { \"BUYER_PRIVATE_KEY\": \"0xYOUR_FUNDED_BASE_MAINNET_KEY\", \"MAX_PRICE_USD\": \"0.05\" }\n        }\n      }\n    }\n  }\n}\n```\n\nSet `MAX_PRICE_USD` to hard-cap spend — any call above it is refused before payment. Full\nintegration guide (ElizaOS, Claude, raw x402 for non-MCP stacks, spend caps): **https://data.predge.io/agents**\n\n## Tools\n\n| Tool | Price | Returns |\n|---|---|---|\n| `predge_list_endpoints` | **free** | API description + every endpoint with its price/schema (call first) |\n| `predge_whales_latest` | ~$0.005 | Latest whale trades ≥$10k (15-min delay). Param: `limit` (1-100) |\n| `predge_whale_market` | ~$0.01 | 7-day whale activity for one market. Param: `condition_id` |\n| `predge_signals_daily` | ~$0.02 | 24h digest: top markets, net flow, largest bets |\n| `predge_wallets_leaderboard` | ~$0.01 | Wallets by realized win rate. Params: `window` (7d\\|30d), `limit` |\n| `predge_wallet_profile` | ~$0.01 | Wallet score, win rates, categories, last 20 trades. Param: `address` |\n| `predge_markets_movers` | ~$0.005 | Largest YES-price moves. Param: `window` (1h\\|6h\\|24h) |\n| `predge_signals_consensus` | ~$0.03 | Edge-verified smart-money net flow + direction per market |\n| `predge_attest` ⭐ | ~$0.02 | **Flagship.** Resolved-outcome attestation — the settled truth for a market (`resolved`, `resolution`, `resolved_at`). Optional `side` (yes\\|no) checks whether a past signal/win-rate claim was actually right. Params: `condition_id`, `side` |\n| `predge_sports_attest` ⭐ | ~$0.02 | **Flagship.** Ed25519-**signed** settled game outcome (winner, final score, `completed`) from ESPN, verifiable offline against Predge's published key. Optional `winner` (team abbr) → `correct`. Settle bets / prove a track record on tamper-evident truth. Leagues: nba, wnba, nfl, college-football, mlb, nhl, mls, epl, champions-league, laliga. Params: `league`, `event_id`, `winner` |\n| `predge_kalshi_attest` ⭐ | ~$0.02 | **Flagship.** Ed25519-**signed** settled Kalshi market resolution (`resolved`, `resolution` yes\\|no, `resolved_at`) from Kalshi's public API, verifiable offline. Attests the market's own result, not trader data. Optional `side` (yes\\|no) → `correct`. Params: `ticker`, `side` |\n| `predge_wallet_attest` ⭐ | ~$0.02 | **Flagship.** Ed25519-**signed** wallet win/loss track record over resolved markets, verifiable offline — turns a self-reported win rate into signed proof. Param: `window` (7d\\|30d, default 30d). Params: `address`, `window` |\n| `predge_bets_biggest` | ~$0.005 | Top-20 largest single trades across all markets. Param: `window` (24h\\|7d) |\n| `predge_signals_daily_category` | ~$0.01 | 24h digest scoped to one category. Param: `category` |\n| `predge_signals_consensus_category` | ~$0.02 | Consensus scoped to one category. Param: `category` |\n| `predge_signals_market` | ~$0.01 | Single-market smart-money verdict (\"trust this move?\"). Param: `condition_id` |\n| `predge_wallet_history` | ~$0.02 | Wallet trade history + running win-rate & PnL curve. Params: `address`, `window` (30d\\|90d\\|all) |\n| `predge_wallets_compare` | ~$0.02 | Compare 2-10 wallets side-by-side + market overlap. Param: `addresses` |\n| `predge_market_history` | ~$0.01 | Price/volume history for one market. Params: `condition_id`, `window` (7d\\|30d\\|all) |\n\nEvery paid result includes a note with the on-chain settle tx. The two Kalshi routes\n(anonymous institutional flow) are not yet exposed as tools — they activate when Kalshi\ningest is enabled; raw x402/HTTP already reaches them.\n\n## Config (env)\n\nPaid tools need a funded key for **at least one rail** — Base (`BUYER_PRIVATE_KEY`)\nand/or Solana (`SOLANA_BUYER_SECRET`). Every paid route's 402 offers both networks;\nthe client pays on whichever it holds a key for (cheapest when both). The\nfacilitator pays the network fee on either rail — the wallet needs USDC only.\n\n| Var | Default | Notes |\n|---|---|---|\n| `BUYER_PRIVATE_KEY` | — | Funded **Base**-mainnet EVM key (`0x…`) for the Base rail. |\n| `SOLANA_BUYER_SECRET` | — | Optional. Funded **Solana**-mainnet key (64-number JSON array or base58) for the Solana rail. |\n| `X402_NETWORK` | `base` | Base network: `base` = mainnet (real USDC), `base-sepolia` only against a testnet deployment. |\n| `X402_SOLANA_NETWORK` | matches `X402_NETWORK` | `solana` (mainnet) or `solana-devnet`. |\n| `SOLANA_RPC_URL` | @x402/svm default | Optional custom Solana RPC (public mainnet-beta is rate-limited). |\n| `PREDGE_BASE_URL` | prod API | `https://x402-api-production-266e.up.railway.app`. Override to point at another deployment. |\n| `MAX_PRICE_USD` | `0.05` | Any call priced above this is refused **before** paying. |\n| `PREDGE_MCP_USER_AGENT` | `predge-whale-data-mcp/0.1.1` | Sent on every request (lets the API attribute MCP traffic). |\n\n> The free `predge_list_endpoints` tool works without any key.\n\n### Testnet\n\nTo exercise the payment path without real money, point `PREDGE_BASE_URL` at a\nBase-Sepolia deployment of the API and set `X402_NETWORK=base-sepolia`; fund the\nbuyer from [faucet.circle.com](https://faucet.circle.com). (The public prod API\nis mainnet-only, so testnet needs your own deployment.)\n\n## Safety\n\n- **Price cap** — `MAX_PRICE_USD` is enforced in the payment selector, so an\n  over-cap call is refused before any money moves (no wasted request).\n- **Network guard** — the client only pays a requirement on the configured\n  network; it won't accidentally settle a mainnet requirement while in testnet\n  mode (or vice-versa).\n- **No key handling beyond env** — the server reads `BUYER_PRIVATE_KEY` from env,\n  never logs it, and never sends it anywhere but the local signer. Use a\n  dedicated low-balance wallet and keep the key out of version control.\n\n## Run from source\n\n```bash\ngit clone https://github.com/predgeAI/whale-data-mcp.git\ncd whale-data-mcp && npm install && npm run build\n# then point your MCP client's \"command\" at node with args [\"/abs/path/whale-data-mcp/dist/index.js\"]\n```\n\n## Verify locally\n\n```bash\nnpm run inspect                                        # list tools (no payment)\nnode dist/dev-list-tools.js predge_list_endpoints      # free call against prod\n# paid call (spends real USDC on mainnet):\nBUYER_PRIVATE_KEY=0x… X402_NETWORK=base node dist/dev-list-tools.js predge_whales_latest '{\"limit\":2}'\n```\n",
  "bytes": 8038,
  "sha": "33620c7d978e7f9c43371cb439d1298fe62c9c8a59c887010e728488abd965ff",
  "repo_slug": "predgeai/whale-data-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_predgeai_whale_data_mcp_ec479a8d/readme"
}