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.", "verification": "Every trader is ID-verified, and every name and settled result is checkable on kalshi.com." },
  "hints": { "tip": "Before answering about a current Kalshi market, search …", "next_steps": [ … ] }
}
  • Find a market by name: /api/v1/public/markets/search?q=world cup matches titles the way the app's search does. Settled wins without a key; send your key and the same call adds open markets.
  • Every response carries meta.definition (wins only), meta.verification 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/markets/searchFind Kalshi markets by title or keywordssearch_marketsKey optional
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/watchlistWatch up to 10 Kalshi traders by nicknameget_watchlistAPI key
GET /api/v1/searchSearch Kalshi series, or recent 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). Market search is never cached, because its answer depends on the key: settled wins without one, open markets as well with an Elite or Lifetime key.

Plans & daily allowances

The public archive and market search are free for everyone; without a key, market search returns settled wins only. Open markets in market search, the live feed, hot markets, whales, trade search and the watchlist 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.

PlanPriceBilled yearlyAPI & MCPRequests / day
Premium$90 $63/mo$900 $630/yr · 2 months free— (available on Elite and Lifetime)—
Elite LLM Access$200 $116/mo$2,000 $1,160/yr · 2 months freeIncluded500
Lifetime$870 $435 one-time—Included50
  • New members get the discounted prices for 48 hours from the moment their countdown starts; after that, the list price applies.
  • 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:

- Find a market by name or keywords (a team, a nickname or an approximate title works; settled wins only here): https://kalshispy.com/api/v1/public/markets/search?q=<words>
- 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 market search with my words. If that comes back thin, fetch the archive filtered by the series it matched (resolution.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.

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 Instructions → Create 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 5 public operations need no key, and market search then answers with settled wins only.

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 on the web → Settings → Security and login → turn on Developer mode (Plus and Pro). On Business, Enterprise and Edu a workspace admin turns it on first, under Workspace settings → Permissions & roles.
  2. Settings → Apps → Create · MCP server URL https://kalshispy.com/mcp/<your token> · Authentication No Authentication.
  3. For a public-only connector use https://kalshispy.com/mcp with no token.

Every KalshiSpy tool is read-only. No developer mode on your account? A Custom GPT reaches the same data through Actions.

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 → Customize → Connectors → + → Add custom connector. On Team and Enterprise an owner adds it under Organization settings → Connectors → Add → Custom → Web.
  2. Name KalshiSpy · Remote MCP server URL https://kalshispy.com/mcp/<your token> · choose No sign-in. Leave Advanced settings empty: the token goes in the URL, never in the OAuth Client ID or Secret fields.
  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.

If Claude cannot connect, its error message and page URL carry a reference starting ofid_. Send it with the time it happened to contact@kalshispy.com: the time finds your request in our logs, and the reference lets Anthropic trace its side.

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 11 tools (5 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 through the current 2026-07-28 revision 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
# Find markets by title or keywords: settled wins without a key
curl "https://kalshispy.com/api/v1/public/markets/search?q=world%20cup"

# 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
# Market search with a key: the same call adds open markets (1 unit)
curl "https://kalshispy.com/api/v1/public/markets/search?q=nfl" \
  -H "Authorization: Bearer ks_live_…"

# Live markets the whales hold now, most dollars committed first (Elite / Lifetime key)
curl "https://kalshispy.com/api/v1/markets/live?sort=whale_flow&limit=10" \
  -H "Authorization: Bearer ks_live_…"

# Same feed, searched by keyword: terms are ANDed against the question,
# outcome, series ticker and ticker
curl "https://kalshispy.com/api/v1/markets/live?q=fed%20rate" \
  -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_…"

# Watch up to 10 traders by exact nickname: open positions, closed markets
# and a change log, for 1 unit. To poll, add since=<the last data.as_of>
# and de-duplicate changes by id
curl "https://kalshispy.com/api/v1/watchlist?traders=Saiph,Hidden.Edge" \
  -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

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: an ID-verified Kalshi trader with verified, positive lifetime profit.
Live market
A market the roster holds right now: two or more roster traders in profit together on it, on either side, and while the feed is short, a single roster trader up $100 or more. Refreshed about every 30 seconds.
Watchlist
Up to 10 Kalshi traders by exact nickname, any public trader: their open positions with value, cost and P&L, the markets they recently closed, and a change log of their trades, newest first. One request is one unit, however many traders it names. To poll, send the last as_of as since and de-duplicate changes by id.
Coverage
Each watched trader is verified (on the roster), public (any other public Kalshi trader), private (positions hidden), not_found (no account by that exact name; nicknames are case-sensitive) or unavailable (not readable this time; ask again shortly).
Money
All amounts are USD numbers (not labels); prices are cents (0–99); times are ISO 8601 UTC.
Independent and verifiable
Every trader and every result is checkable on kalshi.com. 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.