Kalshi API Tutorial: Authentication, Markets & Orders

The Kalshi API is your gateway to automated trading. It exposes everything you can do on the website — and more — through a clean REST API and WebSocket feeds. This tutorial covers every endpoint you'll need, with working Python code for each.

This is a reference guide. If you want a start-to-finish bot tutorial, read our Build a Kalshi Bot with Python guide first, then come back here for the API deep dive.

API Overview

Kalshi provides two interfaces:

• REST API — For authentication, market data, order management, and portfolio queries. Request-response pattern.
• WebSocket — For real-time market data streaming (orderbook updates, trade feeds). Persistent connection.

Base URL: https://api.elections.kalshi.com/trade-api/v2

Authentication

Kalshi uses API key authentication. Generate your key pair (key ID + secret) from your Kalshi account settings.

import requests

class KalshiAPI:
    BASE_URL = "https://api.elections.kalshi.com/trade-api/v2"

    def __init__(self, key_id, key_secret):
        self.key_id = key_id
        self.key_secret = key_secret
        self.session = requests.Session()
        self.session.headers.update({
            "Content-Type": "application/json",
            "Authorization": f"Bearer {key_id}:{key_secret}",
        })

    def get(self, path, params=None):
        resp = self.session.get(f"{self.BASE_URL}{path}", params=params)
        resp.raise_for_status()
        return resp.json()

    def post(self, path, json=None):
        resp = self.session.post(f"{self.BASE_URL}{path}", json=json)
        resp.raise_for_status()
        return resp.json()

    def delete(self, path):
        resp = self.session.delete(f"{self.BASE_URL}{path}")
        resp.raise_for_status()
        return resp.json()

Market Data Endpoints

List Markets

# Get open markets
markets = api.get("/markets", params={
    "status": "open",
    "limit": 50,
    "cursor": None,  # for pagination
})

for m in markets["markets"]:
    print(f"{m['ticker']}: {m['title']}")
    print(f"  YES bid/ask: {m['yes_bid']}/{m['yes_ask']}")
    print(f"  Volume: {m['volume']}")

Get Single Market

market = api.get("/markets/TICKER-HERE")
print(market["market"]["title"])
print(f"Status: {market['market']['status']}")
print(f"Settle time: {market['market']['close_time']}")

Get Orderbook

book = api.get("/markets/TICKER-HERE/orderbook")
print("YES bids:", book["orderbook"]["yes"])
print("NO bids:", book["orderbook"]["no"])

Order Management

Place an Order

order = api.post("/portfolio/orders", json={
    "ticker": "TICKER-HERE",
    "action": "buy",
    "side": "yes",
    "type": "limit",
    "count": 10,
    "yes_price": 45,  # 45 cents
})
print(f"Order ID: {order['order']['order_id']}")

Cancel an Order

api.delete(f"/portfolio/orders/{order_id}")

Get Fills

fills = api.get("/portfolio/fills", params={"ticker": "TICKER-HERE"})
for f in fills["fills"]:
    print(f"Filled {f['count']} @ {f['yes_price']}¢ — {f['created_time']}")

Portfolio Endpoints

# Balance
balance = api.get("/portfolio/balance")
print(f"Available: ${balance['balance'] / 100:.2f}")

# Positions
positions = api.get("/portfolio/positions")
for p in positions["market_positions"]:
    print(f"{p['ticker']}: {p['position']} contracts")

Rate Limits

Kalshi enforces rate limits to prevent abuse. Key limits to know:

• General API calls: throttled per minute
• Order placement: separate, tighter limits
• Market data: most permissive limits

Always implement exponential backoff when you hit rate limits. Never retry immediately.

Best Practices

1. Cache market data — Don't fetch the same market every second. Cache for 5-30 seconds depending on your strategy's time sensitivity.
2. Use limit orders — Market orders in thin markets can fill at bad prices.
3. Handle errors gracefully — The API will return errors for insufficient balance, closed markets, invalid tickers, etc. Parse and handle each.
4. Log everything — Every API call, every response. You'll need this for debugging and tax reporting.

For building a complete bot from scratch, read our Python bot tutorial.