Quick Start: WebSockets - API Documentation

Overview

Kalshi’s WebSocket API provides real-time updates for:

Order book changes
Trade executions
Market status updates
Fill notifications (authenticated connections only)

Connection URL

Connect to the WebSocket endpoint at:

wss://api.elections.kalshi.com/trade-api/ws/v2

For the demo environment, use:

wss://demo-api.kalshi.co/trade-api/ws/v2

Authentication

WebSocket connections require authentication using the same API key signing mechanism as REST endpoints.

For detailed information about API key generation and request signing, see our API Keys documentation.

Required Headers

When establishing the WebSocket connection, include these headers:

KALSHI-ACCESS-KEY: your_api_key_id
KALSHI-ACCESS-SIGNATURE: request_signature
KALSHI-ACCESS-TIMESTAMP: unix_timestamp_in_milliseconds

Signing the WebSocket Request

The signature for WebSocket connections follows the same pattern as REST API requests:

Create the message to sign:
```
timestamp + "GET" + "/trade-api/ws/v2"
```
Generate the signature using your private key (see API Keys documentation)
Include the headers when opening the WebSocket connection

Establishing a Connection

To connect to the WebSocket API, you need to:

Generate authentication headers (same as REST API)
Create a WebSocket connection with those headers
Handle the connection lifecycle

Here’s how to establish an authenticated connection:

import websockets
import asyncio

# WebSocket URL
ws_url = "wss://demo-api.kalshi.co/trade-api/ws/v2"  # Demo environment

# Generate authentication headers (see API Keys documentation)
auth_headers = {
    "KALSHI-ACCESS-KEY": "your_api_key_id",
    "KALSHI-ACCESS-SIGNATURE": "generated_signature",
    "KALSHI-ACCESS-TIMESTAMP": "timestamp_in_milliseconds"
}

# Connect with authentication
async def connect():
    async with websockets.connect(ws_url, additional_headers=auth_headers) as websocket:
        print("Connected to Kalshi WebSocket")

        # Connection is now established
        # You can start sending and receiving messages

        # Listen for messages
        async for message in websocket:
            print(f"Received: {message}")

# Run the connection
asyncio.run(connect())

Subscribing to Data

Once connected, subscribe to channels by sending a subscription command:

import json

async def subscribe_to_ticker(websocket):
    """Subscribe to ticker updates"""
    subscription = {
        "id": 1,
        "cmd": "subscribe",
        "params": {
            "channels": ["ticker"]
        }
    }
    await websocket.send(json.dumps(subscription))

async def subscribe_to_orderbook(websocket, market_tickers):
    """Subscribe to orderbook updates for specific markets"""
    subscription = {
        "id": 2,
        "cmd": "subscribe",
        "params": {
            "channels": ["orderbook"],
            "market_tickers": market_tickers
        }
    }
    await websocket.send(json.dumps(subscription))

Processing Messages

Handle incoming messages based on their type:

async def process_message(message):
    """Process incoming WebSocket messages"""
    data = json.loads(message)
    msg_type = data.get("type")

    if msg_type == "ticker":
        # Handle ticker update
        market = data["data"]["market_ticker"]
        bid = data["data"]["bid"]
        ask = data["data"]["ask"]
        print(f"{market}: Bid ${bid}, Ask ${ask}")

    elif msg_type == "orderbook_snapshot":
        # Handle full orderbook state
        print(f"Orderbook snapshot for {data['data']['market_ticker']}")

    elif msg_type == "orderbook_update":
        # Handle orderbook changes
        print(f"Orderbook update for {data['data']['market_ticker']}")
        # Note: client_order_id field is optional - present only when you caused this change
        if 'client_order_id' in data['data']:
            print(f"  Your order {data['data']['client_order_id']} caused this change")

    elif msg_type == "error":
        error_code = data.get("msg", {}).get("code")
        error_msg = data.get("msg", {}).get("msg")
        print(f"Error {error_code}: {error_msg}")

Connection Keep-Alive

The Python websockets library automatically handles WebSocket ping/pong frames to keep connections alive. No manual heartbeat handling is required. Learn more about automatic keepalive in the websockets documentation.Other WebSocket libraries may require manual ping/pong implementation.

Subscribing to Channels

Once connected, subscribe to specific data channels: To receive real-time ticker updates for all markets:

async def subscribe_to_tickers(self):
    """Subscribe to ticker updates for all markets"""
    subscription_message = {
        "id": self.message_id,
        "cmd": "subscribe",
        "params": {
            "channels": ["ticker"]
        }
    }
    await self.ws.send(json.dumps(subscription_message))
    self.message_id += 1

To subscribe to orderbook or trade updates for specific markets:

async def subscribe_to_markets(self, channels, market_tickers):
    """Subscribe to specific channels and markets"""
    subscription_message = {
        "id": self.message_id,
        "cmd": "subscribe",
        "params": {
            "channels": channels,
            "market_tickers": market_tickers
        }
    }
    await self.ws.send(json.dumps(subscription_message))
    self.message_id += 1

# Example usage:
# Subscribe to orderbook updates
await subscribe_to_markets(["orderbook"], ["KXFUT24-LSV", "KXHARRIS24-LSV"])

# Subscribe to trade feed
await subscribe_to_markets(["trades"], ["KXFUT24-LSV"])

Connection Lifecycle

Initial Connection: Establish WebSocket with authentication headers
Subscribe: Send subscription commands for desired channels
Receive Updates: Process incoming messages based on their type
Handle Disconnects: Implement reconnection logic with exponential backoff

Error Handling

The server sends error messages in this format:

{
  "id": 123,
  "type": "error",
  "msg": {
    "code": 6,
    "msg": "Params required"
  }
}

WebSocket Error Codes

Code	Error	Description
1	Unable to process message	General processing error
2	Params required	Missing params object in command
3	Channels required	Missing channels array in subscribe
4	Subscription IDs required	Missing sids in unsubscribe
5	Unknown command	Invalid command name
7	Unknown subscription ID	Subscription ID not found
8	Unknown channel name	Invalid channel in subscribe
9	Authentication required	Private channel without auth
10	Channel error	Channel-specific error
11	Invalid parameter	Malformed parameter value
12	Exactly one subscription ID required	For update_subscription
13	Unsupported action	Invalid action for update_subscription
14	Market ticker required	Missing market specification
15	Action required	Missing action in update_subscription
16	Market not found	Invalid market ticker
17	Internal error	Server-side processing error

Best Practices

Connection Management

Implement automatic reconnection with exponential backoff
Handle network interruptions gracefully
Use the websockets library’s built-in keepalive

Data Handling

Process messages asynchronously to avoid blocking
Implement proper error handling for malformed messages
Cache initial orderbook state before applying updates

Security

Never expose your private key in client-side code
Rotate API keys regularly
Use secure key storage practices

Performance

Subscribe only to markets you need
Implement message buffering for high-frequency updates
Consider using connection pooling for multiple subscriptions

Complete Example

Here’s a complete, runnable example that connects to the WebSocket API and subscribes to orderbook updates:

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

# Configuration
KEY_ID = "your_api_key_id"
PRIVATE_KEY_PATH = "path/to/private_key.pem"
MARKET_TICKER = "KXHARRIS24-LSV"  # Replace with any open market
WS_URL = "wss://demo-api.kalshi.co/trade-api/ws/v2"

def sign_pss_text(private_key, text: str) -> str:
    """Sign message using RSA-PSS"""
    message = text.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')

def create_headers(private_key, method: str, path: str) -> dict:
    """Create authentication headers"""
    timestamp = str(int(time.time() * 1000))
    msg_string = timestamp + method + path.split('?')[0]
    signature = sign_pss_text(private_key, msg_string)

    return {
        "Content-Type": "application/json",
        "KALSHI-ACCESS-KEY": KEY_ID,
        "KALSHI-ACCESS-SIGNATURE": signature,
        "KALSHI-ACCESS-TIMESTAMP": timestamp,
    }

async def orderbook_websocket():
    """Connect to WebSocket and subscribe to orderbook"""
    # Load private key
    with open(PRIVATE_KEY_PATH, 'rb') as f:
        private_key = serialization.load_pem_private_key(
            f.read(),
            password=None
        )

    # Create WebSocket headers
    ws_headers = create_headers(private_key, "GET", "/trade-api/ws/v2")

    async with websockets.connect(WS_URL, additional_headers=ws_headers) as websocket:
        print(f"Connected! Subscribing to orderbook for {MARKET_TICKER}")

        # Subscribe to orderbook
        subscribe_msg = {
            "id": 1,
            "cmd": "subscribe",
            "params": {
                "channels": ["orderbook_delta"],
                "market_ticker": MARKET_TICKER
            }
        }
        await websocket.send(json.dumps(subscribe_msg))

        # Process messages
        async for message in websocket:
            data = json.loads(message)
            msg_type = data.get("type")

            if msg_type == "subscribed":
                print(f"Subscribed: {data}")

            elif msg_type == "orderbook_snapshot":
                print(f"Orderbook snapshot: {data}")

            elif msg_type == "orderbook_delta":
                # The client_order_id field is optional - only present when you caused the change
                if 'client_order_id' in data.get('data', {}):
                    print(f"Orderbook update (your order {data['data']['client_order_id']}): {data}")
                else:
                    print(f"Orderbook update: {data}")

            elif msg_type == "error":
                print(f"Error: {data}")

# Run the example
if __name__ == "__main__":
    asyncio.run(orderbook_websocket())

This example:

Establishes an authenticated WebSocket connection
Subscribes to orderbook updates for the specified market
Processes both the initial snapshot and incremental updates
Displays orderbook changes in real-time

To run this example:

Replace KEY_ID with your API key ID
Replace PRIVATE_KEY_PATH with the path to your private key file
Replace MARKET_TICKER with any open market ticker
Run with Python 3.7+

Next Steps

Review the WebSocket API Reference for detailed message specifications
Explore Market Data Quick Start for REST API integration
Check out our Demo Environment for testing

​Overview

​Connection URL

​Authentication

​Required Headers

​Signing the WebSocket Request

​Establishing a Connection

​Subscribing to Data

​Processing Messages

​Connection Keep-Alive

​Subscribing to Channels

​Subscribe to Ticker Updates

​Subscribe to Specific Markets

​Connection Lifecycle

​Error Handling

​WebSocket Error Codes

​Best Practices

Connection Management

Data Handling

Security

Performance

​Complete Example

​Next Steps

Overview

Connection URL

Authentication

Required Headers

Signing the WebSocket Request

Establishing a Connection

Subscribing to Data

Processing Messages

Connection Keep-Alive

Subscribing to Channels

Subscribe to Ticker Updates

Subscribe to Specific Markets

Connection Lifecycle

Error Handling

WebSocket Error Codes

Best Practices

Complete Example

Next Steps