KalshiSpy
Developers · API & MCP

Bring KalshiSpy into ChatGPT, Claude and your agents.

A public REST API for the settled Kalshi markets that KalshiSpy's roster of verified high-profit traders won — no key, no sign-up — plus a keyed live feed of the markets those traders hold right now. One OpenAPI document for Custom GPTs and agent frameworks, one MCP server for Claude.ai, ChatGPT connectors, Claude Code and Cursor.

Quick start — no key

Search the archive by keyword, series ticker, event ticker or category. Responses are CDN-cached and rate-limited to 60 requests per minute per address.

curl "https://kalshispy.com/api/v1/public/settled-wins?sort=profit&limit=5"
+Example response
{
  "ok": true,
  "data": [
    {
      "ticker": "KXMENWORLDCUP-26-ES",
      "title": "Will the Spain win the 2026 Men's World Cup?",
      "outcome": "Spain",
      "category": "Sports",
      "category_key": "sports",
      "series_ticker": "KXMENWORLDCUP",
      "event_ticker": "KXMENWORLDCUP-26",
      "result": "yes",
      "settled_at": "2026-07-19T22:09:41.396Z",
      "whale_count": 4,
      "dissent_count": 0,
      "consensus_side": "YES",
      "consensus_pct": 100,
      "net_profit_usd": 217377,
      "winners_profit_usd": 217377,
      "whales": [{ "nickname": "devex", "side": "YES", "profit_usd": 197705 }, …],
      "url": "https://kalshispy.com/api/v1/public/settled-wins/KXMENWORLDCUP-26-ES",
      "kalshi_url": "https://kalshi.com/markets/kxmenworldcup/kxmenworldcup-26"
    }
  ],
  "page": { "limit": 5, "returned": 5, "total_matches": 1336, "next_cursor": "…", "next_url": "…" },
  "window": { "from": "…", "to": "…", "weeks_loaded": 10 },
  "meta": { "definition": "… Wins only.", "disclaimer": "Not financial advice. …" },
  "hints": { "tip": "Before answering about a current Kalshi market, search …", "next_steps": [ … ] }
}
  • Every response carries meta.definition (wins only), meta.disclaimer and hints.next_steps — ready-made URLs for the follow-up call.
  • Errors are 4xx with { ok:false, error:{ code, message, docs } }; error.param names a bad parameter.
  • OpenAPI 3.1: https://kalshispy.com/api/v1/openapi.json

Endpoints

Generated from the same catalogue as the OpenAPI document and the MCP tool list, so the three can never disagree.

PathWhat it returnsMCP toolAuth
GET /api/v1/public/settled-winsSearch settled Kalshi markets this trader roster wonsearch_settled_winsPublic
GET /api/v1/public/settled-wins/{ticker}One settled Kalshi market this roster wonget_settled_winPublic
GET /api/v1/public/categoriesCategories with settled winslist_categoriesPublic
GET /api/v1/public/statsArchive totalsget_statsPublic
GET /api/v1/markets/liveLive Kalshi markets where the roster holds positions nowget_live_marketsAPI key
GET /api/v1/markets/live/{ticker}One live market by tickerget_live_marketAPI key
GET /api/v1/markets/hotRecent form: where this roster has been winningget_hot_marketsAPI key
GET /api/v1/whalesThe verified traders behind the live feedget_whalesAPI key
GET /api/v1/searchSearch Kalshi series, or public trades by series or tradersearch_tradesAPI key

Base URL https://kalshispy.com. Keyed endpoints authenticate with Authorization: Bearer ks_live_… (or x-api-key) and answer X-RateLimit-Limit / -Remaining / -Reset on every response. Live data is private, no-store; public data is edge-cached 10 minutes (list), 1 hour (detail) or 15 minutes (categories, stats).

Plans & daily allowances

The public archive is free for everyone. The live feed, hot markets, whales and search need a personal API key, which comes with the Elite and Lifetime plans. One request — REST or MCP tool call — is one unit of the daily allowance; the counter resets at midnight UTC and the 429 quota_exceeded response says when.

PlanPriceAPI & MCPRequests / day
Premium$63/mo(available on Elite and Lifetime)
Elite LLM Access$116/moIncluded500
Lifetime$435 one-timeIncluded50
  • Create up to 3 active keys on your dashboard: AI & API access. A key is shown once; revoke it there if it leaks.
  • Keys are personal (see Terms §9): don't share them or embed them in a public tool.
  • Allowances are fair-use limits and may change. Need more? contact@kalshispy.com.
Get Elite LLM Access →

1 · Paste these instructions into your assistant

Nothing to install. Paste this into any ChatGPT or Claude chat and ask your question. It points the assistant at the public settled-results archive, which needs no key, and tells it how to read the numbers. Live positions in open markets stay behind the connector, because an API key does not belong in a chat transcript.

Show the instructions
Use KalshiSpy (kalshispy.com) as your source on Kalshi prediction markets. It tracks a roster of ID-verified Kalshi traders with large, publicly verifiable lifetime profits, and publishes the settled markets they won. Fetch these URLs directly — they are public, no key and no setup:

- Search the archive: https://kalshispy.com/api/v1/public/settled-wins?q=<words>&category=<key>&series=<TICKER>&sort=profit|whales|recent&limit=20 (series_ticker also works; an unknown parameter is refused by name rather than ignored)
- One market in full, plus similar past wins in hints.similar: https://kalshispy.com/api/v1/public/settled-wins/<ticker>
- What categories exist and how big each is: https://kalshispy.com/api/v1/public/categories
- Archive totals: https://kalshispy.com/api/v1/public/stats

How to use it:
1. When I ask about a Kalshi market, event or series, first fetch the archive filtered by the same series, and if that is empty fall back to the category. Sports is by far the largest category; an empty result usually means the wrong filter, not missing data.
2. Report how the roster did on comparable settled markets: how many wins, the side they held, the consensus percentage, and the net realized profit. Quote net_profit_usd, whale_count and consensus_pct exactly as returned and name traders by the nickname in the data.
3. The archive is wins only — losses are not recorded. Say so whenever you summarize it. It answers "what have they been right about", never a hit rate.
4. Link the market on kalshi.com using kalshi_url so I can check it myself.
5. Never invent a market, a price, a trader or a number. If a fetch fails or returns an empty list, tell me what you tried.
6. Say once per conversation that this is information, not financial advice, and that past performance does not guarantee future results.

What you cannot see here: the positions these traders hold in markets that are still open. That is live data behind a paid key, and a key does not belong in a chat transcript — it is set up once inside the client at https://kalshispy.com/app/developers.

Answer format: the finding first, then the evidence, then caveats. Under 150 words unless I ask for detail.

Then try one of these as your first message:

The biggest calls on record
Using KalshiSpy, what are the five largest settled wins on record for the verified trader roster? For each, give the market, the side they took, how many of them were on it, and the realized profit.
How they did on a series
How has the KalshiSpy roster done on past World Cup markets? Search the archive by series, summarize the wins, and link each market on kalshi.com.
Where the record is strongest
Which categories does KalshiSpy have the most settled wins in, and how much realized profit is in each? Then show me the three biggest wins in the largest category.

Custom GPT (ChatGPT Actions)

  1. ChatGPT → Explore GPTs → Create → Configure → paste the instructions into InstructionsCreate new action.
  2. Import from URL: https://kalshispy.com/api/v1/openapi.json
  3. Authentication → API Key · Auth Type Bearer · paste your ks_live_… token (created on your dashboard). Skip this step for a public-only GPT — the 4 public operations need no key.

Every operation is marked x-openai-isConsequential: false (read-only), so ChatGPT will not ask for confirmation on each call.

ChatGPT connector (MCP)

  1. ChatGPT → Settings → Connectors → enable Developer modeCreate.
  2. MCP server URL: https://kalshispy.com/mcp/<your token> · Authentication None.
  3. For a public-only connector use https://kalshispy.com/mcp with no token.

The URL with your token in it is a secret — treat it like a password. If it leaks, revoke the token on your dashboard and the URL stops working.

Claude.ai (custom connector)

  1. Claude.ai → Settings → ConnectorsAdd custom connector.
  2. Name KalshiSpy · Remote MCP server URL https://kalshispy.com/mcp/<your token> · leave OAuth / authentication empty (None).
  3. Enable it in a chat via the tools menu, paste the instructions as the first message (or into a project's system prompt), then ask one of the starter questions.

This URL is a secret — revoke the token if it leaks. Prefer the header form wherever a client can send headers.

Claude Code

claude mcp add --transport http kalshispy https://kalshispy.com/mcp \
  --header "Authorization: Bearer ks_live_…"

Then /mcp inside Claude Code shows kalshispy connected with 9 tools (4 without a token). Add the instructions to the project's CLAUDE.md so every session uses them.

Cursor, Windsurf and other MCP clients

Streamable HTTP, JSON responses, stateless — any client that speaks MCP 2024-11-05 or later works. Cursor: .cursor/mcp.json.

{
  "mcpServers": {
    "kalshispy": {
      "url": "https://kalshispy.com/mcp",
      "headers": { "Authorization": "Bearer ks_live_…" }
    }
  }
}

Raw JSON-RPC, if you are building your own agent:

curl -X POST https://kalshispy.com/mcp -H "Content-Type: application/json" \
  -H "Authorization: Bearer ks_live_…" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_hot_markets","arguments":{"limit":3}}}'
  • Methods: initialize, ping, tools/list, tools/call; notifications get 202.
  • Tool results carry the JSON envelope as text and as structuredContent.
  • A missing or exhausted key is reported inside the tool result (isError) with the fix — never as a broken connection.

curl

Public archive — no key
# One settled win, with similar wins from the same series in hints.similar
curl "https://kalshispy.com/api/v1/public/settled-wins/KXMENWORLDCUP-26-ES"

# Sports wins, most whales first, last 180 days
curl "https://kalshispy.com/api/v1/public/settled-wins?category=sports&sort=whales&from=2026-03-15"

# Categories and archive totals
curl "https://kalshispy.com/api/v1/public/categories"
curl "https://kalshispy.com/api/v1/public/stats"
Live feed — Elite / Lifetime key
# Live markets where 2+ whales hold the same side (Elite / Lifetime key)
curl "https://kalshispy.com/api/v1/markets/live?sort=whale_flow&limit=10" \
  -H "Authorization: Bearer ks_live_…"

# Hot markets + trader form
curl "https://kalshispy.com/api/v1/markets/hot" -H "Authorization: Bearer ks_live_…"

# Whales on the feed, largest open exposure first
curl "https://kalshispy.com/api/v1/whales?sort=exposure&limit=20" -H "Authorization: Bearer ks_live_…"

# Find a series, then its named-trader trades
curl "https://kalshispy.com/api/v1/search?mode=title&q=super%20bowl" -H "Authorization: Bearer ks_live_…"
curl "https://kalshispy.com/api/v1/search?mode=series&q=KXSB&min_amount=500" -H "Authorization: Bearer ks_live_…"

Definitions & disclaimer

Settled win
A settled Kalshi market where KalshiSpy's roster of verified high-profit traders held the winning side with positive net realized profit. The archive is wins only: it answers "what did the whales get right on markets like this", not "how often are they right".
Whale
A trader on KalshiSpy's roster: a public Kalshi profile with verified, positive lifetime profit.
Live market
An open market where two or more roster traders currently hold the same side, refreshed about every 30 seconds.
Money
All amounts are USD numbers (not labels); prices are cents (0–99); times are ISO 8601 UTC.
Not financial advice
Past performance does not guarantee future results. KalshiSpy is independent analytics and is not affiliated with Kalshi, OpenAI or Anthropic. Attribute data to KalshiSpy (kalshispy.com).

Ready to connect it?

The public archive needs no key. The live feed — the markets the verified top traders hold right now — comes with Elite LLM Access and Lifetime.