Kalshi API Guide: Python SDK Setup, RSA Auth & Demo Sandbox (2026)

This guide covers the Kalshi API from demo sandbox to production trading bot. Kalshi is the only CFTC-regulated prediction market exchange in the US, offering REST v2, WebSocket, and FIX protocols with RSA-PSS authentication and fiat settlement.

For developers, this means familiar patterns — REST over HTTPS, WebSocket for streaming, and FIX for institutional trading — but with unique quirks around RSA signing and market structure. Start in the demo environment at external-api.demo.kalshi.co, then switch to production when ready.

Last verified: August 2026. Check the Kalshi Changelog for the latest updates. Major 2026 changes reflected below: the legacy order-mutation endpoints were removed in June 2026 (replaced by CreateOrder V2 at /portfolio/events/orders), and rate limits moved to a token-cost system in April 2026.

Try it live: Test Kalshi and Polymarket endpoints side-by-side in the API Playground — no setup required.

Why Kalshi for Agents

Kalshi stands apart from Polymarket in several ways that matter for autonomous agents:

• Regulated: CFTC Designated Contract Market — legal for U.S. entities and institutions
• Fiat settlement: USD deposits and withdrawals via traditional banking (no crypto wallets needed)
• Demo environment: Full-featured sandbox for testing without real money
• Published fee schedule: Trading fees apply per Kalshi’s published fee schedule — taker fees exist (the API’s post-only option exists specifically to avoid them), so factor fees into edge calculations
• FIX protocol support: Institutional-grade connectivity for low-latency strategies
• Familiar auth patterns: RSA-PSS signed requests, not blockchain wallet signatures

The tradeoff: Kalshi has less total liquidity than Polymarket, fewer concurrent markets, and more restricted market categories (due to CFTC oversight). But for agents operating within U.S. regulatory frameworks, or for strategies that need the demo environment for safe testing, Kalshi is often the better starting point.

Architecture Overview

Kalshi’s API is simpler than Polymarket’s — there’s essentially one API with different access methods.

These are the hosts recommended in Kalshi’s current documentation. The docs also list external-api.kalshi.com alongside api.elections.kalshi.com for production REST. The legacy hosts (demo-api.kalshi.co, wss://api.elections.kalshi.com/trade-api/ws/v2) still respond and remain supported, but new integrations should use the documented external-api hosts.

All market data, trading, and account endpoints live under the same base URL. This is a major simplification compared to Polymarket’s multi-service architecture.

How Kalshi Markets Work

Understanding Kalshi’s market structure is essential before you start coding.

Event Contracts

Every Kalshi market is a binary contract that pays out $1.00 if the event occurs, or $0.00 if it doesn’t. You buy contracts at prices between $0.01 and $0.99 (expressed in cents internally — more on this below).

Example: A contract asking “Will Bitcoin be above $100,000 on March 31?” might be trading at $0.65 (65 cents). If Bitcoin is above $100K on that date, you receive $1.00 per contract. If not, you receive $0.00. Your profit on a YES bet is $0.35 per contract; your risk is $0.65.

Ticker Format

Kalshi tickers encode market information directly:

KXNFLGAME-25OCT12CLEPIT
│ │       │  │     │
│ │       │  │     └── Teams (CLE vs PIT)
│ │       │  └──────── Date (October 12)
│ │       └─────────── Year (2025)
│ └─────────────────── Series (NFL Game)
└───────────────────── KX prefix (Kalshi Exchange)

INXCHI-25JAN31-T69.5
│     │        │
│     │        └── Threshold value
│     └─────────── Expiry date
└───────────────── Series ticker

Prices: Fixed-Point Dollar Strings

Critical detail: Kalshi completed a fixed-point migration in March 2026. Prices are now expressed as dollar strings (e.g., "0.6500" for $0.65). The old integer cent fields (yes_price: 65) have been removed from API responses. When placing orders on the CreateOrder V2 endpoint, use price — a fixed-point string with up to 6 decimal places — with side: "bid" or side: "ask", and count as a fixed-point string (e.g., "10.00"). Some markets support subpenny pricing (tick sizes as small as $0.0001) — check the price_level_structure field on market responses. Fractional contract sizes are always supported; the old fractional_trading_enabled flag was removed from the market schema in July 2026.

Getting Started: Demo Environment

The biggest advantage Kalshi has for developers is a fully functional demo environment. Use it.

Demo REST: https://external-api.demo.kalshi.co/trade-api/v2
Demo WebSocket: wss://external-api-ws.demo.kalshi.co/trade-api/ws/v2

(The legacy demo-api.kalshi.co host still works, but the external-api hosts above are what Kalshi’s docs now recommend.)

The demo environment has:

• Fake money with no risk
• All the same endpoints as production
• Real-ish market data to test against
• Separate API keys from production

Always build and test in demo first. Switch to production only after your bot behaves correctly.

Authentication: RSA-PSS Signing

Kalshi uses RSA-PSS (Probabilistic Signature Scheme) for API authentication. This is more complex than a simple API key header, but provides stronger security.

Step 1: Generate API Keys

1. Log into your Kalshi account (or demo account)
2. Go to Settings → API
3. Generate a new API key pair
4. Download the private key (PEM file) — store this securely
5. Note the API Key ID — this is your public identifier

Step 2: Understand the Signing Process

Every authenticated request requires three custom headers:

KALSHI-ACCESS-KEY: <your-api-key-id>
KALSHI-ACCESS-SIGNATURE: <rsa-pss-signature>
KALSHI-ACCESS-TIMESTAMP: <unix-timestamp-in-milliseconds>

The signature is computed over the concatenation of: timestamp + method + path

Step 3: Implement Request Signing (Python)

import time
import base64
import requests
from cryptography.hazmat.primitives import serialization, hashes
from cryptography.hazmat.primitives.asymmetric import padding

class KalshiClient:
    def __init__(self, key_id: str, private_key_path: str, base_url: str = None):
        self.key_id = key_id
        self.base_url = base_url or "https://api.elections.kalshi.com/trade-api/v2"

        with open(private_key_path, "rb") as f:
            self.private_key = serialization.load_pem_private_key(
                f.read(), password=None
            )

    def _sign(self, timestamp_ms: str, method: str, path: str) -> str:
        """Sign the request using RSA-PSS"""
        message = f"{timestamp_ms}{method}{path}".encode("utf-8")
        signature = self.private_key.sign(
            message,
            padding.PSS(
                mgf=padding.MGF1(hashes.SHA256()),
                salt_length=padding.PSS.DIGEST_LENGTH
            ),
            hashes.SHA256()
        )
        return base64.b64encode(signature).decode("utf-8")

    def _headers(self, method: str, path: str) -> dict:
        """Generate authenticated headers for a request"""
        timestamp = str(int(time.time() * 1000))
        signature = self._sign(timestamp, method, path)
        return {
            "KALSHI-ACCESS-KEY": self.key_id,
            "KALSHI-ACCESS-SIGNATURE": signature,
            "KALSHI-ACCESS-TIMESTAMP": timestamp,
            "Content-Type": "application/json",
            "Accept": "application/json"
        }

    def get(self, path: str, params: dict = None):
        url = f"{self.base_url}{path}"
        headers = self._headers("GET", path)
        return requests.get(url, headers=headers, params=params)

    def post(self, path: str, data: dict = None):
        url = f"{self.base_url}{path}"
        headers = self._headers("POST", path)
        return requests.post(url, headers=headers, json=data)

    def delete(self, path: str, data: dict = None):
        url = f"{self.base_url}{path}"
        headers = self._headers("DELETE", path)
        return requests.delete(url, headers=headers, json=data)

Using the Demo Environment

# For demo/testing:
client = KalshiClient(
    key_id="your-demo-api-key-id",
    private_key_path="path/to/demo-private-key.pem",
    base_url="https://external-api.demo.kalshi.co/trade-api/v2"
)

# For production:
client = KalshiClient(
    key_id="your-prod-api-key-id",
    private_key_path="path/to/prod-private-key.pem",
    base_url="https://api.elections.kalshi.com/trade-api/v2"
)

Using the Official Python SDK

Kalshi provides official Python SDKs — synchronous and asynchronous — that handle authentication for you. The old kalshi-python package is deprecated.

# Synchronous (recommended for most bots)
pip install kalshi_python_sync

# Asynchronous (for async/await workflows)
pip install kalshi_python_async

from kalshi_python_sync import Configuration, KalshiClient

config = Configuration(
    host="https://external-api.demo.kalshi.co/trade-api/v2"  # Demo
)

# Read private key from file
with open("path/to/private_key.pem", "r") as f:
    private_key = f.read()

config.api_key_id = "your-api-key-id"
config.private_key_pem = private_key

client = KalshiClient(config)

# Check balance
balance = client.get_balance()
print(f"Balance: ${balance.balance_dollars}")  # balance_dollars is a dollar string
# The integer-cent field is also still present: balance.balance / 100

A TypeScript SDK is also available:

npm install kalshi-typescript

import { Configuration, PortfolioApi } from 'kalshi-typescript';

const config = new Configuration({
    apiKey: 'your-api-key-id',
    privateKeyPath: 'path/to/your/private-key.pem',
    basePath: 'https://api.elections.kalshi.com/trade-api/v2'
});

const portfolioApi = new PortfolioApi(config);
const balance = await portfolioApi.getBalance();

See kalshi_python_sync on PyPI and kalshi-typescript on npm for the latest versions.

REST API Reference

Market Data (Public)

GET /markets — List All Markets

response = client.get("/markets", params={
    "limit": 20,
    "status": "open"
})

for market in response.json()["markets"]:
    print(f"{market['ticker']}: {market['title']}")
    print(f"  Yes bid: {market.get('yes_bid_dollars', 'N/A')}")
    print(f"  Volume: {market.get('volume', 0)}")

Key response fields:

• ticker — Unique market identifier (e.g., KXNFLGAME-25OCT12CLEPIT)
• title — Human-readable description
• status — open, closed, settled
• yes_bid_dollars / no_bid_dollars — Best bid prices as dollar strings (e.g., "0.6500")
• yes_bid_size_fp / yes_ask_size_fp — Total contract size at best bid/ask
• volume — Number of contracts traded
• open_interest — Number of outstanding contracts
• expiration_time — When the market expires
• price_level_structure — Pricing tier (linear_cent, tapered_deci_cent, deci_cent, plus center_deci_edge_centi_cent — $0.0001 ticks below $0.01 and above $0.99 — and center_centi_edge_centi_cent for combo markets)

Note: several fields were removed from the market schema in 2026 — tick_size (May), and fractional_trading_enabled, response_price_units, and resting_orders_count (July). Fractional order sizes are always accepted; there is no per-market flag to check anymore.

GET /markets/{ticker} — Get Single Market

response = client.get("/markets/KXNFLGAME-25OCT12CLEPIT")
market = response.json()["market"]

GET /markets/{ticker}/orderbook — Get Order Book

response = client.get("/markets/KXNFLGAME-25OCT12CLEPIT/orderbook")
book = response.json()["orderbook_fp"]

# Each entry is [price_dollars, count_fp] — both strings
print("YES bids:", book.get("yes_dollars", []))
print("NO bids:", book.get("no_dollars", []))

# Example: [["0.4200", "13.00"], ["0.3500", "11.00"]]
# Sorted ascending — last element is the best (highest) bid

The order book returns bids only — no explicit asks. In binary markets, a YES bid at $X implies a NO ask at $(1.00 - X) and vice versa. Arrays are sorted ascending; the last element is the best bid. Both price and count values are strings to support subpenny pricing and fractional contracts.

To fetch multiple order books in one request, use the batch endpoint GET /markets/orderbooks.

GET /events — List Events

Events group related markets together (e.g., all NFL Week 10 games).

response = client.get("/events", params={"status": "open"})
events = response.json()["events"]

GET /series — List Series

Series are higher-level groupings (e.g., “NFL Games”, “Fed Rate Decisions”).

response = client.get("/series")

Trading (Authenticated)

Breaking change (June 2026): The legacy order-mutation endpoints (POST /portfolio/orders with side: yes/no, action: buy/sell, count_fp, yes_price_dollars) were deprecated and removed June 18–25, 2026. The canonical order endpoint is now CreateOrder V2 at POST /portfolio/events/orders. From June 1, 2026, any remaining legacy mutation endpoints also cost 5x the rate-limit tokens of their V2 equivalents. See the CreateOrder V2 reference and the changelog.

POST /portfolio/events/orders — Place an Order (V2)

import uuid

order = {
    "ticker": "KXNFLGAME-25OCT12CLEPIT",
    "side": "bid",                          # "bid" or "ask"
    "count": "10.00",                       # Contract quantity (fixed-point string)
    "price": "0.65",                        # Fixed-point string, up to 6 decimals
    "time_in_force": "good_till_canceled",  # REQUIRED
    "self_trade_prevention_type": "taker_at_cross",  # REQUIRED
    "client_order_id": str(uuid.uuid4())    # Idempotent tracking ID
}

response = client.post("/portfolio/events/orders", data=order)
print(response.json())

Order parameters:

• ticker — The market ticker (required)
• side — bid or ask (required; replaces the old yes/no + buy/sell combination)
• count — Contract quantity as a fixed-point string (e.g., "10.00") (required)
• price — Limit price as a fixed-point string with up to 6 decimal places (e.g., "0.65")
• time_in_force — Required: fill_or_kill, good_till_canceled, or immediate_or_cancel
• self_trade_prevention_type — Required: taker_at_cross or maker
• client_order_id — Optional idempotency key (recommended for deduplication)
• expiration_time — Optional expiration timestamp in seconds
• subaccount — Optional: route the order to a subaccount
• order_group_id — Optional: attach the order to an order group
• exchange_index — Optional: target a specific exchange shard
• cancel_order_on_pause — Optional: auto-cancel if the market pauses

Note: all orders are limit orders — there is no separate market-order type.

GET /portfolio/orders — List Your Orders

response = client.get("/portfolio/orders", params={
    "status": "resting"  # resting, canceled, executed
})

Canceling, Amending, and Decreasing Orders (V2)

The legacy cancel (DELETE /portfolio/orders/{order_id}), amend, and decrease endpoints have V2 equivalents under the /portfolio/events/orders family, and batch order creation lives at POST /portfolio/events/orders/batched. See the orders section of the API reference for the exact V2 paths and payloads.

Account & Positions

GET /portfolio/positions — Get Your Positions

response = client.get("/portfolio/positions")
positions = response.json()["positions"]

for pos in positions:
    print(f"{pos['ticker']}: {pos['position']} contracts")
    print(f"  Market exposure: ${pos.get('market_exposure', 0) / 100:.2f}")

GET /portfolio/balance — Check Your Balance

response = client.get("/portfolio/balance")
balance = response.json()

# Preferred: the balance_dollars dollar-string field (added May 2026)
print(f"Available: ${balance['balance_dollars']}")

# The legacy integer-cent field still works:
print(f"Available: ${balance['balance'] / 100:.2f}")

Per the changelog, balance reads are scoped by exchange_index as of August 2026 — if you trade on more than one exchange shard (e.g., the Perps exchange), query the balance for each index.

GET /portfolio/settlements — Settlement History

response = client.get("/portfolio/settlements")

Historical Data

Kalshi partitions data into live and historical tiers. Live endpoints return current and recent data; older data must be queried through dedicated historical endpoints.

GET /historical/cutoff — Get Cutoff Timestamps

response = client.get("/historical/cutoff")
cutoffs = response.json()
# Returns: market_settled_ts, trades_created_ts, orders_updated_ts

Historical Endpoints

# Example: fetch historical trades
response = client.get("/historical/trades", params={
    "ticker": "KXNFLGAME-25OCT12CLEPIT",
    "limit": 100
})

The live data window is approximately 3 months. Historical endpoints support the same cursor-based pagination as their live counterparts.

WebSocket API

For real-time data, Kalshi’s WebSocket API streams order book updates, trade executions, and market status changes.

Connection with Authentication

import asyncio
import base64
import json
import time
import websockets
from cryptography.hazmat.primitives import serialization, hashes
from cryptography.hazmat.primitives.asymmetric import padding

KEY_ID = "your-api-key-id"
PRIVATE_KEY_PATH = "path/to/private-key.pem"
WS_URL = "wss://external-api-ws.demo.kalshi.co/trade-api/ws/v2"  # Demo

def load_private_key():
    with open(PRIVATE_KEY_PATH, "rb") as f:
        return serialization.load_pem_private_key(f.read(), password=None)

def sign_ws_message(private_key, timestamp_ms: str) -> str:
    message = f"{timestamp_ms}GET/trade-api/ws/v2".encode("utf-8")
    signature = private_key.sign(
        message,
        padding.PSS(
            mgf=padding.MGF1(hashes.SHA256()),
            salt_length=padding.PSS.DIGEST_LENGTH
        ),
        hashes.SHA256()
    )
    return base64.b64encode(signature).decode("utf-8")

async def stream_kalshi():
    private_key = load_private_key()
    timestamp = str(int(time.time() * 1000))
    signature = sign_ws_message(private_key, timestamp)

    headers = {
        "KALSHI-ACCESS-KEY": KEY_ID,
        "KALSHI-ACCESS-SIGNATURE": signature,
        "KALSHI-ACCESS-TIMESTAMP": timestamp
    }

    async with websockets.connect(WS_URL, additional_headers=headers) as ws:
        print("Connected to Kalshi WebSocket")

        # Subscribe to ticker updates
        await ws.send(json.dumps({
            "id": 1,
            "cmd": "subscribe",
            "params": {
                "channels": ["ticker"]
            }
        }))

        # Subscribe to orderbook for a specific market
        await ws.send(json.dumps({
            "id": 2,
            "cmd": "subscribe",
            "params": {
                "channels": ["orderbook_delta"],
                "market_tickers": ["KXNFLGAME-25OCT12CLEPIT"]
            }
        }))

        async for message in ws:
            data = json.loads(message)
            print(f"Update: {data}")

asyncio.run(stream_kalshi())

Available Channels

Note: The WebSocket connection itself requires authentication — even for public data channels. Auth headers must be included during the handshake.

Private channels:

• fill — Your trade executions
• user_orders — Real-time order updates (created, updated, canceled, executed)
• market_positions — Your position updates
• order_group_updates — Order group status changes

Public channels:

• orderbook_delta — Real-time order book changes for specific markets
• ticker — Market-wide ticker updates for all markets
• trade — Public trade feed
• market_lifecycle_v2 — Market open/close/settlement events (excludes KXMVE-prefixed tickers)
• multivariate_market_lifecycle — Lifecycle events for multivariate event (MVE) markets

Subscription Management

You can dynamically add or remove markets from an existing subscription without re-subscribing. A get_snapshot command is also available to request a fresh orderbook snapshot on demand — useful after detecting a sequence gap.

# Add markets to an existing subscription
await ws.send(json.dumps({
    "id": 3,
    "cmd": "update_subscription",
    "params": {
        "sids": [1],
        "market_tickers": ["NEW-MARKET-1", "NEW-MARKET-2"],
        "action": "add_markets"
    }
}))

Keepalive

The Python websockets library handles keepalive automatically. Other WebSocket libraries may require manual ping/pong implementation.

FIX Protocol

For institutional-grade connectivity, Kalshi supports the FIX (Financial Information eXchange) protocol (version 1.0.31 as of June 2026, based on FIXT.1.1) — the same protocol used by major stock and futures exchanges.

FIX is relevant if you:

• Have existing FIX trading infrastructure
• Need the lowest possible latency
• Are building for an institutional trading desk

Key features: session management, order entry, market settlement reports, RFQ support, drop copy sessions, order groups, and subpenny pricing support. Authentication uses 2048-bit RSA PKCS#8 key pairs.

Contact [email protected] for FIX access and connection details.

Rate Limits

Kalshi replaced its old per-request tiers with a token-cost system in April 2026. Each tier gets separate read and write token budgets per second, and each endpoint consumes a published number of tokens per call (rate limits docs):

How costs work:

• A single order costs 10 write tokens; a batch of N orders costs N × 10
• Legacy (pre-V2) order endpoints cost 5x their V2 equivalents as of June 1, 2026
• Advanced is self-serve: upgrade via POST /account/api_usage_level/upgrade (added June 2026)
• Higher tiers are earned automatically from trailing 30-day trading volume (thresholds range from 0.075% to 1.00% of exchange volume; requirements were halved June 25, 2026) and are granted for 30 days at a time

Key guidelines:

• WebSocket feeds are better suited for latency-sensitive strategies than REST polling
• Cache market metadata (tickers, descriptions) — it rarely changes
• Query your current limits via GET /account/limits (and GET /account/limits/perps for the Perps API)
• Query per-endpoint token costs via GET /account/endpoint_costs rather than hardcoding them

What Else Changed in 2026

A few platform-level additions worth knowing about (changelog):

• Predictions vs. Perps API split: Kalshi now runs a separate Perps API for perpetual futures with margin, alongside the classic prediction market API (docs.kalshi.com/welcome)
• Subaccounts and scoped API keys: API keys can be restricted with granular permissions such as write::trade (June 2026) and write::transfer (June 2026), and orders can be routed to subaccounts
• Multi-exchange sharding: an exchange_index parameter appears across order placement, balance reads, and other endpoints to target a specific exchange shard
• Batch orderbook reads: GET /markets/orderbooks fetches multiple books in one call
• Historical positions: GET /historical/positions (July 2026) rounds out the historical data tier
• WebSocket get_snapshot: request a fresh orderbook snapshot on an existing subscription instead of tearing it down

Putting It Together: A Complete Trading Bot

Here’s a minimal but functional bot that monitors a market and places orders based on a simple threshold strategy:

import time
import uuid
import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("kalshi-bot")

class SimpleKalshiBot:
    def __init__(self, client: KalshiClient, ticker: str):
        self.client = client
        self.ticker = ticker
        self.position = 0
        self.max_position = 50  # Max contracts to hold

    def get_market_price(self) -> dict:
        """Fetch current market prices"""
        response = self.client.get(f"/markets/{self.ticker}")
        market = response.json()["market"]
        return {
            "yes_bid": market.get("yes_bid_dollars"),
            "yes_ask": market.get("yes_ask_dollars"),
            "no_bid": market.get("no_bid_dollars"),
            "no_ask": market.get("no_ask_dollars"),
            "volume": market.get("volume", 0)
        }

    def check_position(self):
        """Get current position in this market"""
        response = self.client.get("/portfolio/positions", params={
            "ticker": self.ticker
        })
        positions = response.json().get("positions", [])
        for pos in positions:
            if pos["ticker"] == self.ticker:
                self.position = pos.get("position", 0)
                return
        self.position = 0

    def place_order(self, side: str, count: int, price: str):
        """Place a limit order via CreateOrder V2. side is 'bid' or 'ask'."""
        order = {
            "ticker": self.ticker,
            "side": side,
            "count": f"{count}.00",
            "price": price,
            "time_in_force": "good_till_canceled",
            "self_trade_prevention_type": "taker_at_cross",
            "client_order_id": str(uuid.uuid4())
        }
        response = self.client.post("/portfolio/events/orders", data=order)

        if response.status_code in (200, 201):
            logger.info(f"Order placed: {side} {count}x @ ${price}")
        else:
            logger.error(f"Order failed: {response.text}")

        return response

    def run(self, buy_threshold: str, sell_threshold: str, interval: int = 10):
        """
        Simple threshold strategy:
        - Buy YES if price drops below buy_threshold
        - Sell YES if price rises above sell_threshold
        Thresholds are dollar strings (e.g., "0.40", "0.60")
        """
        from decimal import Decimal
        buy_t = Decimal(buy_threshold)
        sell_t = Decimal(sell_threshold)

        logger.info(f"Starting bot for {self.ticker}")
        logger.info(f"Buy below: ${buy_threshold} | Sell above: ${sell_threshold}")

        while True:
            try:
                prices = self.get_market_price()
                self.check_position()

                yes_ask = prices["yes_ask"]
                yes_bid = prices["yes_bid"]

                logger.info(
                    f"Price: bid=${yes_bid} ask=${yes_ask} | "
                    f"Position: {self.position} contracts"
                )

                # Buy signal — bid for YES contracts
                if (yes_ask and Decimal(yes_ask) <= buy_t
                        and self.position < self.max_position):
                    contracts = min(5, self.max_position - self.position)
                    self.place_order("bid", contracts, yes_ask)

                # Sell signal — offer out our YES contracts
                if (yes_bid and Decimal(yes_bid) >= sell_t
                        and self.position > 0):
                    contracts = min(5, self.position)
                    self.place_order("ask", contracts, yes_bid)

            except Exception as e:
                logger.error(f"Error: {e}")

            time.sleep(interval)


# Usage:
client = KalshiClient(
    key_id="your-key-id",
    private_key_path="path/to/key.pem",
    base_url="https://external-api.demo.kalshi.co/trade-api/v2"  # START WITH DEMO
)

bot = SimpleKalshiBot(client, ticker="KXNFLGAME-25OCT12CLEPIT")
bot.run(buy_threshold="0.40", sell_threshold="0.60", interval=10)

Common Patterns for Agent Builders

Pattern 1: Multi-Market Scanner

Scan all open markets for opportunities matching your criteria.

from decimal import Decimal

def scan_markets(client, min_volume=1000, max_yes_price="0.30"):
    """Find underpriced YES contracts with decent volume"""
    max_price = Decimal(max_yes_price)
    response = client.get("/markets", params={
        "status": "open",
        "limit": 200
    })

    opportunities = []
    for market in response.json()["markets"]:
        vol = market.get("volume", 0)
        yes_ask = market.get("yes_ask_dollars")

        if vol >= min_volume and yes_ask and Decimal(yes_ask) <= max_price:
            opportunities.append({
                "ticker": market["ticker"],
                "title": market["title"],
                "yes_ask_dollars": yes_ask,
                "volume": vol
            })

    return sorted(opportunities, key=lambda x: x["volume"], reverse=True)

Pattern 2: Cross-Platform Arbitrage (Kalshi ↔ Polymarket)

Compare prices on the same event across both platforms.

from decimal import Decimal

def find_cross_platform_arbs(kalshi_client, polymarket_markets):
    """
    Compare Kalshi and Polymarket prices for matching events.
    Requires a mapping of Kalshi tickers to Polymarket token IDs.
    """
    kalshi_response = kalshi_client.get("/markets", params={
        "status": "open", "limit": 200
    })

    for kalshi_market in kalshi_response.json()["markets"]:
        ticker = kalshi_market["ticker"]

        # Check if we have a Polymarket match
        if ticker in polymarket_markets:
            kalshi_yes = Decimal(kalshi_market.get("yes_ask_dollars", "1.00"))
            poly_no = Decimal(str(polymarket_markets[ticker]["no_price"]))

            combined = kalshi_yes + poly_no
            if combined < Decimal("0.98"):  # 2%+ arb
                print(f"ARB: {ticker}")
                print(f"  Kalshi YES: ${kalshi_yes}")
                print(f"  Poly NO: ${poly_no}")
                print(f"  Combined: ${combined}")
                print(f"  Edge: ${Decimal('1.00') - combined}")

Pattern 3: News-Driven Trading

Get started in 1 click: Deploy the Kalshi News Bot — a ready-to-run Claude-powered trading agent for Kalshi’s demo environment.

React to news events by monitoring external sources and executing on Kalshi.

import time

def news_driven_strategy(client, ticker, news_monitor):
    """
    When positive news hits, buy YES.
    When negative news hits, buy NO.
    """
    while True:
        signal = news_monitor.get_latest_signal(ticker)

        if signal and signal["confidence"] > 0.7:
            market = client.get(f"/markets/{ticker}").json()["market"]

            # Positive news: bid at the YES ask to buy YES exposure.
            # Negative news: hit the YES bid (ask side) to take NO exposure.
            if signal["direction"] == "positive":
                side, price = "bid", market.get("yes_ask_dollars")
            else:
                side, price = "ask", market.get("yes_bid_dollars")

            if price:
                client.post("/portfolio/events/orders", data={
                    "ticker": ticker,
                    "side": side,
                    "count": "5.00",
                    "price": price,
                    "time_in_force": "immediate_or_cancel",
                    "self_trade_prevention_type": "taker_at_cross",
                    "client_order_id": str(uuid.uuid4())
                })

        time.sleep(30)

Pattern 4: Portfolio Monitoring Dashboard

Pull all positions and compute aggregate P&L.

def portfolio_summary(client):
    """Get a complete portfolio summary"""
    balance = client.get("/portfolio/balance").json()
    positions = client.get("/portfolio/positions").json().get("positions", [])

    total_exposure = 0
    total_unrealized = 0

    print(f"Cash Balance: ${balance['balance_dollars']}")
    print(f"\nOpen Positions:")
    print("-" * 60)

    for pos in positions:
        exposure = float(pos.get("market_exposure_dollars", "0"))
        total_exposure += exposure

        print(f"  {pos['ticker']}")
        print(f"    Side: {pos.get('side', 'N/A')}")
        print(f"    Contracts: {pos.get('position_fp', '0')}")
        print(f"    Exposure: ${exposure:.2f}")

    print("-" * 60)
    print(f"Total Exposure: ${total_exposure:.2f}")
    print(f"Total Portfolio: ${(balance['balance'] / 100) + total_exposure:.2f}")

Production Deployment Checklist

Before taking your bot from demo to production:

Security:

• Private keys stored in environment variables or a secrets manager (never in code)
• API key permissions scoped to only what’s needed
• Separate keys for demo and production
• No secrets committed to version control

Risk Management:

• Maximum position size limits per market
• Maximum total portfolio exposure limit
• Kill switch to cancel all orders and halt trading
• Daily loss limit with automatic shutdown
• Slippage protection on market orders

Reliability:

• Automatic reconnection for WebSocket disconnections (exponential backoff)
• Graceful error handling for all API calls
• Logging of every order placed and every error encountered
• Health check / heartbeat monitoring

Operational:

• Tested extensively in demo environment
• Start with very small position sizes in production
• Monitor manually for the first 24-48 hours
• Alerts set up for unusual behavior (large losses, connection failures)
• Rate limit awareness built into request logic

Kalshi vs. Polymarket: Choosing Your Platform

For many agent builders, the optimal approach is to start on Kalshi’s demo environment to test your logic safely, then deploy to both platforms to maximize opportunity and diversification.

Beyond prediction markets: Many agents don’t stop at Polymarket and Kalshi. Traditional offshore sportsbooks offer sports odds that overlap with prediction market events — often with different pricing and significantly higher limits. For a full comparison of how these worlds differ in odds quality, API access, and automation potential, see Offshore vs. Regulated Sportsbooks.

See our Polymarket API Guide for the complete Polymarket reference.

Troubleshooting

For an in-depth breakdown of the 10 most common integration failures — including RSA signing edge cases, order book drift, the fixed-point migration, and fractional contract handling — see the top 10 Kalshi API problems guide.

Authentication errors (401/403):

• Verify your timestamp is in milliseconds (not seconds)
• Check that you’re signing the correct string: timestamp + method + path
• Ensure your private key file is the correct PEM format
• Remember: demo and production use separate keys

“Order rejected” errors:

• If you’re posting to POST /portfolio/orders with side: yes/no and action: buy/sell, your code targets the legacy endpoint removed in June 2026 — migrate to POST /portfolio/events/orders (V2) with side: bid/ask and the required time_in_force and self_trade_prevention_type fields
• Check market status — it may be closed or settled
• Verify your price is within the valid range and tick size for the market’s price_level_structure
• Ensure you have sufficient balance
• Check that you haven’t exceeded position limits

Rate limit errors (429):

• Reduce polling frequency
• Switch to WebSocket for real-time data
• Cache market metadata
• Implement exponential backoff on retries

WebSocket disconnections:

• Implement automatic reconnection with exponential backoff
• Re-subscribe to channels after reconnecting
• The websockets Python library handles keepalive automatically — other libraries may need manual ping/pong

Demo vs Production discrepancies:

• Some market data in demo may be synthetic or delayed
• Demo order execution may differ slightly from production
• Always re-verify behavior with small production orders before scaling

Official Resources

• Kalshi API Documentation
• Kalshi SDK Overview — Official SDK docs
• Kalshi OpenAPI Spec — Import into Postman, Apidog, etc.
• Kalshi AsyncAPI Spec — WebSocket schema
• kalshi_python_sync (PyPI) — Official synchronous Python SDK
• kalshi_python_async (PyPI) — Official async Python SDK
• kalshi-typescript (npm) — Official TypeScript SDK
• Kalshi Changelog
• Kalshi Academy — Educational resources
• Kalshi Trading Console

Community SDKs and Tools

The official SDKs above receive weekly releases and are the recommended starting point. The old kalshi-python PyPI package is deprecated — do not use it for new projects. Community clients like AndrewNolte/KalshiPythonClient (last pushed 2022) and sswadkar/kalshi-interface are unmaintained and predate the 2026 API changes; the community kalshi-rust crate exists but verify it against the current API before relying on it.

Where This Fits in the Agent Betting Stack

This guide covers Layer 3 (Trading) of the Agent Betting Stack. Kalshi’s API is one execution venue for converting intelligence into positions — and for many U.S.-based agents, it’s the only fully legal one.

To build a complete autonomous agent, you also need:

• Layer 1 — Identity: Register and verify your agent (Moltbook Identity Guide)
• Layer 2 — Wallet: Hold and manage funds (Wallet Comparison Guide)
• Layer 4 — Intelligence: Agent Intelligence Guide — LLM analysis, sentiment, and strategy
• Cross-Market: Offshore Sportsbook API Guide — Extend your agent to traditional sportsbooks

This guide is maintained by AgentBets.ai. Found an error or API change we missed? Let us know on Twitter.

Not financial advice. Built for builders.