MCP server

Connect Claude, ChatGPT, Cursor and other AI agents to Polywhaler. Ask about whale trades, wallets, the Smart Money board, markets and the Bitcoin forecast in plain language, and let the agent look them up for you.

Quant tier

The MCP server comes with the Quant plan, like the API. Every tool call is one API request against your daily quota. See plans.

What it does#

The Model Context Protocol (MCP) is how AI apps call outside tools. Polywhaler's MCP server gives an agent 32 tools, one for each endpoint of the Polywhaler API: the odds, prices and price history of any Polymarket or Kalshi market, with the two venues side by side; whale trades on both venues with their insider scores, wallets and clusters, the Smart Money leaderboard and its flow, markets ranked by whale volume, the Bitcoin forecast, and your watchlist.

  • It reads public prediction market activity and Polywhaler's analysis of it. It cannot place orders, move money or touch a trading account.
  • The only thing it can change is your watchlist, and only if you allow that when you connect.
  • It sees only what the agent sends in a tool call, such as a wallet address or a date range. It never reads your conversation, your files or the AI app's memory.

Server URL#

The server is at https://polywhaler.com/api/mcp and speaks Streamable HTTP. Most clients need only that URL.

To keep the tool list short, add ?toolsets= with the groups you want, for example https://polywhaler.com/api/mcp?toolsets=trades,wallets. The toolsets are market_data, trades, wallets, smart_money, markets, forecasts, watchlist and account. The portal's Developer › MCP server page builds the URL for you.

Sign in or use an API key#

API key#

Scripts, CI and clients without sign-in (such as Codex) send an API key instead, as Authorization: Bearer pwhk_.... Create one under Developer › API keys. A read-only key gets every read tool; a key with the watchlist:write scope can also follow and unfollow wallets. See Get an API key.

Set up your client#

Claude#

Works in Claude on the web, desktop and mobile. Connectors you add on the web or desktop follow you to mobile.

  1. In Claude, open Customize › Connectors, choose + Add, then Add custom connector.
  2. Name it Polywhaler and paste https://polywhaler.com/api/mcp. Leave the OAuth client ID and secret empty.
  3. Choose Connect, sign in to Polywhaler and allow access.
  4. In a chat, open the + menu, choose Connectors and turn Polywhaler on.

On Team and Enterprise plans an Owner adds the connector under Organization settings › Connectors, and members then connect it from Customize › Connectors.

ChatGPT#

ChatGPT connects to custom MCP servers on the web, on a paid plan. The Free plan has no Developer mode or custom servers.

  1. In ChatGPT's settings, open Plugins, then Advanced settings, and turn on Developer mode. On Business and Enterprise a workspace admin turns it on first.
  2. Back in Plugins, choose +, then Add custom MCP server. Name it Polywhaler, paste https://polywhaler.com/api/mcp, choose OAuth and confirm the warning.
  3. Sign in to Polywhaler and allow access.
  4. In a chat, add Polywhaler from the + menu.

Claude Code#

Add the server, then run /mcp in Claude Code, pick polywhaler and choose Authenticate. Your browser opens to sign in. --scope user makes it available in every project.

Terminal
claude mcp add --transport http --scope user polywhaler https://polywhaler.com/api/mcp

With an API key instead:

Terminal
export POLYWHALER_API_KEY='pwhk_...'

claude mcp add --transport http --scope user polywhaler https://polywhaler.com/api/mcp \
  --header "Authorization: Bearer $POLYWHALER_API_KEY"

Cursor#

Add this to ~/.cursor/mcp.json (every project) or .cursor/mcp.json in one project. Cursor asks you to sign in the first time it connects.

mcp.json
{
  "mcpServers": {
    "polywhaler": { "url": "https://polywhaler.com/api/mcp" }
  }
}

VS Code#

Add this to .vscode/mcp.json, or run MCP: Open User Configuration for every workspace. VS Code asks you to sign in the first time the server starts, and the tools appear in Chat's agent mode.

mcp.json
{
  "servers": {
    "polywhaler": { "type": "http", "url": "https://polywhaler.com/api/mcp" }
  }
}

Codex#

Codex uses an API key. Add this to ~/.codex/config.toml and export POLYWHALER_API_KEY in the shell you start Codex from.

config.toml
[mcp_servers.polywhaler]
url = "https://polywhaler.com/api/mcp"
bearer_token_env_var = "POLYWHALER_API_KEY"

Other clients#

Any client that speaks Streamable HTTP works. With sign-in, the server's 401 names its OAuth metadata (https://polywhaler.com/.well-known/oauth-protected-resource/api/mcp), and the client registers itself with dynamic client registration. Without sign-in, send an API key as a Bearer token.

Tools#

Each tool is one API endpoint, with the same parameters. Read tools are marked read only, so your AI app can run them without asking. The two watchlist changes are marked as changes, so it asks you first.

Market data#

These read Polymarket and Kalshi live and answer for both venues side by side, unless the agent names one. When only one venue lists a question, or one doesn't answer, the result says so.

  • get_odds: the odds on one question from both venues in one call, lined up outcome by outcome and priced the same way on each, with whale flow beside them. "What are the odds of a December Fed cut?" is one call.
  • search_markets: events on both venues by text, or the busiest, the soonest to end and the recently closed.
  • get_event: one event with every market in it, its counterpart on the other venue and its whale flow.
  • get_market: one market's prices, bid and ask, moves over an hour, a day and a week, volume, open interest and result.
  • get_market_price_history: an outcome's price over time, with the same outcome on the other venue drawn alongside.

Trades#

  • list_trades: whale trades on Polymarket and Kalshi, newest first (both venues unless the agent names one), filtered by wallet, category, side, size, insider score, event or date.
  • get_trade: one trade with its full insider scoring and, once the market resolved, how it did.
  • list_insider_events: events whose whale trades score highest for insider risk.
  • list_outcomes: how whale trades did once their market resolved, with ROI.

Wallets#

  • get_wallet: a wallet's Smart Money standing and stats.
  • list_wallet_trades: a wallet's whale trades.
  • get_wallet_positions: a wallet's open and closed positions, read live from Polymarket.
  • get_wallet_score_history: a wallet's daily Smart Money Score and rank.
  • get_wallet_clusters: the clusters a wallet belongs to.
  • list_clusters: groups of wallets that appear to be one trader.

Smart Money#

  • list_smart_money_leaderboard: wallets ranked by Smart Money Score.
  • list_smart_money_trades: whale trades by the ranked wallets.
  • get_smart_money_flow: net whale flow by category, all whales against the smart tier.
  • get_active_methodology: how the Smart Money Score is computed.

Markets#

  • list_markets: events ranked by whale volume, with buy and sell split and insider scores.
  • list_aggregated_positions: positions built from many smaller fills that together cross the whale threshold.
  • list_crypto_markets: Polymarket's open crypto price markets with their outcome prices.
  • get_black_swan_status: the latest tail-risk reading.
  • list_oracle_editions: The Prophet's daily briefings.

Forecasts#

  • get_btc_forecast: the latest hourly Bitcoin price forecast, fitted to Polymarket and Kalshi price markets.
  • list_btc_forecast_markets: the markets behind the forecast and each one's weight.
  • list_btc_forecast_history: past forecast runs, for up to a year.

Watchlist#

  • list_watchlist: the wallets you follow.
  • list_watchlist_consensus: positions several wallets you follow took on the same side.
  • add_to_watchlist: follow a wallet. Following one you already follow replaces its name and image. Needs watchlist access.
  • remove_from_watchlist: unfollow a wallet. Needs watchlist access.

Account#

  • get_usage: today's requests against your daily quota. It does not count against the quota itself.

Every parameter and field is in the API reference. Trade lists and market search include sports unless the agent passes sports=exclude; the Smart Money leaderboard leaves sports traders out unless it passes sports=include.

Try asking#

  • What are the odds of a December Fed cut on Polymarket and Kalshi?
  • Chart the December Fed decision's most likely outcome over the last week on both venues.
  • What were the five largest Polymarket whale trades in the last 24 hours, and who placed them?
  • Which events have the most insider-like whale flow this week?
  • Who are the top 10 wallets on the Smart Money board, and what have they bought today?
  • Where is smart money flowing by category over the last 7 days, compared with all whales?
  • What does the latest Bitcoin forecast say about the price at the end of the month?
  • Look up wallet 0x… and summarize its record, its open positions and any clusters it is in.

Quotas and limits#

  • Each tool call is one API request: 10,000 a day on Quant (1,000 a day during a free trial), reset at midnight UTC, and up to 100 a minute per connection or key. The quota is shared with your REST API calls.
  • Connecting and listing tools count toward the minute limit only, and get_usage does not use the daily quota.
  • List tools return 20 rows unless the agent asks for more, and page with a cursor. A result too long for an AI app is cut to its first rows, with a note saying how to read the rest.
  • Every call appears in Developer › Logs with the polywhaler-mcp user agent, and each connected app is listed apart in Developer › Usage.

Disconnect an app#

  1. Open Developer › MCP server. Connected apps lists every app you signed in, with its access and when it connected.
  2. Choose Disconnect. The app's access stops at once, and its tokens no longer work.

Then remove the connector in the app too: in Claude under Customize › Connectors, in ChatGPT under Plugins. For a client that uses an API key, revoke the key under Developer › API keys. Deleting your Polywhaler account disconnects every app.

Your data#

For each tool call Polywhaler logs the endpoint, the parameters (with anything that looks like a secret removed), the time, the result status, your IP address and the app's user agent, and keeps the log for 14 days. It also stores each app's registration, your connections and hashed tokens, and the wallets you follow. The privacy policy has the details, including who receives what and for how long.

Troubleshooting#

  • The app asks you to sign in again: the connection was disconnected, or went unused for 90 days. Connect again.
  • plan_required: the account you signed in with isn't on Quant. Sign in with the account that is, or see plans.
  • insufficient_scope, or the watchlist tools are missing: the connection or key is read only. Reconnect and tick watchlist access, or use a key with watchlist:write.
  • quota_exceeded or rate_limited: the daily quota or the minute limit is used up. The error says when to retry.
  • A tool is missing: check the server URL's ?toolsets=. Without it, every tool is listed.

Support#

Email info@polywhaler.com. If a tool returned an error, include its request id: it is at the end of the error message.