pykalshi

The Python client for Kalshi prediction markets. WebSocket streaming, automatic retries, pandas integration, and clean interfaces for building trading systems.

from pykalshi import KalshiClient, Action, Side

client = KalshiClient()

# Place a trade
order = client.portfolio.place_order("KXBTC-25MAR15-B100000", Action.BUY, Side.YES, count=10, yes_price=45)
order.wait_until_terminal()  # Block until filled/canceled

Features

• WebSocket streaming - Real-time orderbook, ticker, and trade data with typed messages
• Automatic retries - Exponential backoff on rate limits and transient errors
• Domain objects - Market, Order, Event with methods like order.cancel(), market.get_orderbook()
• pandas integration - .to_dataframe() on any list of results
• Jupyter support - Rich HTML display for markets, orders, and positions
• Local orderbook - OrderbookManager maintains state from WebSocket deltas
• Type safety - Pydantic models and typed exceptions throughout

Installation

pip install pykalshi

# With pandas support
pip install pykalshi[dataframe]

Get your API credentials from kalshi.com and create a .env file:

KALSHI_API_KEY_ID=your-key-id
KALSHI_PRIVATE_KEY_PATH=/path/to/private-key.key

Quick Start

Browse Markets

from pykalshi import MarketStatus, CandlestickPeriod

client = KalshiClient()

# Search markets
markets = client.get_markets(status=MarketStatus.OPEN, limit=100)
btc_markets = client.get_markets(series_ticker="KXBTC")

# Get a specific market
market = client.get_market("KXBTC-25MAR15-B100000")
print(f"{market.title}: {market.yes_bid}¢ / {market.yes_ask}¢")

# Market data
orderbook = market.get_orderbook()
trades = market.get_trades(limit=50)
candles = market.get_candlesticks(start_ts, end_ts, period=CandlestickPeriod.ONE_HOUR)

Trading

from pykalshi import Action, Side, OrderType, OrderStatus

# Check balance
balance = client.portfolio.get_balance()
print(f"${balance.balance / 100:.2f} available")

# Limit order
order = client.portfolio.place_order(market, Action.BUY, Side.YES, count=10, yes_price=50)

# Market order
order = client.portfolio.place_order(market, Action.BUY, Side.YES, count=10, order_type=OrderType.MARKET)

# Manage orders
order.wait_until_terminal()  # Block until filled/canceled
order.modify(yes_price=45)   # Amend price
order.cancel()               # Cancel

# View portfolio
positions = client.portfolio.get_positions()
fills = client.portfolio.get_fills(limit=100)
orders = client.portfolio.get_orders(status=OrderStatus.RESTING)

Real-time Streaming

from pykalshi import Feed, TickerMessage, OrderbookSnapshotMessage

async with Feed(client) as feed:
    await feed.subscribe_ticker("KXBTC-25MAR15-B100000")
    await feed.subscribe_orderbook("KXBTC-25MAR15-B100000")
    await feed.subscribe_trades("KXBTC-25MAR15-B100000")

    async for msg in feed:
        match msg:
            case TickerMessage():
                print(f"Price: {msg.price}¢")
            case OrderbookSnapshotMessage():
                print(f"Book: {len(msg.yes)} yes levels, {len(msg.no)} no levels")

Local Orderbook

from pykalshi import Feed, OrderbookManager

manager = OrderbookManager()

async with Feed(client) as feed:
    await feed.subscribe_orderbook(ticker)

    async for msg in feed:
        manager.apply(msg)
        book = manager.get(ticker)
        best_bid = book["yes"][0] if book["yes"] else None

pandas Integration

# Any list result has .to_dataframe()
positions_df = client.portfolio.get_positions().to_dataframe()
markets_df = client.get_markets(limit=500).to_dataframe()
fills_df = client.portfolio.get_fills().to_dataframe()

# Candlesticks and orderbooks too
candles_df = market.get_candlesticks(start, end).to_dataframe()
orderbook_df = market.get_orderbook().to_dataframe()

Error Handling

from pykalshi import InsufficientFundsError, RateLimitError, KalshiAPIError

try:
    order = client.portfolio.place_order(...)
except InsufficientFundsError:
    print("Not enough balance")
except RateLimitError:
    pass  # Client auto-retries with backoff
except KalshiAPIError as e:
    print(f"{e.status_code}: {e.error_code}")

Examples

See the examples/ directory:

• demo.ipynb - Interactive notebook with rich display examples
• basic_usage.py - Browse markets and check portfolio
• place_order.py - Place and manage orders
• stream_orderbook.py - WebSocket streaming patterns
• momentum_bot.py - Simple trading bot example

Why pykalshi?

	pykalshi	kalshi-python (official)
WebSocket streaming	✓	—
Automatic retry/backoff	✓	—
Rate limit handling	✓	—
Domain objects	✓	—
pandas integration	✓	—
Jupyter display	✓	—
Local orderbook	✓	—
Typed exceptions	✓	—
Pydantic models	✓	—
Full API coverage	—	✓

The official SDK is auto-generated from the OpenAPI spec. pykalshi adds the infrastructure needed for production trading: real-time data, error recovery, and ergonomic interfaces.

Links

• Kalshi API Reference
• kalshi-python (official SDK)

---

This is an unofficial library and is not affiliated with Kalshi.