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 cupmatches 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.verificationandhints.next_steps— ready-made URLs for the follow-up call. - Errors are 4xx with
{ ok:false, error:{ code, message, docs } };error.paramnames 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.
| Path | What it returns | MCP tool | Auth |
|---|---|---|---|
| GET /api/v1/public/markets/search | Find Kalshi markets by title or keywords | search_markets | Key optional |
| GET /api/v1/public/settled-wins | Search settled Kalshi markets this trader roster won | search_settled_wins | Public |
| GET /api/v1/public/settled-wins/{ticker} | One settled Kalshi market this roster won | get_settled_win | Public |
| GET /api/v1/public/categories | Categories with settled wins | list_categories | Public |
| GET /api/v1/public/stats | Archive totals | get_stats | Public |
| GET /api/v1/markets/live | Live Kalshi markets where the roster holds positions now | get_live_markets | API key |
| GET /api/v1/markets/live/{ticker} | One live market by ticker | get_live_market | API key |
| GET /api/v1/markets/hot | Recent form: where this roster has been winning | get_hot_markets | API key |
| GET /api/v1/whales | The verified traders behind the live feed | get_whales | API key |
| GET /api/v1/watchlist | Watch up to 10 Kalshi traders by nickname | get_watchlist | API key |
| GET /api/v1/search | Search Kalshi series, or recent trades by series or trader | search_trades | API 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.
| Plan | Price | Billed yearly | API & MCP | Requests / day |
|---|---|---|---|---|
| Premium | — (available on Elite and Lifetime) | — | ||
| Elite LLM Access | Included | 500 | ||
| Lifetime | — | Included | 50 |
- 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.
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. Paste this into the Instructions field of a Custom GPT, a Claude project's system prompt, or the first message of any chat with the connector enabled. It tells the assistant to check the live whales first, then the settled archive, and to quote the numbers as returned.
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. You are connected to KalshiSpy (kalshispy.com), independent analytics for Kalshi prediction markets. It follows a roster of ID-verified Kalshi traders with large, verifiable lifetime profits: the markets they hold right now (live feed, needs my API key) and the settled markets they won (public archive, no key). Use it to help me decide which Kalshi market to take.
Use it like this:
1. When I name a market in words, call search_markets first with those words. Read access in the result: it says whether open markets are included and, if my key was refused, why; tell me that reason. Report the side the roster holds now, how many hold it and the price (open_markets.roster), then what named traders traded recently (open_markets.recent_trades: recent trades, not current holdings), then the settled wins it found.
2. For the wider live picture, call get_live_markets and report the side the whales hold, how many hold it, and the consensus percentage. Search it with keywords from what I asked about (e.g. "fed rate"; terms are ANDed against the market question, outcome and tickers), or narrow it by category or series, using the argument names in the tool's own schema. When I name one market by ticker, use get_live_market. An empty result means nothing matching is in the roster's top live positions right now, not that the roster holds none of it or that the market does not exist; say so.
3. Then call search_settled_wins with the same series_ticker or category and summarize how the roster did on similar past markets: how many wins, net profit, and any dissent. The archive is wins only; say so when it matters.
4. Quote numbers exactly as returned (yes_price_cents, whale_count, consensus_pct, net_profit_usd) and name traders by nickname when the data includes them.
5. Treat fewer than 2 whales on the same side as a weak signal. Never invent a position, a price or a trader.
6. Link the market on kalshi.com (urls.kalshi or kalshi_url) so I can act on it.
7. If a tool reports a missing key or an exhausted daily allowance, tell me what it said and stop instead of guessing. The exception is search_markets: it still answers with settled wins and puts that message in access, so relay the message and show the wins.
Answer format: the side, whale count and consensus first; then the evidence; then caveats. Under 150 words unless I ask for detail.
Tools:
- search_markets (Action: searchMarkets) [open markets need my API key]: Find Kalshi markets by title or keywords
- search_settled_wins (Action: searchSettledWins): Search settled Kalshi markets this trader roster won
- get_settled_win (Action: getSettledWin): One settled Kalshi market this roster won
- list_categories (Action: listCategories): Categories with settled wins
- get_stats (Action: getStats): Archive totals
- get_live_markets (Action: getLiveMarkets) [needs my API key]: Live Kalshi markets where the roster holds positions now
- get_live_market (Action: getLiveMarket) [needs my API key]: One live market by ticker
- get_hot_markets (Action: getHotMarkets) [needs my API key]: Recent form: where this roster has been winning
- get_whales (Action: getWhales) [needs my API key]: The verified traders behind the live feed
- get_watchlist (Action: getWatchlist) [needs my API key]: Watch up to 10 Kalshi traders by nickname
- search_trades (Action: searchTrades) [needs my API key]: Search Kalshi series, or recent trades by series or traderThen try one of these as your first message:
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 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. 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. Which Kalshi markets do 3 or more whales agree on right now? Sort by whale flow. For each, give the side, price and consensus, and for the top three tell me how the same traders did on similar settled markets. What do the whales hold on the next Fed rate decision on Kalshi, and how did the roster do on past Fed-rate markets? Who are the top 5 whales by open exposure today, and which single market is each of them most concentrated in? Custom GPT (ChatGPT Actions)
- ChatGPT → Explore GPTs → Create → Configure → paste the instructions into Instructions → Create new action.
- Import from URL:
https://kalshispy.com/api/v1/openapi.json - 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)
- 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.
- Settings → Apps → Create · MCP server URL
https://kalshispy.com/mcp/<your token>· Authentication No Authentication. - For a public-only connector use
https://kalshispy.com/mcpwith 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)
- Claude.ai → Customize → Connectors → + → Add custom connector. On Team and Enterprise an owner adds it under Organization settings → Connectors → Add → Custom → Web.
- 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. - 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
# 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" # 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_ofassinceand de-duplicate changes byid. - 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.