Kalshi API
交易和查询首个CFTC监管的预测市场交易所。二元是与否合约,覆盖真实世界事件,定价1-99美分。
基础URL: https://external-api.kalshi.com/trade-api/v2
演示URL: https://external-api.demo.kalshi.co/trade-api/v2
在 https://kalshi.com/account/api-keys 获取您的API密钥(需要Premier或Market Maker层级)
关键概念
层级结构:系列 > 事件 > 市场
- 系列 — 周期性事件模板(例如“月度就业报告”、“每周失业救济申请”)
- 事件 — 系列中的具体实例(例如“2026年5月就业报告”)
- 市场 — 事件中的单个二元结果(例如“新增就业人数是否超过20万?”)
二元合约定价
- 价格以美分为单位(1-99),代表隐含概率
- “是”合约价格为65美分表示市场隐含概率为65%
- “是”的买价X等同于“否”的卖价(100 - X) — 订单簿仅显示“是”买价和“否”买价
- 结算:若“是”,支付1.00美元(100美分);若“否”,支付0美元
- 所有货币值(余额、价格、结算)均以美分为单位
交易代码格式
- 系列:
KXBTC,KXJOBLESS,KXINX - 事件:
KXBTC-25MAY30(系列 + 日期) - 市场:
KXBTC-25MAY30-T100000(事件 + 阈值/结果)
体育比赛代码遵循不同模式:{SERIES}-{YYMONDD}{TEAM1}{TEAM2}-{TEAM}
- 示例:
KXNHLGAME-25MAY12EDMORL-EDM(NHL,2025年5月12日,埃德蒙顿 vs 奥兰多,埃德蒙顿赢) - 每个比赛事件有两个互斥的“是”市场 — 每队一个
关键:基于系列的市场导航
不要对体育、选举或任何基于系列的类别使用 /markets?keyword=。它只会显示多场比赛的捆绑组合,而不是实际的比赛级市场。搜索“NHL”、“Fulham”、“Premier League”等将返回零个或无关结果。
始终遵循:系列 → 事件 → 市场。 比赛级市场位于系列/事件层级下,必须通过 /events?series_ticker=KXXX 访问。此外,/markets/{ticker} 可能对比赛市场返回404 — 买卖价格仅出现在事件端点响应中(/events/{event_ticker} 配合 with_nested_markets=true)。
此模式适用于所有基于系列的类别,不仅仅是体育:
- 体育比赛 — NHL、NBA、NFL、MLB、EPL等
- 政治竞选 — 多候选人事件中的单个候选人市场
- 特定公司市场 — 收益、CEO变更等
- 周期性经济数据 — 就业报告、失业救济申请、CPI等
已知体育系列代码:
| 体育项目 | 系列代码 | 示例 |
|---|---|---|
| NHL | KXNHLGAME | KXNHLGAME-25MAY12EDMORL |
| NBA | KXNBAGAME | KXNBAGAME-25MAY12BOSLAL |
| NFL | KXNFLGAME | KXNFLGAME-25SEP07KCDET |
| MLB | KXMLBGAME | KXMLBGAME-25MAY12NYYLAD |
| EPL(英超) | KXEPLGAME | KXEPLGAME-25MAY12FULARS |
正确的体育工作流程:
# 1. 列出某项体育的开放比赛
curl -s "https://external-api.kalshi.com/trade-api/v2/events?series_ticker=KXNHLGAME&status=open&with_nested_markets=true"
# 2. 获取特定比赛的实时买卖价
curl -s "https://external-api.kalshi.com/trade-api/v2/events/KXNHLGAME-25MAY12EDMORL?with_nested_markets=true"
# 错误 — 不要这样做:
# curl -s "https://external-api.kalshi.com/trade-api/v2/markets?keyword=NHL" ← 返回组合,不是比赛
如何调用
Kalshi 使用 RSA 密钥对签名认证。认证请求需要三个头部:
| 头部 | 值 |
|---|---|
KALSHI-ACCESS-KEY | API 密钥 ID($KALSHI_ACCESS_KEY) |
KALSHI-ACCESS-SIGNATURE | timestamp + method + path 的 RSA-PSS 签名 |
KALSHI-ACCESS-TIMESTAMP | Unix 时间戳(毫秒) |
公共 GET 端点(市场、事件、订单簿)无需认证头部即可调用。
# 公共端点 — 无需认证
curl -s "https://external-api.kalshi.com/trade-api/v2/markets?limit=10&status=open"
对于认证端点,请使用直接的 RSA-PSS 签名(不要使用 kalshi_python SDK — 它不工作):
import os, time, base64, requests
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding
from cryptography.hazmat.backends import default_backend
from dotenv import load_dotenv
load_dotenv('/data/workspace/.env')
BASE_URL = "https://api.elections.kalshi.com"
def kalshi_headers(method: str, path: str) -> dict:
import re
raw = os.environ["KALSHI_PRIVATE_KEY"]
# 首先解码字面转义序列(某些输入通道将 '\n' 保存为两个字符反斜杠+n,而不是真正的换行符)
raw = (raw.replace('\\r\\n', '\n').replace('\\n', '\n')
.replace('\\r', '\n').replace('\\t', ' '))
# 如果存在 PEM 标记,则剥离,然后剥离所有空白并重新换行
body = re.sub(r'-----BEGIN[^-]+-----', '', raw)
body = re.sub(r'-----END[^-]+-----', '', body)
body = re.sub(r'\s+', '', body)
wrapped = '\n'.join(body[i:i+64] for i in range(0, len(body), 64))
pem = f"-----BEGIN RSA PRIVATE KEY-----\n{wrapped}\n-----END RSA PRIVATE KEY-----\n"
private_key = serialization.load_pem_private_key(pem.encode(), password=None, backend=default_backend())
ts = str(int(time.time() * 1000))
msg = (ts + method + path).encode() # path 绝对不能包含查询字符串
sig = private_key.sign(msg, padding.PSS(mgf=padding.MGF1(hashes.SHA256()), salt_length=padding.PSS.DIGEST_LENGTH), hashes.SHA256())
return {
"KALSHI-ACCESS-KEY": os.environ["KALSHI_ACCESS_KEY"].strip(),
"KALSHI-ACCESS-TIMESTAMP": ts,
"KALSHI-ACCESS-SIGNATURE": base64.b64encode(sig).decode(),
"Content-Type": "application/json"
}
path = "/trade-api/v2/portfolio/balance"
resp = requests.get(BASE_URL + path, headers=kalshi_headers("GET", path))
print(resp.json()) # {"balance": 5000, ...} — 余额以美分为单位
签名注意事项:
- PSS 而不是 PKCS1v15 — PKCS1v15 填充返回 401。必须使用 PSS 配合 SHA256。
- 签名前剥离查询字符串 — 签名仅在裸路径上计算(例如
/trade-api/v2/portfolio/balance),而不是/trade-api/v2/portfolio/balance?param=value。包含查询字符串将导致 401。 - 密钥环境变量格式 —
KALSHI_PRIVATE_KEY接受以下任意格式:原始 base64 主体、带有真正换行符的完整 PEM、或换行符被折叠为空白(常见于通过 Web 表单粘贴时)的完整 PEM。辅助函数会自动规范化所有格式。为了最稳健的存储,请在.env中将密钥保存为带\n转义的双引号多行 PEM,这样 python-dotenv 会将其还原为真正的 PEM 字符串。
API 规范
完整 OpenAPI 规范:https://docs.kalshi.com/openapi.yaml
意图路由
将用户意图映射到正确的端点。所有路径均相对于基础 URL。
事件
| 方法 | 端点 | 主要参数 | 描述 |
|---|---|---|---|
| GET | /events | limit (1-200), cursor, status, series_ticker, with_nested_markets | 列出事件(排除多变量) |
| GET | /events/{event_ticker} | event_ticker, with_nested_markets | 获取特定事件 |
| GET | /events/{event_ticker}/metadata | event_ticker | 仅获取事件元数据 |
| GET | /events/multivariate | limit, cursor, series_ticker, collection_ticker, with_nested_markets | 列出多变量(组合)事件 |
市场
| 方法 | 端点 | 主要参数 | 描述 |
|---|---|---|---|
| GET | /markets | limit, cursor, status, ticker, event_ticker, series_ticker, min_close_ts, max_close_ts | 列出/过滤市场 |
| GET | /markets/{ticker} | ticker | 获取特定市场详情 |
| GET | /markets/{ticker}/orderbook | ticker, depth | 当前订单簿(是买价 + 否买价) |
| GET | /markets/orderbooks | tickers (数组,最多100) | 批量订单簿 |
| GET | /markets/trades | ticker, limit, cursor, min_ts, max_ts | 跨市场交易 |
K线图
| 方法 | 端点 | 主要参数 | 描述 |
|---|---|---|---|
| GET | /series/{series_ticker}/markets/{ticker}/candlesticks | series_ticker, ticker, start_ts, end_ts, period_interval | 市场级 K 线 |
| GET | /series/{series_ticker}/events/{ticker}/candlesticks | series_ticker, ticker, start_ts, end_ts, period_interval | 聚合事件级 K 线 |
| GET | /markets/candlesticks | market_tickers, start_ts, end_ts, period_interval | 批量 K 线 |
period_interval 值:1 (1 分钟), 60 (1 小时), 1440 (1 天)
预测与实时数据
| 方法 | 端点 | 主要参数 | 描述 |
|---|---|---|---|
| GET | /series/{series_ticker}/events/{ticker}/forecast_percentile_history | percentiles (0-10000), start_ts, end_ts, period_interval | 历史预测百分位数 |
| GET | /live_data/milestone/{milestone_id} | milestone_id, include_player_stats | 实时里程碑数据 |
| GET | /live_data/batch | milestone_ids (数组,最多100), include_player_stats | 批量实时数据 |
| GET | /live_data/game-stats/{milestone_id} | milestone_id | 逐回合统计(足球、篮球、足球、曲棍球、棒球) |
系列
| 方法 | 端点 | 主要参数 | 描述 |
|---|---|---|---|
| GET | /series/{series_ticker} | series_ticker, include_volume | 获取系列模板 |
| GET | /series | category, tags, include_volume, min_updated_ts | 列出所有系列 |
交易所信息
| 方法 | 端点 | 主要参数 | 描述 |
|---|---|---|---|
| GET | /exchange/status | — | 当前交易所状态 |
| GET | /exchange/schedule | — | 营业时间 |
| GET | /exchange/announcements | — | 平台公告 |
| GET | /exchange/user_data_timestamp | — | 数据同步时间戳 |
| GET | /series/fee_changes | series_ticker, show_historical | 费用变更历史 |
搜索与发现
| 方法 | 端点 | 主要参数 | 描述 |
|---|---|---|---|
| GET | /search/tags_by_categories | — | 按系列类别组织的标签 |
| GET | /search/filters_by_sport | — | 按运动项目组织的过滤器 |
订单(需认证)
| 方法 | 端点 | 主要参数 | 描述 |
|---|---|---|---|
| GET | /portfolio/orders | ticker, event_ticker, status, limit, cursor, subaccount | 列出用户订单 |
| GET | /portfolio/orders/{order_id} | order_id | 获取特定订单 |
| POST | /portfolio/orders | Body: ticker, action, side, type, count, yes_price/no_price | 创建订单 |
| DELETE | /portfolio/orders/{order_id} | order_id, subaccount | 取消订单 |
| POST | /portfolio/orders/{order_id}/amend | order_id, Body: 新的 count/price | 修改订单 |
| POST | /portfolio/orders/{order_id}/decrease | order_id, Body: 减少数量 | 减少订单数量 |
| POST | /portfolio/orders/batched | Body: 订单数组 | 批量创建(最大数量随层级变化) |
| DELETE | /portfolio/orders/batched | Body: 订单ID数组 | 批量取消 |
| GET | /portfolio/orders/queue_positions | market_tickers, event_ticker, subaccount | 所有休眠订单的队列位置 |
| GET | /portfolio/orders/{order_id}/queue_position | order_id | 特定订单的队列位置 |
订单 V2 — 事件市场订单(需认证,定点数)
| 方法 | 端点 | 主要参数 | 描述 |
|---|---|---|---|
| POST | /portfolio/events/orders | Body: 事件代码、市场方向、价格(定点数)、数量 | 创建 V2 订单 |
| POST | /portfolio/events/orders/batched | Body: V2 订单数组 | 批量创建 V2 |
| DELETE | /portfolio/events/orders/{order_id} | order_id, subaccount | 取消 V2 订单 |
| DELETE | /portfolio/events/orders/batched | Body: 订单ID数组 | 批量取消 V2 |
| POST | /portfolio/events/orders/{order_id}/amend | order_id, Body: 新数量/价格 | 修改 V2 订单 |
| POST | /portfolio/events/orders/{order_id}/decrease | order_id, Body: 新剩余数量 | 减少 V2 订单 |
订单组(需认证)
| 方法 | 端点 | 主要参数 | 描述 |
|---|---|---|---|
| GET | /portfolio/order_groups | subaccount | 列出所有订单组 |
| POST | /portfolio/order_groups/create | Body: 合约限制 | 创建订单组 |
| GET | /portfolio/order_groups/{id} | id, subaccount | 获取特定组 |
| DELETE | /portfolio/order_groups/{id} | id, subaccount | 删除组并取消所有订单 |
| PUT | /portfolio/order_groups/{id}/limit | id, Body: 新限制 | 更新合约限制 |
| PUT | /portfolio/order_groups/{id}/trigger | id, subaccount | 触发组(取消所有订单) |
| PUT | /portfolio/order_groups/{id}/reset | id, subaccount | 重置已匹配合约计数器 |
投资组合(需认证)
| 方法 | 端点 | 主要参数 | 描述 |
|---|---|---|---|
| GET | /portfolio/balance | subaccount | 余额与投资组合价值(以美分为单位) |
| GET | /portfolio/positions | cursor, limit, count_filter, ticker, event_ticker, subaccount | 用户持仓 |
| GET | /portfolio/fills | ticker, order_id, min_ts, max_ts, limit, cursor, subaccount | 所有交易成交 |
| GET | /portfolio/settlements | limit, cursor, ticker, event_ticker, min_ts, max_ts, subaccount | 结算历史 |
| GET | /portfolio/deposits | limit, cursor | 存款历史 |
| GET | /portfolio/withdrawals | limit, cursor | 取款历史 |
| GET | /portfolio/summary/total_resting_order_value | — | 总休眠订单价值 |