Kalshi Api

Kalshi API

Trade and query the first CFTC-regulated prediction market exchange. Binary yes/no contracts on real-world events priced 1-99 cents.

Base URL: https://external-api.kalshi.com/trade-api/v2 Demo URL: https://external-api.demo.kalshi.co/trade-api/v2

Get your API key at https://kalshi.com/account/api-keys (Premier or Market Maker tier required)

Key Concepts

Hierarchy: Series > Events > Markets

• Series — recurring event templates (e.g., "Monthly Jobs Report", "Weekly Jobless Claims")
• Events — specific instances within a series (e.g., "May 2026 Jobs Report")
• Markets — individual binary outcomes within an event (e.g., "Will jobs added be above 200k?")

Binary Contract Pricing

• Prices are in cents (1-99), representing implied probability
• A Yes contract at 65c = market implies 65% probability
• Yes bid at price X is equivalent to No ask at (100 - X) — orderbooks show Yes bids and No bids only
• Settlement: pays $1.00 (100 cents) if Yes, $0 if No
• All monetary values (balance, prices, settlements) are in cents

Ticker Format

• Series: KXBTC, KXJOBLESS, KXINX
• Event: KXBTC-25MAY30 (series + date)
• Market: KXBTC-25MAY30-T100000 (event + threshold/outcome)

Sports game tickers follow a different pattern: {SERIES}-{YYMONDD}{TEAM1}{TEAM2}-{TEAM}

• Example: KXNHLGAME-25MAY12EDMORL-EDM (NHL, May 12 2025, Edmonton vs Orlando, Edmonton to win)
• Each game event has two mutually exclusive YES markets — one per team

CRITICAL: Series-Based Market Navigation

DO NOT use `/markets?keyword=` for sports, elections, or any series-based category. It only surfaces multi-game parlay bundles, not actual game-level markets. Searching "NHL", "Fulham", "Premier League" etc. returns zero or irrelevant results.

Always navigate: Series → Events → Markets. Game-level markets live under the series/event hierarchy and must be accessed via /events?series_ticker=KXXX. Also, /markets/{ticker} may return 404 for game markets — bid/ask prices only appear in the event endpoint response (/events/{event_ticker} with with_nested_markets=true).

This pattern applies to all series-based categories, not just sports:

• Sports games — NHL, NBA, NFL, MLB, EPL, etc.
• Political races — individual candidate markets within multi-candidate events
• Company-specific markets — earnings, CEO changes within a series
• Recurring economic data — jobs reports, jobless claims, CPI, etc.

Known Sports Series Tickers:

Correct workflow for sports:

# 1. List open games for a sport
curl -s "https://external-api.kalshi.com/trade-api/v2/events?series_ticker=KXNHLGAME&status=open&with_nested_markets=true"

# 2. Get specific game with live bid/ask
curl -s "https://external-api.kalshi.com/trade-api/v2/events/KXNHLGAME-25MAY12EDMORL?with_nested_markets=true"

# WRONG — do not do this:
# curl -s "https://external-api.kalshi.com/trade-api/v2/markets?keyword=NHL"  ← returns parlays, not games

How to Call

Kalshi uses RSA key-pair signature authentication. Three headers are required on authenticated requests:

Public GET endpoints (markets, events, orderbooks) can be called without auth headers.

# Public endpoint — no auth needed
curl -s "https://external-api.kalshi.com/trade-api/v2/markets?limit=10&status=open"

For authenticated endpoints, use direct RSA-PSS signing (not the kalshi_python SDK — it doesn't work):

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:
    raw_pk = os.environ["KALSHI_PRIVATE_KEY"].strip().replace(' ', '')
    pem = f"-----BEGIN RSA PRIVATE KEY-----\n{raw_pk}\n-----END RSA PRIVATE KEY-----"
    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 must NOT include query string
    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, ...} — balance is in cents

Signing gotchas:

• PSS not PKCS1v15 — PKCS1v15 padding returns 401. Must use PSS with SHA256.
• Strip query strings before signing — signature is computed on the bare path only (e.g. /trade-api/v2/portfolio/balance), not /trade-api/v2/portfolio/balance?param=value. Including query string will 401.
• Key env var format — KALSHI_PRIVATE_KEY should be stored as the raw base64 body with no PEM headers. The helper wraps it automatically.

API Spec

Full OpenAPI spec: https://docs.kalshi.com/openapi.yaml

Intent Routing

Map user intent to the right endpoint. All paths are relative to the base URL.

Events

Markets

Candlesticks

period_interval values: 1 (1 min), 60 (1 hour), 1440 (1 day)

Forecast & Live Data

Series

Exchange Info

Search & Discovery

Orders (Authenticated)

Orders V2 — Event-Market Orders (Authenticated, Fixed-Point)

Order Groups (Authenticated)

Portfolio (Authenticated)

Subaccounts (Authenticated — Institutions/Market Makers)

RFQ — Request for Quote (Authenticated)

API Keys (Authenticated)

Account (Authenticated)

Historical Data

Milestones & Structured Targets

Multivariate Collections

Incentives

Rate Limits

Token-based system that scales by API tier (Standard, Premier, Market Maker).

Check your limits with GET /account/limits. Batch operation max size scales with your tier's write budget.

Pagination

All list endpoints use cursor-based pagination. The response includes a cursor field — pass it back as a query param to get the next page.

WebSocket Channels

WebSocket connection at wss://external-api.kalshi.com/trade-api/ws/v2 (auth required at handshake).

Public channels:

• Market Ticker — price, volume, open interest updates
• Public Trades — trade notifications
• Market & Event Lifecycle — state changes, new markets/events
• Multivariate Market & Event Lifecycle — MVE state changes

Authenticated channels:

• User Orders — order created/updated notifications
• User Fills — fill notifications
• Market Positions — real-time position updates
• Order Group Updates — lifecycle and limit notifications
• Communications — RFQ and quote notifications
• Orderbook Updates — incremental price level changes

Order Fields Reference

Safety Notes

• All prices are in cents (1-99). A price of 65 means $0.65 per contract, NOT $65.
• Balance is in cents. 10000 = $100.00.
• POST /portfolio/orders submits real orders on production. Always verify ticker, side, and price before placing.
• Batch operations execute atomically — all succeed or all fail.
• Demo environment available at https://external-api.demo.kalshi.co/trade-api/v2 for risk-free testing.
• Before placing orders, always confirm the market ticker, current price, and position size with the user.
• Max 200,000 open orders per user.

Known Limitations

• `/markets?keyword=` misses series-based markets — sports games, political races, and other series-based categories are invisible to keyword search. Always navigate via /events?series_ticker=. See "CRITICAL: Series-Based Market Navigation" above.
• `/markets/{ticker}` returns 404 for game markets — bid/ask prices for sports and similar markets only appear in the event endpoint response. Use /events/{event_ticker}?with_nested_markets=true instead.
• RSA signing required for authenticated endpoints — cannot use simple API key header like most REST APIs. Use the official Python/TypeScript SDK for signing.
• Binary markets only — no multi-outcome contracts (except via multivariate events)
• US-regulated — trading available to eligible US residents only
• Market hours — markets have defined close times, check close_ts before trading
• Historical data split — older data requires /historical/* endpoints, check /historical/cutoff-timestamps for the boundary
• V1 vs V2 order endpoints — V2 uses fixed-point format, V1 uses cents. Both work but V2 is recommended for new integrations.
• Subaccounts — only available to institutions and market makers (max 32 per user)
• RFQ limit — max 100 open RFQs at a time
• Multivariate market creation — max 5000 per week per collection