kalshi

name: kalshi version: 1.0.2 description: | Kalshi prediction markets: binary event contracts on politics, economy, sports, weather.

Use when trading or browsing US regulated event markets (e.g. CPI above 3%, NHL Edmonton vs Florida, jobs report > 200k, election odds). allowed-tools: Bash, Read, Write, WebFetch homepage: https://kalshi.com metadata: openclaw: emoji: "🎯" requires: env: - KALSHI_ACCESS_KEY - KALSHI_PRIVATE_KEY primaryEnv: KALSHI_ACCESS_KEY homepage: https://kalshi.com tags: - prediction-market - event-contracts - binary-options - trading - orderbook - politics - economics - weather - sports - crypto - implied-probability - cftc-regulated - elections - forecasting

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:
    import re
    raw = os.environ["KALSHI_PRIVATE_KEY"]
    # Decode literal escape sequences first (some input channels save '\n' as
    # two chars backslash+n instead of a real newline).
    raw = (raw.replace('\\r\\n', '\n').replace('\\n', '\n')
              .replace('\\r', '\n').replace('\\t', ' '))
    # Strip PEM markers if present, then strip ALL whitespace and rewrap.
    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 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 accepts any of: raw base64 body, full PEM with real newlines, or full PEM with newlines collapsed to whitespace (common when pasted through web forms). The helper normalises all formats automatically. For the most robust storage, save as a double-quoted multi-line PEM with \n escapes in .env so python-dotenv rehydrates it to a real PEM string.

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