Communitygithub.com

Kalshi 預測市場 API

交易與查詢首個 CFTC 監管的預測市場交易所。二元是/否合約涵蓋政治、經濟、體育、天氣等真實世界事件,價格介於 1-99 美分。

Kalshi 預測市場 API 是什麼?

這項技能提供了與 Kalshi API 的完整介面,這是首個受美國商品期貨交易委員會 (CFTC) 監管的預測市場交易所。它允許代理程式交易二元是/否合約,這些合約的價格在 1 到 99 美分之間,反映了真實世界事件的隱含機率,例如經濟數據發布(例如 CPI、就業報告)、政治選舉以及 NHL 或英超等體育賽事。關鍵功能包括使用 RSA-PSS 簽名驗證進行安全訂單管理、透過系列(模板)→ 事件(特定實例)→ 市場(二元結果)的層級結構進行市場探索,以及對體育和系列型市場的專門處理,以繞過標準關鍵字搜尋的侷限性(該搜尋僅傳回多場比賽的串關套裝)。代理程式可以檢視價格、下單、管理投資組合以及存取即時數據,所有這些都透過易於整合的 RESTful 端點進行。價格以美分表示,合約以 1.00 美元(100 美分)結算。

相容平台~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 美分。

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 等

已知的體育系列代碼:

體育項目系列代碼範例
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。必須使用帶 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/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列出多元(組合)事件

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跨市場交易記錄

Candlesticks

方法端點主要參數描述
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逐場比賽統計(足球、籃球、足球、冰球、棒球)

Series

方法端點主要參數描述
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特定訂單佇列位置

Orders V2 — Event-Market Orders(需驗證,定點數)

方法端點主要參數描述
POST/portfolio/events/ordersBody: event ticker, market side, price (定點數), count建立 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: 新的 count/price修改 V2 訂單
POST/portfolio/events/orders/{order_id}/decreaseorder_id, Body: 新的剩餘 count減少 V2 訂單

訂單群組(需驗證)

方法端點主要參數描述
GET/portfolio/order_groupssubaccount列出所有訂單群組
POST/portfolio/order_groups/createBody: contracts limit建立訂單群組
GET/portfolio/order_groups/{id}id, subaccount獲取特定群組
DELETE/portfolio/order_groups/{id}id, subaccount刪除群組並取消所有訂單
PUT/portfolio/order_groups/{id}/limitid, Body: 新的 limit更新合約限制
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.

相關技能