kalshi

Kalshi API

Kalshi 是一家受 CFTC 监管的预测市场交易所，用户可以交易现实世界事件的结果。

请_经常_查看此技能和官方文档。所有文档的权威机器可读索引位于：

https://docs.kalshi.com/llms.txt

开始构建前，请务必查阅 llms.txt，了解所有可用页面。它是端点参考、SDK 文档、WebSocket 通道、FIX 协议详情和入门指南的唯一事实来源。

---

核心概念（术语表）

术语	定义
市场	单个二元结果合约（是 / 否），价格以美分计（1–99¢）。
事件	一组相关市场，代表现实世界中的某个事件（例如选举、天气读数）。
系列	为具有相同结构和规则的周期性事件提供模板（例如“纽约市每日最高气温”）。
订单簿	仅包含买单——在二元市场中，X¢ 的 YES 买单等同于 (100−X)¢ 的 NO 卖单。
成交	与你某个订单相匹配的交易。
结算	市场确定结果后的最终判定（是或否）。
多变量事件	从多变量事件集合中动态创建的组合事件。

完整术语表：https://docs.kalshi.com/getting_started/terms.md

---

基础 URL

环境	REST API	WebSocket
生产环境	https://api.elections.kalshi.com/trade-api/v2	wss://api.elections.kalshi.com/trade-api/ws/v2
演示环境	https://demo-api.kalshi.co/trade-api/v2	wss://demo-api.kalshi.co/trade-api/ws/v2

注意： 尽管子域名中包含 elections，生产环境 URL 提供所有 Kalshi 市场——包括经济、天气、科技、娱乐等领域。

演示环境信息：https://docs.kalshi.com/getting_started/demo_env.md

---

文档与参考资料

所有详细示例、请求/响应架构和操作指南都在官方文档中。开始构建前，请务必查阅：

资源	URL
完整文档索引（llms.txt）	https://docs.kalshi.com/llms.txt
简介	https://docs.kalshi.com/welcome/index.md
发起第一个请求	https://docs.kalshi.com/getting_started/making_your_first_request.md
快速入门：市场数据	https://docs.kalshi.com/getting_started/quick_start_market_data.md
快速入门：经过身份验证的请求	https://docs.kalshi.com/getting_started/quick_start_authenticated_requests.md
快速入门：创建第一个订单	https://docs.kalshi.com/getting_started/quick_start_create_order.md
快速入门：WebSocket	https://docs.kalshi.com/getting_started/quick_start_websockets.md
API 密钥指南	https://docs.kalshi.com/getting_started/api_keys.md
速率限制与层级	https://docs.kalshi.com/getting_started/rate_limits.md
分页	https://docs.kalshi.com/getting_started/pagination.md
订单簿响应	https://docs.kalshi.com/getting_started/orderbook_responses.md
历史数据	https://docs.kalshi.com/getting_started/historical_data.md
子美分定价	https://docs.kalshi.com/getting_started/subpenny_pricing.md
定点合约	https://docs.kalshi.com/getting_started/fixed_point_contracts.md
OpenAPI 规范（YAML）	https://docs.kalshi.com/openapi.yaml
API 更新日志	https://docs.kalshi.com/changelog/index.md
Kalshi 平台	https://kalshi.com
演示平台	https://demo.kalshi.co

---

身份验证

Kalshi 使用 RSA-PSS 签名请求（而非 Bearer 令牌）。每个经过身份验证的请求都需要三个标头：

标头	值
KALSHI-ACCESS-KEY	你的 API Key ID
KALSHI-ACCESS-TIMESTAMP	当前 Unix 时间戳，单位为毫秒
KALSHI-ACCESS-SIGNATURE	{timestamp}{METHOD}{path} 的 Base64 编码 RSA-PSS 签名

**重要：**签名时，使用不含查询参数的路径。例如，即使请求 URL 为 /trade-api/v2/portfolio/orders?limit=5，也应对 /trade-api/v2/portfolio/orders 进行签名。

生成 API 密钥

1. 登录 → 账户设置 → API 密钥部分。
2. 点击“Create New API Key”以生成 RSA 密钥对。
3. 立即保存私钥——之后无法再次获取。

完整指南：https://docs.kalshi.com/getting_started/api_keys.md

Python 签名示例

import base64, datetime, requests
from cryptography.hazmat.primitives import serialization, hashes
from cryptography.hazmat.primitives.asymmetric import padding

def load_private_key(file_path):
    with open(file_path, "rb") as f:
        return serialization.load_pem_private_key(f.read(), password=None)

def sign_pss(private_key, text: str) -> str:
    sig = private_key.sign(
        text.encode("utf-8"),
        padding.PSS(mgf=padding.MGF1(hashes.SHA256()), salt_length=padding.PSS.DIGEST_LENGTH),
        hashes.SHA256(),
    )
    return base64.b64encode(sig).decode("utf-8")

def kalshi_headers(key_id, private_key, method, path):
    ts = str(int(datetime.datetime.now().timestamp() * 1000))
    path_no_qs = path.split("?")[0]
    sig = sign_pss(private_key, ts + method + path_no_qs)
    return {
        "KALSHI-ACCESS-KEY": key_id,
        "KALSHI-ACCESS-SIGNATURE": sig,
        "KALSHI-ACCESS-TIMESTAMP": ts,
    }

JavaScript 签名示例

const crypto = require("crypto");
const fs = require("fs");

function signPss(privateKeyPem, text) {
  const sign = crypto.createSign("RSA-SHA256");
  sign.update(text);
  sign.end();
  return sign.sign({
    key: privateKeyPem,
    padding: crypto.constants.RSA_PKCS1_PSS_PADDING,
    saltLength: crypto.constants.RSA_PSS_SALTLEN_DIGEST,
  }).toString("base64");
}

function kalshiHeaders(keyId, privateKeyPem, method, path) {
  const ts = Date.now().toString();
  const pathNoQs = path.split("?")[0];
  const sig = signPss(privateKeyPem, ts + method + pathNoQs);
  return {
    "KALSHI-ACCESS-KEY": keyId,
    "KALSHI-ACCESS-SIGNATURE": sig,
    "KALSHI-ACCESS-TIMESTAMP": ts,
  };
}

---

SDK

Kalshi 提供官方 SDK。生产环境集成建议优先使用这些 SDK：

SDK	安装	文档
Python（同步）	pip install kalshi_python_sync	https://docs.kalshi.com/sdks/python/quickstart.md
Python（异步）	pip install kalshi_python_async	https://docs.kalshi.com/sdks/python/quickstart.md
TypeScript	npm install kalshi-typescript	https://docs.kalshi.com/sdks/typescript/quickstart.md

旧版 kalshi-python 软件包已弃用。请迁移到 kalshi_python_sync 或 kalshi_python_async。

SDK 概览：https://docs.kalshi.com/sdks/overview.md

对于生产应用，可考虑根据 OpenAPI 规范生成自己的客户端。

---

速率限制

等级	读取	写入
Basic	20/s	10/s
Advanced	30/s	30/s
Premier	100/s	100/s
Prime	400/s	400/s

受写入限制的端点：CreateOrder、CancelOrder、AmendOrder、DecreaseOrder、BatchCreateOrders、BatchCancelOrders。在批量 API 中，每个项目计为 1 笔交易（BatchCancelOrders 除外，其中每次取消计为 0.2 笔交易）。

完整详情：https://docs.kalshi.com/getting_started/rate_limits.md

---

分页

该 API 使用基于游标的分页。响应中包含 cursor 字段；在下一次请求中将其作为 ?cursor={value} 传递。空值或 null 游标表示没有更多页面。默认页面大小为 100（最大值通常为 1000）。

完整指南：https://docs.kalshi.com/getting_started/pagination.md

---

REST API 端点概览

以下按领域整理了摘要。完整的请求/响应架构请参阅链接文档，或浏览 https://docs.kalshi.com/llms.txt。

市场

端点	方法	身份验证	描述
/markets	GET	否	列出市场，可按状态、系列和时间戳筛选。文档：获取市场列表
/markets/{ticker}	GET	否	根据 ticker 获取单个市场。文档：获取市场
/markets/{ticker}/orderbook	GET	否	获取当前订单簿（yes 买单 + no 买单）。文档：获取市场订单簿
/markets/{ticker}/candlesticks	GET	否	K 线数据（1m、1h、1d）。文档：获取市场 K 线
/markets/candlesticks	POST	否	批量获取最多 100 个 ticker 的 K 线数据。文档：批量获取市场 K 线
/markets/trades	GET	否	所有公开交易。文档：获取交易记录
/series/{ticker}	GET	否	获取一个系列。文档：获取系列
/series	GET	否	列出系列。文档：获取系列列表

事件

端点	方法	身份验证	描述
/events	GET	No	列出事件（不包括多变量事件）。文档：获取事件
/events/{ticker}	GET	No	获取单个事件。文档：获取事件
/events/{ticker}/metadata	GET	No	仅获取事件元数据。文档：获取事件元数据
/events/{ticker}/candlesticks	GET	No	获取聚合事件蜡烛图。文档：获取事件蜡烛图
/events/{ticker}/forecast/percentile_history	GET	No	获取预测百分位数历史记录。文档：获取事件预测百分位数历史记录
/events/multivariate	GET	No	列出多变量事件。文档：获取多变量事件

订单（需身份验证）

端点	方法	身份验证	描述
/portfolio/orders	POST	Yes	创建订单。文档：创建订单
/portfolio/orders	GET	Yes	列出你的订单（挂单／已取消／已执行）。文档：获取订单
/portfolio/orders/{order_id}	GET	Yes	获取单个订单。文档：获取订单
/portfolio/orders/{order_id}	DELETE	Yes	取消订单。文档：取消订单
/portfolio/orders/{order_id}/amend	POST	Yes	修改价格／数量。文档：修改订单
/portfolio/orders/{order_id}/decrease	POST	Yes	减少合约数量。文档：减少订单数量
/portfolio/orders/{order_id}/queue_position	GET	Yes	获取排队位置。文档：获取订单排队位置
/portfolio/orders/queue_positions	GET	Yes	获取所有挂单的排队位置。文档：获取订单排队位置
/portfolio/orders/batched	POST	Yes	批量创建订单（最多 20 个）。文档：批量创建订单
/portfolio/orders/batched	DELETE	Yes	批量取消订单（最多 20 个）。文档：批量取消订单

投资组合（需身份验证）

端点	方法	身份验证	描述
/portfolio/balance	GET	Yes	账户余额（美分）。文档：获取余额
/portfolio/positions	GET	Yes	市场持仓。文档：获取持仓
/portfolio/fills	GET	Yes	你的成交记录。文档：获取成交记录
/portfolio/settlements	GET	Yes	结算历史记录。文档：获取结算记录
/portfolio/resting_order_value	GET	Yes	挂单总价值（FCM）。文档：获取挂单总价值

子账户（已认证）

端点	方法	认证	描述
/portfolio/subaccounts	POST	是	创建子账户（最多 32 个）。文档：创建子账户
/portfolio/subaccounts/balances	GET	是	获取所有子账户余额。文档：获取所有子账户余额
/portfolio/subaccounts/transfers	GET	是	获取子账户转账历史记录。文档：获取子账户转账记录
/portfolio/subaccounts/transfer	POST	是	在子账户之间转账。文档：子账户间转账

订单组（已认证）

订单组适用滚动 15 秒合约数量限制；达到限制时，组内所有订单都会自动取消。

端点	方法	认证	描述
/portfolio/order_groups	POST	是	创建订单组。文档：创建订单组
/portfolio/order_groups	GET	是	列出订单组。文档：获取订单组
/portfolio/order_groups/{id}	GET	是	获取订单组。文档：获取订单组
/portfolio/order_groups/{id}	DELETE	是	删除订单组。文档：删除订单组
/portfolio/order_groups/{id}/reset	POST	是	重置计数器。文档：重置订单组
/portfolio/order_groups/{id}/trigger	POST	是	手动触发。文档：触发订单组
/portfolio/order_groups/{id}/limit	PUT	是	更新限制。文档：更新订单组限制

通信 / RFQ（已认证）

端点	方法	认证	描述
/communications/id	GET	是	获取你的通信 ID。文档：获取通信 ID
/rfqs	POST	是	创建 RFQ（最多 100 个未结 RFQ）。文档：创建 RFQ
/rfqs	GET	是	列出 RFQ。文档：获取 RFQ
/rfqs/{id}	GET	是	获取 RFQ。文档：获取 RFQ
/rfqs/{id}	DELETE	是	删除 RFQ。文档：删除 RFQ
/quotes	POST	是	创建报价。文档：创建报价
/quotes	GET	是	列出报价。文档：获取报价
/quotes/{id}	GET	是	获取报价。文档：获取报价
/quotes/{id}	DELETE	是	删除报价。文档：删除报价
/quotes/{id}/accept	POST	是	接受报价。文档：接受报价
/quotes/{id}/confirm	POST	是	确认报价。文档：确认报价

历史数据（已认证）

历史数据适用于已超过截止时间戳的归档市场、订单和成交记录。

Endpoint	Method	Auth	Description
/historical/cutoff_timestamps	GET	Yes	截止边界。文档：获取历史截止时间戳
/historical/markets	GET	Yes	归档市场。文档：获取历史市场
/historical/markets/{ticker}	GET	Yes	单个归档市场。文档：获取历史市场
/historical/markets/{ticker}/candlesticks	GET	Yes	归档蜡烛图。文档：获取历史市场蜡烛图
/historical/fills	GET	Yes	归档成交记录。文档：获取历史成交记录
/historical/orders	GET	Yes	归档订单。文档：获取历史订单

历史数据指南：https://docs.kalshi.com/getting_started/historical_data.md

多变量集合

Endpoint	Method	Auth	Description
/multivariate/collections	GET	No	列出集合。文档：获取多变量事件集合
/multivariate/collections/{ticker}	GET	No	获取集合。文档：获取多变量事件集合
/multivariate/collections/{ticker}/markets	POST	Yes	在集合中创建市场。文档：在多变量事件集合中创建市场
/multivariate/collections/{ticker}/lookup	GET	No	查询代码。文档：查询多变量事件集合中市场的代码
/multivariate/collections/{ticker}/lookup_history	GET	No	最近的查询记录。文档：获取多变量事件集合查询历史

里程碑和结构化目标

Endpoint	Method	Auth	Description
/milestones	GET	No	列出里程碑。文档：获取里程碑
/milestones/{id}	GET	No	获取里程碑。文档：获取里程碑
/structured_targets	GET	No	列出结构化目标。文档：获取结构化目标
/structured_targets/{id}	GET	No	获取结构化目标。文档：获取结构化目标

实时数据

Endpoint	Method	Auth	Description
/live_data/{milestone_id}	GET	No	里程碑的实时数据。文档：获取实时数据
/live_data	GET	No	多个里程碑。文档：获取多个里程碑的实时数据

搜索与发现

端点	方法	认证	描述
/search/sports/filters	GET	否	体育筛选条件。文档：获取体育筛选条件
/search/tags	GET	否	按类别列出标签。文档：获取系列类别的标签

交易所与账户

端点	方法	认证	描述
/exchange/status	GET	否	交易所状态。文档：获取交易所状态
/exchange/schedule	GET	否	交易所日程。文档：获取交易所日程
/exchange/announcements	GET	否	公告。文档：获取交易所公告
/exchange/data_timestamp	GET	是	数据更新时间戳。文档：获取用户数据时间戳
/exchange/series_fee_changes	GET	否	费用变更。文档：获取系列费用变更
/account/api_limits	GET	是	你的速率限制等级。文档：获取账户 API 限制
/account/api_keys	GET	是	列出 API 密钥。文档：获取 API 密钥
/account/api_keys	POST	是	创建 API 密钥。文档：创建 API 密钥
/account/api_keys/generate	POST	是	生成密钥对。文档：获取 API 密钥
/account/api_keys/{id}	DELETE	是	删除 API 密钥。文档：删除 API 密钥

激励计划

端点	方法	认证	描述
/incentives	GET	否	列出激励。文档：获取激励

---

WebSocket API

单个经过身份验证的 WebSocket 连接即可提供实时流数据。发送 JSON 命令即可订阅频道。

连接

wss://api.elections.kalshi.com/trade-api/ws/v2      (production)
wss://demo-api.kalshi.co/trade-api/ws/v2            (demo)

握手期间必须包含认证标头（KALSHI-ACCESS-KEY、KALSHI-ACCESS-SIGNATURE、KALSHI-ACCESS-TIMESTAMP）。对字符串 {timestamp}GET/trade-api/ws/v2 进行签名。

可用频道

频道	是否需要身份验证	说明	文档
ticker	否*	市场价格／成交量／未平仓量更新	市场行情
trade	否*	公开交易通知	公开交易
market_lifecycle_v2	否*	市场／事件状态变更	市场与事件生命周期
multivariate	否*	多变量查询通知	多变量查询
orderbook_delta	是	实时订单簿更新	订单簿更新
fill	是	您的成交通知	用户成交
order	是	您的订单更新	用户订单
market_positions	是	您的市场持仓更新	市场持仓
communications	是	RFQ／报价通知	通信
order_group_updates	是	订单组生命周期	订单组更新

*即使是公开频道，连接本身也始终需要身份验证。

订阅命令

{
  "id": 1,
  "cmd": "subscribe",
  "params": {
    "channels": ["ticker", "orderbook_delta"],
    "market_tickers": ["KXHIGHNY-24JAN01-T60"]
  }
}

保持连接

Kalshi 每 10 秒发送一次正文为 heartbeat 的 Ping 帧。客户端必须以 Pong 帧响应。文档：连接保活

完整 WebSocket 指南：https://docs.kalshi.com/getting_started/quick_start_websockets.md

---

订单簿结构

Kalshi 订单簿仅返回买单（无卖单）。在二元市场中：

• YES 买单，价格为 X¢ = NO 卖单，价格为 (100−X)¢
• NO 买单，价格为 Y¢ = YES 卖单，价格为 (100−Y)¢

每个条目都是按升序排列的 [price, quantity]。最优买单是最后一个元素。

价差计算：

• 最优 YES 卖价 = 100 - best_no_bid
• 价差 = 最优 YES 卖价 − 最优 YES 买价

完整指南：https://docs.kalshi.com/getting_started/orderbook_responses.md

---

FIX 协议

Kalshi 还支持金融信息交换（FIX）协议，用于低延迟交易：

主题	文档
概述	https://docs.kalshi.com/fix/index.md
连接	https://docs.kalshi.com/fix/connectivity.md
会话管理	https://docs.kalshi.com/fix/session-management.md
订单录入	https://docs.kalshi.com/fix/order-entry.md
订单组	https://docs.kalshi.com/fix/order-groups.md
Drop Copy	https://docs.kalshi.com/fix/drop-copy.md
市场结算	https://docs.kalshi.com/fix/market-settlement.md
RFQ 消息	https://docs.kalshi.com/fix/rfq-messages.md
错误处理	https://docs.kalshi.com/fix/error-handling.md
亚分定价	https://docs.kalshi.com/fix/subpenny-pricing.md

---

常见模式

获取某个系列的所有未平仓市场

curl -s "https://api.elections.kalshi.com/trade-api/v2/markets?series_ticker=KXHIGHNY&status=open" | jq '.markets[] | {ticker, title, yes_price, volume}'

获取某个市场的订单簿

curl -s "https://api.elections.kalshi.com/trade-api/v2/markets/KXHIGHNY-24JAN01-T60/orderbook" | jq '.orderbook'

翻页遍历所有结果

# First page
curl -s "https://api.elections.kalshi.com/trade-api/v2/markets?limit=100" > page1.json
# Extract cursor for next page
CURSOR=$(jq -r '.cursor' page1.json)
# Next page
curl -s "https://api.elections.kalshi.com/trade-api/v2/markets?limit=100&cursor=$CURSOR" > page2.json

---

使用技巧

• 始终先查看 llms.txt： https://docs.kalshi.com/llms.txt 包含所有端点和指南。
• 测试时请使用演示环境——其凭据与生产环境分开。
• 切勿将 API 密钥硬编码——请使用环境变量或安全的密钥存储。
• 价格以美分为单位（1–99）。WebSocket 仓位频道中的货币值以百分之一美分为单位（除以 10,000 即为美元）。
• 对不含查询参数的路径进行签名。 签名前删除 ? 之后的所有内容。
• 处理分页——始终检查 cursor 是否非空，并循环直到没有更多结果。
• 遵守速率限制——对 429 响应实施指数退避。
• 结合使用 REST 和 WebSocket以获得最准确的状态：使用 REST 获取初始快照，使用 WebSocket 获取实时增量。
• 订单簿仅包含买单——通过 100−价格的补数推导卖单。
• 历史数据与实时数据： 检查截止时间戳，以确定应查询实时端点还是历史端点。
• 市场状态值请使用：unopened、open、closed、settled。
• 批量操作中的每个项目都会计入每秒写入限制。

---

错误处理

适用标准 HTTP 错误代码。API 会返回包含详细消息的 JSON 错误正文。对于 429（速率受限）和 5xx（服务器错误），请实施带退避的重试。

WebSocket 错误代码

代码	含义
1	无法处理消息
2	需要参数
3	需要频道
5	未知命令
8	未知频道名称
9	需要身份验证
14	需要市场行情代码
16	未找到市场
17	内部错误
18	命令超时

完整错误代码表：https://docs.kalshi.com/getting_started/quick_start_websockets.md

---

示例项目：Alph Bot

Alph Bot 是一款开源自动化交易机器人，展示了如何以生产级质量集成 Kalshi API，并结合 Shipp 获取实时体育数据，使用 Claude AI 估算概率。

Alph Bot 如何使用 Kalshi

1. 市场发现——搜索与正在进行的体育比赛相关的 Kalshi 事件合约（例如 NBA 让分盘、大小分）。
2. 读取订单簿——获取订单簿数据，以确定当前市场隐含概率（以美分计价的价格直接对应隐含百分比）。
3. 优势检测——将 Kalshi 市场价格与基于 Claude 和 Shipp 实时比赛数据的 AI 估算概率进行比较。
4. 订单执行——发现足够优势时，使用凯利准则确定仓位规模并下达限价单。
5. 风险管理——实施熔断机制（每日最大亏损）、仓位规模限制、单一市场敞口上限和最低账户余额阈值。

Alph Bot 的 Kalshi 配置

摘自其 .env.example：

ALPH_BOT_KALSHI_API_KEY_ID=abc123
ALPH_BOT_KALSHI_PRIVATE_KEY_PATH=./keys/kalshi-private.pem

# Strategy
ALPH_BOT_MIN_EDGE_PCT=5
ALPH_BOT_MIN_CONFIDENCE=medium
ALPH_BOT_KELLY_FRACTION=0.25

# Risk controls
ALPH_BOT_MAX_TOTAL_EXPOSURE_USD=10000
ALPH_BOT_MAX_POSITION_SIZE_USD=1000
ALPH_BOT_MAX_SINGLE_MARKET_PERCENT=20
ALPH_BOT_MAX_DAILY_LOSS_USD=500
ALPH_BOT_MAX_DAILY_TRADES=50
ALPH_BOT_MIN_ACCOUNT_BALANCE_USD=100

试用

git clone https://gitlab.com/outsharp/shipp/alph-bot.git
cd alph-bot
cp .env.example .env
# Add your Kalshi, Shipp, and Anthropic API keys

yarn migrate

# Find a game to trade on
./index.ts available-games --sport NBA

# Run value betting in demo mode (uses Kalshi demo environment)
./index.ts value-bet -d --game <GAME_ID>

# Run in paper mode (no real orders executed)
./index.ts value-bet --paper --game <GAME_ID>

警告： 不在演示／模拟模式下时，Kalshi 交易涉及真实资金。请始终从演示账户开始。

完整设置说明请参阅 Alph Bot README。

---

版本管理

当前 API 版本为 /trade-api/v2 下的 v2。请关注 API 更新日志以获取更新。SDK 版本与 OpenAPI 规范保持一致，通常每周发布。