Kalshi API
交易與查詢首個 CFTC 監管的預測市場交易所。二元是/否合約,針對真實世界事件定價 1-99 美分。
Base URL: https://external-api.kalshi.com/trade-api/v2
Demo URL: https://external-api.demo.kalshi.co/trade-api/v2
請在 https://kalshi.com/account/api-keys 取得您的 API 金鑰(需要 Premier 或 Market Maker 等級)
關鍵概念
層級結構:Series > Events > Markets
- Series — 重複性事件模板(例如「月度就業報告」、「每週初次請領失業救濟金人數」)
- Events — 系列中的特定實例(例如「2026年5月就業報告」)
- Markets — 事件中的個別二元結果(例如「新增就業人數是否高於 20 萬?」)
二元合約定價
- 價格以美分為單位(1-99),代表隱含機率
- 65 美分的「是」合約 = 市場隱含 65% 的機率
- 價格 X 的「是」買單等同於價格 (100 - X) 的「否」賣單 — 訂單簿僅顯示「是」買單和「否」買單
- 結算:若結果為「是」,支付 1.00 美元(100 美分);若結果為「否」,支付 0 美元
- 所有貨幣價值(餘額、價格、結算金額)均以美分為單位
代碼格式
- Series:
KXBTC,KXJOBLESS,KXINX - Event:
KXBTC-25MAY30(系列 + 日期) - Market:
KXBTC-25MAY30-T100000(事件 + 閾值/結果)
體育賽事代碼遵循不同的模式:{SERIES}-{YYMONDD}{TEAM1}{TEAM2}-{TEAM}
- 範例:
KXNHLGAME-25MAY12EDMORL-EDM(NHL,2025年5月12日,埃德蒙頓 vs 奧蘭多,埃德蒙頓獲勝) - 每個賽事事件有兩個互斥的「是」市場 — 每隊一個
關鍵:基於系列的市場導覽
對於體育、選舉或任何基於系列的類別,請勿使用 /markets?keyword=。 它只會顯示多場比賽的串關套裝,而非實際的賽事級市場。搜尋「NHL」、「Fulham」、「Premier League」等將回傳零個或不相關的結果。
始終遵循導覽路徑:Series → Events → Markets。 賽事級市場位於系列/事件層級結構之下,必須透過 /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。必須使用帶 SHA256 的 PSS。
- 簽名前去除查詢字串 — 簽名僅基於裸路徑計算(例如
/trade-api/v2/portfolio/balance),而非/trade-api/v2/portfolio/balance?param=value。包含查詢字串會導致 401。 - 金鑰環境變數格式 —
KALSHI_PRIVATE_KEY接受:原始 base64 主體、帶真實換行符的完整 PEM、或換行符被壓縮成空白的完整 PEM(常見於透過網頁表單貼上時)。輔助函數會自動標準化所有格式。為獲得最穩健的儲存方式,請在.env中將其儲存為帶有\n逸出序列的雙引號多行 PEM,以便 python-dotenv 將其還原為真正的 PEM 字串。
API 規範
完整 OpenAPI 規範:https://docs.kalshi.com/openapi.yaml
意圖路由
將使用者意圖映射到正確的端點。所有路徑均相對於 Base URL。
Events
| 方法 | 端點 | 主要參數 | 描述 |
|---|---|---|---|
| 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 | 列出多元(組合)事件 |
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 | 跨市場交易記錄 |
Candlesticks
| 方法 | 端點 | 主要參數 | 描述 |
|---|---|---|---|
| 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 | 逐場比賽統計(足球、籃球、足球、冰球、棒球) |
Series
| 方法 | 端點 | 主要參數 | 描述 |
|---|---|---|---|
| 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 | 特定訂單佇列位置 |
Orders V2 — Event-Market Orders(需驗證,定點數)
| 方法 | 端點 | 主要參數 | 描述 |
|---|---|---|---|
| POST | /portfolio/events/orders | Body: event ticker, market side, price (定點數), count | 建立 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: 新的 count/price | 修改 V2 訂單 |
| POST | /portfolio/events/orders/{order_id}/decrease | order_id, Body: 新的剩餘 count | 減少 V2 訂單 |
訂單群組(需驗證)
| 方法 | 端點 | 主要參數 | 描述 |
|---|---|---|---|
| GET | /portfolio/order_groups | subaccount | 列出所有訂單群組 |
| POST | /portfolio/order_groups/create | Body: contracts limit | 建立訂單群組 |
| GET | /portfolio/order_groups/{id} | id, subaccount | 獲取特定群組 |
| DELETE | /portfolio/order_groups/{id} | id, subaccount | 刪除群組並取消所有訂單 |
| PUT | /portfolio/order_groups/{id}/limit | id, Body: 新的 limit | 更新合約限制 |
| 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 | — | 總掛單價值 |
(由於原始內容被截斷,此處根據上下文推斷為「總掛單價值」。完整的原始內容應包含更多細節。)