Kalshi

kalshi

来自受美国 CFTC 监管的预测市场交易所 Kalshi 的市场数据。 读取公开数据无需凭据；本工具包中的任何内容都不会访问账户。

本项目属于 Pipeworx——一个将 AI Agent 连接到 1882+ 个实时数据源的 MCP 网关。这是独立的非官方集成，与上游提供方无关联、未获其认可，也不是由其发布。

上游：https://api.elections.kalshi.com/trade-api/v2（文档： https://docs.kalshi.com/llms.txt，该页面提供每个端点页面的 .md 版本）。

包含内容

工具	能回答的问题
kalshi_markets / kalshi_market	按主题查找市场；获取单个市场的完整信息，包括其结算规则
kalshi_events / kalshi_event	获取一个事件及其所有子市场（每个结果区间对应一个）
kalshi_series / kalshi_macro	获取循环问题模板；也可使用易记名称快捷查询（Fed、CPI、BTC……）
kalshi_orderbook / kalshi_orderbooks	获取单个市场的订单簿深度 / 一次获取最多 100 个市场的订单簿深度
kalshi_trades	获取已执行的交易，包含实时或归档数据
kalshi_price_history / kalshi_candlesticks	获取单个市场的 OHLC 数据，支持分页和归档回退 / 在一个共享时间窗口内获取最多 100 个市场的数据
kalshi_top_markets	获取当前交易量最大的市场
kalshi_exchange_status	查询交易所是否开市
kalshi_event_live_data	获取事件结算依据的现实世界测量数据
kalshi_game_stats	获取体育里程碑的实时比分和比赛过程记录
kalshi_milestones	获取 Kalshi 为市场设定的发生事项，以及每项事项对应的事件
kalshi_structured_targets	获取市场所指涉的实体（球员、球队、演员、电影、公司）
kalshi_weather_index / kalshi_weather_index_calibrations	获取城市气温指数市场的结算依据，以及该指数的计算方式

加粗行于 2026-09-16（fleet #2040）上线。八类已探测端点的归属判定及原始响应见 docs/pack-build-queue.md。

已踩过的坑

Kalshi 会在其列表端点上过滤来自 Cloudflare 的出口流量。 多个端点从 Workers IP 发出的请求会返回空结果。网关会注入 _proxyUrl/_proxyToken，并在这些参数存在时让 kalshiGet() 通过中继路由所有上游请求。新增内容必须通过 kalshiGet，不能直接调用 fetch。

此 API 可以明确区分需要身份验证的端点和出故障的端点，因此下结论前请先检查。 需要凭据的端点会返回 401 {"error":{"code":"token_authentication_failure"}}。400 bad_request 表示处理程序拒绝了请求，并非缺少密钥。

/markets/orderbooks 使用重复的 tickers 参数；/markets/candlesticks 使用逗号分隔的 market_tickers 参数。 同一 API 上有两个批量端点，却采用两种不同的数组传参方式。传错会返回 400，而非静默返回部分结果。

批量蜡烛图响应中，每组数据的标签是 market_ticker，不是 ticker。 请根据该标签配对。若按请求顺序配对，会把一个市场的完整价格历史归到另一个市场名下，而且仍然返回 200。

Kalshi 对所有请求市场的批量蜡烛图总数限制为 10,000 根，且不提供游标。 kalshi_candlesticks 会报告 truncated_by_upstream。若要查询单个 ticker 的长时间窗口，或查询已归档的较早市场，请使用 kalshi_price_history；它支持分页并会回退到归档数据，而批量端点两者都不支持。

大多数事件在 /live_data/events/{ticker} 上会返回 404，这是正常现象。 此端点适用于加密货币价格事件和部分经济序列事件。found:false 是如实返回的结果，并非错误。实时 BTC 事件的负载约为 473 KB，因此序列会按 max_points 截断，并通过 series_trimmed 报告截断前的长度。

天气数据按城市索引，而非按事件索引。 KXHIGHNY-26SEP16 在事件实时数据端点上会返回 404。观测数据位于 /live_data/weather/{city}，无论市场是否开放都会存在。 天气指数的城市 ID 恰好有 13 个，它们是 ID，不是地名：miami、dfw、houston、phl-delaware-valley、puget-sound、sf-bay、greater-boston、southeast-michigan、kansas-city、minneapolis-st-paul、nyc、chicago、la-coastal。Kalshi 会在未知城市的拒绝消息中列出这些 ID。austin 不在其中。该指数按分钟更新，因此时长不足约 2 分钟的窗口确实可能返回零个数据点。这里的 from/to 使用 Unix 毫秒；last_sec 使用秒。

天气指数的站点偏移量单位是摄氏度，而指数本身以华氏度发布。（kalshi_weather_index_calibrations。）

对于 Sportradar 不覆盖的里程碑事件，/live_data/milestone/{id}/game_stats 会返回 200 和 {"pbp":{}}——已在一场大学橄榄球比赛中验证，日期为 2026-09-16。plays_available:false 会明确说明这一点，而不会把空数组伪装成没有比赛数据。文档列出的覆盖范围：职业／大学橄榄球、职业／大学篮球、WNBA、足球、职业冰球、职业棒球。

**/structured_targets 不会拒绝未知的 type，而是返回 200 和空列表。**类型按运动项目细分；没有裸用的 player、team 或 athlete（type=player 恰好匹配一条名为 testingmaxxiong 的测试记录）。筛选查询结果为空时，处理程序会列出已知类型，因此拼写错误不会被误解为“Kalshi 没有 NFL 球员”。

/milestones 要求提供 limit（不提供时返回 400），且未筛选的页面内容严重偏向历史数据——传入 minimum_start_date 可查询当前发生的事件。

**被拒绝的调用是错误，绝不是空结果（fleet #3516、#3524）。**Kalshi 返回限流响应或 5xx 时，所有工具都会返回带有 message 的 error（rate_limited／upstream_error），且不会包含任何会让它看起来像结果的字段：不会返回 count: 0，不会用 found: false 代替“记录不存在”，也不会返回空的 markets／trades／series／订单簿。如果工具发起多个请求，但只有部分请求被拒绝，响应会明确说明（partial: true、detail_requests_refused、events_refused、orderbook_error），而不会把成功部分当作完整结果报告。kalshi_weather_index* 仅当 Kalshi 针对城市返回 HTTP 400 时才会报告 unknown_city。每个工具的固定测试见 src/__tests__/refusal-not-empty.test.ts。

**forecast_percentile_history 会先验证，然后拒绝请求。**完整证据见 docs/pack-build-queue.md；不要再试探它以寻找正确参数。

开发

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

通过实时网关使用内部标头进行冒烟测试，切勿使用 BYO 密钥（scripts/pwcall.sh call kalshi_weather_index '{"city":"nyc"}'），并检查负载非空——返回 200 和空数组虽能通过所有 CI 门禁，但仍然是失败的冒烟测试。

快速开始

添加到你的 MCP 客户端（Claude Desktop、Cursor、Windsurf 等）：

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

此端点实际提供的内容

https://gateway.pipeworx.io/kalshi/mcp 上的 tools/list 会返回上表中的工具，以及共享的 Pipeworx 元工具——ask_pipeworx、 discover_tools、search_within、remember/recall 和其余整个网关通用的工具。因此，你看到的工具数量会多于此表：目前，单个工具包端点除了该工具包自身的工具外，还会列出约 30 个共享工具。连接的 initialize 响应会说明其确切范围，也是当日有效的权威信息。

这是有意为之，并非意外的多路复用。元工具让限定范围的连接也能回答此工具包未覆盖的问题——通过跨整个目录路由的 ask_pipeworx 实现，无需再添加第二个 MCP 服务。目前无法挂载不含这些元工具的工具包端点；如果额外的架构定义带来的上下文开销超过路由功能的价值，请连接完整网关一次，而不是连接多个工具包端点。

也可以连接完整的 Pipeworx 网关，直接列出所有工具包的工具，而不只是此工具包的工具：

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

两个 URL 都会连接到同一个网关和同样的 1882+ 个数据源。唯一的区别是直接列出哪个工具包的工具；从任一端点都可以通过 ask_pipeworx 访问所有工具。

没有 MCP 客户端？通过 HTTP 调用

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

首次调用无需账户。查看任意工具：GET https://gateway.pipeworx.io/v1/tools/kalshi_markets。查找工具：使用 {"query":"..."} 向 https://gateway.pipeworx.io/v1/tools/search_packs 发送 POST 请求。

独立运行（无需网关账户）

此软件包也可以作为本地 stdio MCP 服务运行——无需 Pipeworx 账户，也无需往返网关：

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

或者直接运行，以确认它能够启动：

npx -y @pipeworx/mcp-kalshi

它通过 stdin/stdout 使用 MCP 通信，并仅对此工具包的工具响应 initialize/tools/list/tools/call——不包含上述网关连接所添加的任何共享元工具。使用相同的源代码和工具，但没有 ask_pipeworx 路由功能。

使用 ask_pipeworx

你可以用通俗易懂的语言提问，而不是直接调用工具——这既适用于上面的工具包端点，也适用于完整网关：

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

网关会选择合适的工具，并自动填入参数。

更多信息

• 文档和指南
• pipeworx.io

许可证

MIT