Kalshi

kalshi

Market data from Kalshi, the CFTC-regulated US prediction-market exchange. Public reads need no credential; nothing in this pack ever touches an account.

Part of Pipeworx — an MCP gateway connecting AI agents to 1683+ live data sources.

Upstream: https://api.elections.kalshi.com/trade-api/v2 (docs: https://docs.kalshi.com/llms.txt, which serves every endpoint page as .md).

What is here

Bold rows landed 2026-09-16 (fleet #2040). The bucket assignment for all eight probed endpoint families, with the literal responses, is in docs/pack-build-queue.md.

Traps already paid for

Kalshi filters Cloudflare egress on its listing endpoints. Several endpoints return empty to a Workers IP. The gateway injects _proxyUrl/_proxyToken and kalshiGet() routes every upstream fetch through the relay when they are present. Anything new must go through kalshiGet, never a bare fetch.

Auth-gated vs broken is legible on this API, so check before concluding. An endpoint that needs a credential answers 401 {"error":{"code":"token_authentication_failure"}}. A 400 bad_request is the handler refusing, not a missing key.

/markets/orderbooks takes tickers repeated; /markets/candlesticks takes market_tickers comma-separated. Two batch endpoints on the same API, two different array conventions. Getting it wrong is a 400, not a silent subset.

The batch candlestick response labels each group market_ticker, not ticker. Pair by that label. Pairing by request order would attribute one market's entire price history to another and still return 200.

Kalshi caps batch candlesticks at 10,000 candles across ALL requested markets and gives no cursor there. kalshi_candlesticks reports truncated_by_upstream. For one ticker over a long window — or a market old enough to be archived — use kalshi_price_history, which pages and falls back to the archive; the batch endpoint does neither.

/live_data/events/{ticker} is 404 for most events, and that is normal. It exists for crypto price events and some economic-series events. found:false is the honest answer, not an error. A live BTC event's payload is ~473 KB, which is why series are trimmed to max_points with series_trimmed reporting the untrimmed length.

Weather is city-keyed, not event-keyed. KXHIGHNY-26SEP16 404s on the event live-data endpoint. The observations live at /live_data/weather/{city} and exist whether or not a market is open.

There are exactly thirteen weather-index city ids, and they are ids, not place names: miami, dfw, houston, phl-delaware-valley, puget-sound, sf-bay, greater-boston, southeast-michigan, kansas-city, minneapolis-st-paul, nyc, chicago, la-coastal. Kalshi enumerates them in its own rejection message for an unknown city. austin is not one. The index is per-minute, so a window under ~2 minutes can legitimately return zero points. from/to here are unix milliseconds; last_sec is seconds.

Weather-index station offsets are in Celsius while the index itself is published in Fahrenheit. (kalshi_weather_index_calibrations.)

/live_data/milestone/{id}/game_stats answers 200 with {"pbp":{}} for a milestone Sportradar does not cover — verified on a college football game, 2026-09-16. plays_available:false says so rather than passing an empty array off as a game with no plays. Documented coverage: Pro/College Football, Pro/College Basketball, WNBA, Soccer, Pro Hockey, Pro Baseball.

/structured_targets does not reject an unknown type — it returns 200 with an empty list. The types are granular by sport; there is no bare player, team or athlete (type=player matches exactly one test row named testingmaxxiong). The handler names the known types whenever a filtered query comes back empty, so a typo cannot read as "Kalshi has no NFL players".

/milestones requires limit (a 400 without it) and its unfiltered page skews heavily historical — pass minimum_start_date for current occurrences.

forecast_percentile_history validates and then refuses. Full evidence in docs/pack-build-queue.md; do not re-probe it looking for the right parameters.

Development

node scripts/sync-catalog.mjs          # after any tool change
pnpm check:examples                     # tool-examples.json must cover new tools

Smoke-test through the live gateway with the internal header, never with a BYO key (scripts/pwcall.sh call kalshi_weather_index '{"city":"nyc"}'), and check the payload is non-empty — a 200 with an empty array passes every CI gate and is still a failed smoke test.

Quick Start

Add to your MCP client (Claude Desktop, Cursor, Windsurf, etc.):

{
  "mcpServers": {
    "kalshi": {
      "url": "https://gateway.pipeworx.io/kalshi/mcp"
    }
  }
}

What this endpoint actually serves

tools/list at https://gateway.pipeworx.io/kalshi/mcp returns the tools in the table above plus the shared Pipeworx meta-tools — ask_pipeworx, discover_tools, search_within, remember/recall and the rest of the gateway-wide set. So the tool count you see is larger than this table: a single-pack endpoint currently lists roughly 30 shared tools alongside the pack's own. The connection's initialize response states its exact scope, and is the authoritative answer for a given day.

This is deliberate, not multiplexing by accident. The meta-tools are what let a scoped connection answer a question this pack does not cover — via ask_pipeworx, which routes across the whole catalog — without you adding a second MCP server. There is currently no way to mount a pack endpoint without them; if the extra schemas cost you more context than the routing is worth, connect to the full gateway once rather than to several pack endpoints.

Or connect to the full Pipeworx gateway to get every pack's tools listed directly, instead of just this one's:

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

Both URLs reach the same gateway and the same 1683+ data sources. The only difference is which pack's tools are listed directly; ask_pipeworx reaches all of them from either one.

No MCP client? Call it over HTTP

curl -X POST https://gateway.pipeworx.io/v1/tools/kalshi_markets \
  -H 'Content-Type: application/json' \
  -d '{"keyword":"inflation"}'

No account needed for the first calls. Inspect any tool: GET https://gateway.pipeworx.io/v1/tools/kalshi_markets. Find one: POST https://gateway.pipeworx.io/v1/tools/search_packs with {"query":"..."}.

Standalone (no gateway account)

This package also runs as a local stdio MCP server — no Pipeworx account, no gateway round-trip:

{
  "mcpServers": {
    "kalshi": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-kalshi"]
    }
  }
}

Or run it directly to confirm it starts:

npx -y @pipeworx/mcp-kalshi

It speaks MCP over stdin/stdout and answers initialize/tools/list/tools/call for only this pack's tools — none of the shared meta-tools the gateway connection above adds. Same source, same tools, no ask_pipeworx routing.

Using with ask_pipeworx

Instead of calling tools directly, you can ask questions in plain English — this works on the pack endpoint above as well as on the full gateway:

ask_pipeworx({ question: "your question about Kalshi data" })

The gateway picks the right tool and fills the arguments automatically.

More

• Docs and guides
• pipeworx.io

License

MIT