Communitygithub.com

Kalshi API:预测市场交易技能

交易和查询首个CFTC监管的预测市场交易所。二元是与否合约,覆盖政治、经济、体育、天气等真实世界事件。

Kalshi API:预测市场交易技能 是什么?

这是一个专门用于与Kalshi预测市场交易所交互的AI智能体技能。Kalshi是美国商品期货交易委员会(CFTC)监管的平台,允许用户交易二元是与否合约,这些合约的定价基于事件发生的主观概率(1-99美分)。用户可以通过该技能查询市场数据(事件、市场、订单簿),管理投资组合,以及下达和修改订单。该技能的核心优势在于其层级化导航方法:必须遵循系列(Series)→ 事件(Event)→ 市场(Market)的路径,特别是对于体育和政治等类别,避免使用无效的关键词搜索。技能提供了完整的API端点和认证指南,使用RSA-PSS签名,并包含针对体育赛事、经济数据和政治竞选的特定市场代码。该技能适用于Claude Code、Cursor、Codex等AI智能体平台,能够显著提升Kalshi平台上的交易决策和市场分析效率。

兼容平台~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/Starchild-ai-agent/official-skills/tree/HEAD/kalshi

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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等

已知体育系列代码:

体育项目系列代码示例
NHLKXNHLGAMEKXNHLGAME-25MAY12EDMORL
NBAKXNBAGAMEKXNBAGAME-25MAY12BOSLAL
NFLKXNFLGAMEKXNFLGAME-25SEP07KCDET
MLBKXMLBGAMEKXMLBGAME-25MAY12NYYLAD
EPL(英超)KXEPLGAMEKXEPLGAME-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-KEYAPI 密钥 ID($KALSHI_ACCESS_KEY)
KALSHI-ACCESS-SIGNATUREtimestamp + method + path 的 RSA-PSS 签名
KALSHI-ACCESS-TIMESTAMPUnix 时间戳(毫秒)

公共 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/eventslimit (1-200), cursor, status, series_ticker, with_nested_markets列出事件(排除多变量)
GET/events/{event_ticker}event_ticker, with_nested_markets获取特定事件
GET/events/{event_ticker}/metadataevent_ticker仅获取事件元数据
GET/events/multivariatelimit, cursor, series_ticker, collection_ticker, with_nested_markets列出多变量(组合)事件

市场

方法端点主要参数描述
GET/marketslimit, cursor, status, ticker, event_ticker, series_ticker, min_close_ts, max_close_ts列出/过滤市场
GET/markets/{ticker}ticker获取特定市场详情
GET/markets/{ticker}/orderbookticker, depth当前订单簿(是买价 + 否买价)
GET/markets/orderbookstickers (数组,最多100)批量订单簿
GET/markets/tradesticker, limit, cursor, min_ts, max_ts跨市场交易

K线图

方法端点主要参数描述
GET/series/{series_ticker}/markets/{ticker}/candlesticksseries_ticker, ticker, start_ts, end_ts, period_interval市场级 K 线
GET/series/{series_ticker}/events/{ticker}/candlesticksseries_ticker, ticker, start_ts, end_ts, period_interval聚合事件级 K 线
GET/markets/candlesticksmarket_tickers, start_ts, end_ts, period_interval批量 K 线

period_interval 值:1 (1 分钟), 60 (1 小时), 1440 (1 天)

预测与实时数据

方法端点主要参数描述
GET/series/{series_ticker}/events/{ticker}/forecast_percentile_historypercentiles (0-10000), start_ts, end_ts, period_interval历史预测百分位数
GET/live_data/milestone/{milestone_id}milestone_id, include_player_stats实时里程碑数据
GET/live_data/batchmilestone_ids (数组,最多100), include_player_stats批量实时数据
GET/live_data/game-stats/{milestone_id}milestone_id逐回合统计(足球、篮球、足球、曲棍球、棒球)

系列

方法端点主要参数描述
GET/series/{series_ticker}series_ticker, include_volume获取系列模板
GET/seriescategory, tags, include_volume, min_updated_ts列出所有系列

交易所信息

方法端点主要参数描述
GET/exchange/status—当前交易所状态
GET/exchange/schedule—营业时间
GET/exchange/announcements—平台公告
GET/exchange/user_data_timestamp—数据同步时间戳
GET/series/fee_changesseries_ticker, show_historical费用变更历史

搜索与发现

方法端点主要参数描述
GET/search/tags_by_categories—按系列类别组织的标签
GET/search/filters_by_sport—按运动项目组织的过滤器

订单(需认证)

方法端点主要参数描述
GET/portfolio/ordersticker, event_ticker, status, limit, cursor, subaccount列出用户订单
GET/portfolio/orders/{order_id}order_id获取特定订单
POST/portfolio/ordersBody: ticker, action, side, type, count, yes_price/no_price创建订单
DELETE/portfolio/orders/{order_id}order_id, subaccount取消订单
POST/portfolio/orders/{order_id}/amendorder_id, Body: 新的 count/price修改订单
POST/portfolio/orders/{order_id}/decreaseorder_id, Body: 减少数量减少订单数量
POST/portfolio/orders/batchedBody: 订单数组批量创建(最大数量随层级变化)
DELETE/portfolio/orders/batchedBody: 订单ID数组批量取消
GET/portfolio/orders/queue_positionsmarket_tickers, event_ticker, subaccount所有休眠订单的队列位置
GET/portfolio/orders/{order_id}/queue_positionorder_id特定订单的队列位置

订单 V2 — 事件市场订单(需认证,定点数)

方法端点主要参数描述
POST/portfolio/events/ordersBody: 事件代码、市场方向、价格(定点数)、数量创建 V2 订单
POST/portfolio/events/orders/batchedBody: V2 订单数组批量创建 V2
DELETE/portfolio/events/orders/{order_id}order_id, subaccount取消 V2 订单
DELETE/portfolio/events/orders/batchedBody: 订单ID数组批量取消 V2
POST/portfolio/events/orders/{order_id}/amendorder_id, Body: 新数量/价格修改 V2 订单
POST/portfolio/events/orders/{order_id}/decreaseorder_id, Body: 新剩余数量减少 V2 订单

订单组(需认证)

方法端点主要参数描述
GET/portfolio/order_groupssubaccount列出所有订单组
POST/portfolio/order_groups/createBody: 合约限制创建订单组
GET/portfolio/order_groups/{id}id, subaccount获取特定组
DELETE/portfolio/order_groups/{id}id, subaccount删除组并取消所有订单
PUT/portfolio/order_groups/{id}/limitid, Body: 新限制更新合约限制
PUT/portfolio/order_groups/{id}/triggerid, subaccount触发组(取消所有订单)
PUT/portfolio/order_groups/{id}/resetid, subaccount重置已匹配合约计数器

投资组合(需认证)

方法端点主要参数描述
GET/portfolio/balancesubaccount余额与投资组合价值(以美分为单位)
GET/portfolio/positionscursor, limit, count_filter, ticker, event_ticker, subaccount用户持仓
GET/portfolio/fillsticker, order_id, min_ts, max_ts, limit, cursor, subaccount所有交易成交
GET/portfolio/settlementslimit, cursor, ticker, event_ticker, min_ts, max_ts, subaccount结算历史
GET/portfolio/depositslimit, cursor存款历史
GET/portfolio/withdrawalslimit, cursor取款历史
GET/portfolio/summary/total_resting_order_value—总休眠订单价值

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

相关技能