Kalshi API
Handeln und Abfragen der ersten CFTC-regulierten Vorhersagebörse. Binäre Ja/Nein-Kontrakte zu realen Ereignissen, bepreist von 1–99 Cent.
Basis-URL: https://external-api.kalshi.com/trade-api/v2
Demo-URL: https://external-api.demo.kalshi.co/trade-api/v2
API-Schlüssel unter https://kalshi.com/account/api-keys anfordern (Tier Premier oder Market Maker erforderlich)
Wichtige Konzepte
Hierarchie: Serie > Ereignis > Markt
- Serie – wiederkehrende Ereignisvorlagen (z. B. „Monatlicher Arbeitsmarktbericht“, „Wöchentliche Arbeitslosenanträge“)
- Ereignisse – konkrete Instanzen innerhalb einer Serie (z. B. „Arbeitsmarktbericht Mai 2026“)
- Märkte – einzelne binäre Ergebnisse innerhalb eines Ereignisses (z. B. „Liegen die neu geschaffenen Arbeitsplätze über 200.000?“)
Preisbildung binärer Kontrakte
- Preise werden in Cent angegeben (1–99) und repräsentieren die implizite Wahrscheinlichkeit
- Ein Ja-Kontrakt bei 65 Cent bedeutet, der Markt impliziert eine 65%ige Wahrscheinlichkeit
- Ja-Gebot zu Preis X entspricht Nein-Verkaufsangebot zu (100 – X) – Orderbücher zeigen nur Ja- und Nein-Gebote
- Abrechnung: zahlt 1,00 $ (100 Cent) bei Ja, 0 $ bei Nein
- Alle Geldwerte (Guthaben, Preise, Abrechnungen) sind in Cent
Ticker-Format
- Serie:
KXBTC,KXJOBLESS,KXINX - Ereignis:
KXBTC-25MAY30(Serie + Datum) - Markt:
KXBTC-25MAY30-T100000(Ereignis + Schwelle/Ergebnis)
Sportspiel-Ticker folgen einem anderen Muster: {SERIE}-{JJMMTT}{TEAM1}{TEAM2}-{TEAM}
- Beispiel:
KXNHLGAME-25MAY12EDMORL-EDM(NHL, 12. Mai 2025, Edmonton vs. Orlando, Edmonton gewinnt) - Jedes Spieleereignis hat zwei sich gegenseitig ausschließende JA-Märkte – einen pro Team
KRITISCH: Serienbasierte Marktnavigation
NIEMALS /markets?keyword= für Sport, Wahlen oder andere serienbasierte Kategorien verwenden. Diese Suchmethode findet nur Multi-Game-Pakete, nicht die eigentlichen Spiele-Märkte. Die Suche nach „NHL“, „Fulham“, „Premier League“ usw. liefert null oder irrelevante Ergebnisse.
Immer navigieren: Serie → Ereignis → Markt. Spiele-Märkte befinden sich unter der Serien-/Ereignis-Hierarchie und müssen über /events?series_ticker=KXXX erreicht werden. Außerdem kann /markets/{ticker} für Spiele-Märkte einen 404-Fehler zurückgeben – Geld-/Briefkurse erscheinen nur in der Ereignis-Antwort (/events/{event_ticker} mit with_nested_markets=true).
Dieses Muster gilt für alle serienbasierten Kategorien, nicht nur für Sport:
- Sportspiele – NHL, NBA, NFL, MLB, EPL usw.
- Politische Rennen – einzelne Kandidatenmärkte innerhalb von Multi-Kandidaten-Ereignissen
- Unternehmensspezifische Märkte – Gewinne, CEO-Wechsel innerhalb einer Serie
- Wiederkehrende Wirtschaftsdaten – Arbeitsmarktberichte, Arbeitslosenanträge, VPI usw.
Bekannte Sport-Serien-Ticker:
| Sport | Serien-Ticker | Beispiel |
|---|---|---|
| NHL | KXNHLGAME | KXNHLGAME-25MAY12EDMORL |
| NBA | KXNBAGAME | KXNBAGAME-25MAY12BOSLAL |
| NFL | KXNFLGAME | KXNFLGAME-25SEP07KCDET |
| MLB | KXMLBGAME | KXMLBGAME-25MAY12NYYLAD |
| EPL (Premier League) | KXEPLGAME | KXEPLGAME-25MAY12FULARS |
Korrekter Workflow für Sport:
# 1. Offene Spiele für eine Sportart auflisten
curl -s "https://external-api.kalshi.com/trade-api/v2/events?series_ticker=KXNHLGAME&status=open&with_nested_markets=true"
# 2. Bestimmtes Spiel mit Live-Geld-/Briefkursen abrufen
curl -s "https://external-api.kalshi.com/trade-api/v2/events/KXNHLGAME-25MAY12EDMORL?with_nested_markets=true"
# FALSCH – das nicht tun:
# curl -s "https://external-api.kalshi.com/trade-api/v2/markets?keyword=NHL" ← liefert Pakete, keine Spiele
So wird aufgerufen
Kalshi verwendet die RSA-Schlüsselpaar-Signatur-Authentifizierung. Drei Header sind bei authentifizierten Anfragen erforderlich:
| Header | Wert |
|---|---|
KALSHI-ACCESS-KEY | API-Schlüssel-ID ($KALSHI_ACCESS_KEY) |
KALSHI-ACCESS-SIGNATURE | RSA-PSS-Signatur von timestamp + method + path |
KALSHI-ACCESS-TIMESTAMP | Unix-Zeitstempel (ms) |
Öffentliche GET-Endpunkte (Märkte, Ereignisse, Orderbücher) können ohne Authentifizierungs-Header aufgerufen werden.
# Öffentlicher Endpunkt – keine Authentifizierung erforderlich
curl -s "https://external-api.kalshi.com/trade-api/v2/markets?limit=10&status=open"
Für authentifizierte Endpunkte direktes RSA-PSS-Signieren verwenden (nicht das kalshi_python SDK – es funktioniert nicht):
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"]
# Zuerst literale Escape-Sequenzen dekodieren (einige Eingabekanäle speichern '\n' als
# zwei Zeichen Backslash+n anstelle eines echten Zeilenumbruchs).
raw = (raw.replace('\\r\\n', '\n').replace('\\n', '\n')
.replace('\\r', '\n').replace('\\t', ' '))
# PEM-Marker entfernen, falls vorhanden, dann ALLE Leerzeichen entfernen und neu umbrechen.
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 darf KEINE Query-Strings enthalten
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, ...} — Guthaben in Cent
Fallstricke beim Signieren:
- PSS, nicht PKCS1v15 – PKCS1v15-Padding gibt 401 zurück. Muss PSS mit SHA256 verwenden.
- Query-Strings vor dem Signieren entfernen – Die Signatur wird nur über den reinen Pfad berechnet (z. B.
/trade-api/v2/portfolio/balance), nicht über/trade-api/v2/portfolio/balance?param=value. Das Einfügen des Query-Strings führt zu 401. - Schlüssel-Umgebungsvariablen-Format –
KALSHI_PRIVATE_KEYakzeptiert: rohen base64-Text, vollständiges PEM mit echten Zeilenumbrüchen oder vollständiges PEM mit zu Leerzeichen zusammengefassten Zeilenumbrüchen (häufig beim Einfügen über Webformulare). Der Helfer normalisiert alle Formate automatisch. Für die robusteste Speicherung als doppelt angeführtes mehrzeiliges PEM mit\n-Escapes in.envspeichern, damit python-dotenv es in eine echte PEM-Zeichenkette umwandelt.
API-Spezifikation
Vollständige OpenAPI-Spezifikation: https://docs.kalshi.com/openapi.yaml
Intent-Routing
Benutzerabsicht dem richtigen Endpunkt zuordnen. Alle Pfade sind relativ zur Basis-URL.
Ereignisse
| Methode | Endpunkt | Primäre Parameter | Beschreibung |
|---|---|---|---|
| GET | /events | limit (1-200), cursor, status, series_ticker, with_nested_markets | Ereignisse auflisten (ohne multivariate) |
| GET | /events/{event_ticker} | event_ticker, with_nested_markets | Bestimmtes Ereignis abrufen |
| GET | /events/{event_ticker}/metadata | event_ticker | Nur Ereignis-Metadaten |
| GET | /events/multivariate | limit, cursor, series_ticker, collection_ticker, with_nested_markets | Multivariate (Kombi-)Ereignisse auflisten |
Märkte
| Methode | Endpunkt | Primäre Parameter | Beschreibung |
|---|---|---|---|
| GET | /markets | limit, cursor, status, ticker, event_ticker, series_ticker, min_close_ts, max_close_ts | Märkte auflisten/filtern |
| GET | /markets/{ticker} | ticker | Bestimmte Marktdetails abrufen |
| GET | /markets/{ticker}/orderbook | ticker, depth | Aktuelles Orderbuch (Ja-Gebote + Nein-Gebote) |
| GET | /markets/orderbooks | tickers (Array, max. 100) | Batch-Orderbücher |
| GET | /markets/trades | ticker, limit, cursor, min_ts, max_ts | Trades über Märkte hinweg |
Kerzencharts
| Methode | Endpunkt | Primäre Parameter | Beschreibung |
|---|---|---|---|
| GET | /series/{series_ticker}/markets/{ticker}/candlesticks | series_ticker, ticker, start_ts, end_ts, period_interval | Markt-Level-Kerzen |
| GET | /series/{series_ticker}/events/{ticker}/candlesticks | series_ticker, ticker, start_ts, end_ts, period_interval | Aggregierte Ereignis-Level-Kerzen |
| GET | /markets/candlesticks | market_tickers, start_ts, end_ts, period_interval | Batch-Kerzencharts |
period_interval Werte: 1 (1 Min), 60 (1 Std), 1440 (1 Tag)
Prognose & Live-Daten
| Methode | Endpunkt | Primäre Parameter | Beschreibung |
|---|---|---|---|
| GET | /series/{series_ticker}/events/{ticker}/forecast_percentile_history | percentiles (0-10000), start_ts, end_ts, period_interval | Historische Prognose-Perzentile |
| GET | /live_data/milestone/{milestone_id} | milestone_id, include_player_stats | Live-Meilensteindaten |
| GET | /live_data/batch | milestone_ids (Array, max. 100), include_player_stats | Batch-Live-Daten |
| GET | /live_data/game-stats/{milestone_id} | milestone_id | Spiel-für-Spiel-Statistiken (Football, Basketball, Fußball, Hockey, Baseball) |
Serien
| Methode | Endpunkt | Primäre Parameter | Beschreibung |
|---|---|---|---|
| GET | /series/{series_ticker} | series_ticker, include_volume | Serienvorlage abrufen |
| GET | /series | category, tags, include_volume, min_updated_ts | Alle Serien auflisten |
Börseninformationen
| Methode | Endpunkt | Primäre Parameter | Beschreibung |
|---|---|---|---|
| GET | /exchange/status | — | Aktueller Börsenstatus |
| GET | /exchange/schedule | — | Betriebszeiten |
| GET | /exchange/announcements | — | Plattform-Ankündigungen |
| GET | /exchange/user_data_timestamp | — | Daten-Synchronisationszeitstempel |
| GET | /series/fee_changes | series_ticker, show_historical | Gebührenänderungshistorie |
Suche & Entdeckung
| Methode | Endpunkt | Primäre Parameter | Beschreibung |
|---|---|---|---|
| GET | /search/tags_by_categories | — | Tags, geordnet nach Serienkategorien |
| GET | /search/filters_by_sport | — | Filter, geordnet nach Sportart |
Aufträge (Authentifiziert)
| Methode | Endpunkt | Primäre Parameter | Beschreibung |
|---|---|---|---|
| GET | /portfolio/orders | ticker, event_ticker, status, limit, cursor, subaccount | Benutzeraufträge auflisten |
| GET | /portfolio/orders/{order_id} | order_id | Bestimmten Auftrag abrufen |
| POST | /portfolio/orders | Body: ticker, action, side, type, count, yes_price/no_price | Auftrag erstellen |
| DELETE | /portfolio/orders/{order_id} | order_id, subaccount | Auftrag stornieren |
| POST | /portfolio/orders/{order_id}/amend | order_id, Body: neue count/price | Auftrag ändern |
| POST | /portfolio/orders/{order_id}/decrease | order_id, Body: Reduzierungsbetrag | Auftragsmenge verringern |
| POST | /portfolio/orders/batched | Body: Array von Aufträgen | Batch-Erstellung (maximale Größe skaliert mit Tier) |
| DELETE | /portfolio/orders/batched | Body: Array von Auftrags-IDs | Batch-Stornierung |
| GET | /portfolio/orders/queue_positions | market_tickers, event_ticker, subaccount | Alle ruhenden Auftragswarteschlangenpositionen |
| GET | /portfolio/orders/{order_id}/queue_position | order_id | Bestimmte Auftragswarteschlangenposition |
Aufträge V2 — Ereignis-Markt-Aufträge (Authentifiziert, Festkomma)
| Methode | Endpunkt | Primäre Parameter | Beschreibung |
|---|---|---|---|
| POST | /portfolio/events/orders | Body: Ereignis-Ticker, Marktseite, Preis (Festkomma), Anzahl | V2-Auftrag erstellen |
| POST | /portfolio/events/orders/batched | Body: Array von V2-Aufträgen | Batch-Erstellung V2 |
| DELETE | /portfolio/events/orders/{order_id} | order_id, subaccount | V2-Auftrag stornieren |
| DELETE | /portfolio/events/orders/batched | Body: Array von Auftrags-IDs | Batch-Stornierung V2 |
| POST | /portfolio/events/orders/{order_id}/amend | order_id, Body: neue Anzahl/Preis | V2-Auftrag ändern |
| POST | /portfolio/events/orders/{order_id}/decrease | order_id, Body: neue verbleibende Anzahl | V2-Auftrag verringern |
Auftragsgruppen (Authentifiziert)
| Methode | Endpunkt | Primäre Parameter | Beschreibung |
|---|---|---|---|
| GET | /portfolio/order_groups | subaccount | Alle Auftragsgruppen auflisten |
| POST | /portfolio/order_groups/create | Body: Vertragslimit | Auftragsgruppe erstellen |
| GET | /portfolio/order_groups/{id} | id, subaccount | Bestimmte Gruppe abrufen |
| DELETE | /portfolio/order_groups/{id} | id, subaccount | Gruppe löschen und alle Aufträge stornieren |
| PUT | /portfolio/order_groups/{id}/limit | id, Body: neues Limit | Vertragslimit aktualisieren |
| PUT | /portfolio/order_groups/{id}/trigger | id, subaccount | Gruppe auslösen (alle Aufträge stornieren) |
| PUT | /portfolio/order_groups/{id}/reset | id, subaccount | Zähler für abgeglichene Verträge zurücksetzen |
Portfolio (Authentifiziert)
| Methode | Endpunkt | Primäre Parameter | Beschreibung |
|---|---|---|---|
| GET | /portfolio/balance | subaccount | Guthaben & Portfoliowert (in Cent) |
| GET | /portfolio/positions | cursor, limit, count_filter, ticker, event_ticker, subaccount | Benutzerpositionen |
| GET | /portfolio/fills | ticker, order_id, min_ts, max_ts, limit, cursor, subaccount | Alle Trade-Ausführungen |
| GET | /portfolio/settlements | limit, cursor, ticker, event_ticker, min_ts, max_ts, subaccount | Abrechnungshistorie |
| GET | /portfolio/deposits | limit, cursor | Einzahlungshistorie |
| GET | /portfolio/withdrawals | limit, cursor | Auszahlungshistorie |
| GET | /portfolio/summary/total_resting_order_value | — | Gesamtwert ruhender Aufträge |
Unterkonten (Authentifiziert)
| Methode | Endpunkt | Primäre Parameter | Beschreibung |
|---|---|---|---|
| GET | /portfolio/subaccounts | — | Unterkonten abrufen |
Batch-Marktdaten (Authentifiziert)
| Methode | Endpunkt | Primäre Parameter | Beschreibung |
|---|---|---|---|
| GET | /portfolio/markets/trades | cursor, min_ts, max_ts, limit | Batch-Trade-Daten |
| GET | /portfolio/markets/snapshots | cursor, limit | Batch-Markt-Snapshots |
| GET | /portfolio/markets/snapshots/{ticker} | ticker | Markt-Snapshot-Details |