Kalshi Order Book API Explained: Endpoints, Auth, and Connection Setup

The Kalshi Order Book API is a tool for accessing real-time data on binary markets. It offers two main interfaces: a REST API for snapshots and a WebSocket API for live updates. The API focuses on bid data due to the reciprocal pricing model, where "YES" and "NO" prices always sum to $1.00. This simplifies data handling and ensures efficiency for traders.

Key features include:

• REST API: Fetch complete order book snapshots for one or multiple markets.
• WebSocket API: Stream real-time updates with minimal latency.
• Authentication: Secure your access with RSA-based credentials and headers.
• Trading Integration: Automate order placement and portfolio management.

To get started, you'll need API credentials, which include a Key ID and a private key. These are used to generate secure headers for authenticated requests. For live trading, the WebSocket API provides continuous updates, while REST endpoints are better for occasional data retrieval.

This API is ideal for developing automated trading systems, reducing manual effort, and accessing accurate market data. It’s free to use but charges a $0.02 fee per executed contract. REST calls are rate-limited, so optimize your usage with features like bulk requests and local caching.

Kalshi Order Book Endpoints

Kalshi provides three endpoints to access its order book data: two REST options for snapshots and one WebSocket for real-time updates. Each serves a distinct purpose depending on your trading requirements. Here’s a closer look at each option and how they work.

The REST endpoint (GET https://api.elections.kalshi.com/trade-api/v2/markets/{ticker}/orderbook) delivers a complete bid snapshot for a specific market. Replace {ticker} with the market's identifier (e.g., "KXHIGHNY-24JAN01-T60") to retrieve the data. This endpoint doesn’t require authentication and includes an optional depth parameter (ranging from 0 to 100) to limit the number of price levels returned. The response is formatted as an orderbook_fp object, containing yes_dollars and no_dollars arrays. Each array consists of two-element string arrays: [price_dollars, count_fp], sorted in ascending order so the highest bid appears last.

The bulk REST endpoint (GET /markets/orderbooks) is designed for retrieving order book data for up to 100 tickers in a single request. This reduces the need for multiple API calls when monitoring several markets. Unlike the single-ticker endpoint, this one requires authentication using the KALSHI-ACCESS-KEY, KALSHI-ACCESS-SIGNATURE, and KALSHI-ACCESS-TIMESTAMP headers.

For real-time updates, the WebSocket endpoint (wss://api.elections.kalshi.com/trade-api/ws/v2) offers a persistent connection. Once subscribed to orderbook_delta, you’ll first receive an orderbook_snapshot, followed by incremental updates that reflect changes in the order book. This approach minimizes bandwidth usage and latency compared to repeatedly polling the REST endpoint. WebSocket connections always require authentication during the handshake. Additionally, you can subscribe to multiple channels (e.g., ticker, trade, fills) within a single connection.

Here’s a quick comparison of the REST and WebSocket endpoints:

Feature	REST (/markets/{ticker}/orderbook)	WebSocket (/ws/v2)
Communication	Request-Response (Polling)	Streaming (Push)
Latency	Higher (limited by polling frequency)	Lower (real-time)
Authentication	Not required for single market	Required for all connections
Data Provided	Full snapshot of bids	Initial snapshot + incremental deltas
Best For	One-off lookups, simple apps	Active trading, live price tracking

Next, we’ll cover how to set up API authentication to securely access these endpoints.

API Authentication Setup

Kalshi endpoints, apart from a few public REST calls, require proper authentication using API credentials, secure headers, and adherence to best practices. Here’s a step-by-step guide to setting everything up.

Getting Your API Credentials

Start by logging into your Kalshi account and navigating to the API Keys section. Click on Create New API Key (or Create Key) to generate your credentials. Kalshi will provide you with:

• Key ID: A unique identifier, such as a952bcbe-ec3b-4b5b-b8f9-11dae589608c.
• Private Key: Delivered in RSA_PRIVATE_KEY format and downloadable as a .key or .txt file.

Once you’ve downloaded your Private Key, make sure to store it securely because you won’t be able to retrieve it later. According to Kalshi:

For security reasons, the private key will not be stored by our service, and you will not be able to retrieve it again once this page is closed.

If you lose the key, you’ll need to generate a new key pair.

You can also create API keys programmatically by sending a POST request to /trade-api/v2/api_keys with your RSA public key in PEM format and specifying the required scopes (e.g., read or write). This process applies to both the demo environment (demo-api.kalshi.co) and production (api.elections.kalshi.com).

Once you have your credentials, you’re ready to configure authentication headers.

Required Authentication Headers

Authenticated requests must include these three headers:

1. KALSHI-ACCESS-KEY: Your unique API Key ID.
2. KALSHI-ACCESS-TIMESTAMP: The current Unix timestamp in milliseconds.
3. KALSHI-ACCESS-SIGNATURE: An RSA-PSS SHA256 signature of the request timestamp, HTTP method, and request path.

To generate the signature:

• Concatenate the timestamp, HTTP method (e.g., GET or POST), and request path (excluding query parameters). For example, if the request is for /trade-api/v2/portfolio/orders?limit=5, sign only /trade-api/v2/portfolio/orders.
• Use RSA-PSS with SHA256 to sign the string.
• Base64-encode the resulting signature.

For WebSocket requests, the path to sign is /trade-api/ws/v2.

Header	Description	Example
KALSHI-ACCESS-KEY	Your unique API Key ID	a952bcbe-ec3b-4b5b-b8f9-11dae589608c
KALSHI-ACCESS-TIMESTAMP	Current Unix time in milliseconds	1703123456789
KALSHI-ACCESS-SIGNATURE	Base64-encoded RSA-PSS signature of the request	base64_encoded_string

Once your headers are set, it’s crucial to implement security measures to protect your keys and requests.

API Security Best Practices

• Never expose your private key in client-side code. Signing should always be performed on a secure backend.
• Store your private key securely. Use encrypted storage or a secure key management system.
• Rotate your keys regularly. This minimizes the risk in case of a key compromise.
• Test in the demo environment first. Before moving to production, ensure your setup works correctly in the demo environment.

Common issues include:

• 401 Unauthorized errors, which may indicate an incorrect Key ID or private key file path.
• Signature mismatches, often caused by including query parameters in the signed path or using seconds instead of milliseconds for the timestamp.

How to Connect and Retrieve Order Book Data

Once authentication is set up, you can access order book data either through REST APIs for snapshots or WebSocket for live updates. Below, we’ll walk through both methods and cover how to handle errors effectively.

Fetching Order Book Data with REST APIs

To fetch an order book snapshot, use the GET endpoint:
https://api.elections.kalshi.com/trade-api/v2/markets/{ticker}/orderbook.

Replace {ticker} with the market ID, such as KXHIGHNY-24JAN01-T60.

You can include the depth parameter to specify the number of price levels to retrieve. This parameter accepts integers between 0 and 100. A value of 0 or any negative number will return all available levels. For instance, adding ?depth=5 to the URL will fetch the top five price levels on each side.

The response is structured in an orderbook_fp object, where prices and contract counts are formatted as strings to eliminate floating-point inaccuracies. Note that REST API calls for market data are rate-limited to approximately 10 requests per second. If you exceed this rate, the server will respond with an HTTP 429 (Too Many Requests) error.

Streaming Real-Time Data via WebSocket

For real-time order book updates, connect to the WebSocket endpoint:

• Production: wss://api.elections.kalshi.com/trade-api/ws/v2
• Testing: wss://demo-api.kalshi.co/trade-api/ws/v2

Authentication is required during the initial WebSocket handshake. Include these headers in your request:

• KALSHI-ACCESS-KEY
• KALSHI-ACCESS-SIGNATURE
• KALSHI-ACCESS-TIMESTAMP

To generate the signature, concatenate the current timestamp, the HTTP method (GET), and the path (/trade-api/ws/v2). Then, sign this string using your private key with RSA-PSS and SHA256.

After establishing the connection, subscribe to the orderbook_delta channel by sending a JSON command. The server will send two types of messages:

• orderbook_snapshot: A complete snapshot of the current order book state.
• orderbook_delta: Incremental updates that include price, side, and changes to apply to your local order book.

Process the orderbook_snapshot first to ensure your local state is in sync before applying any orderbook_delta updates. If you're using Python's websockets library, it automatically handles ping/pong frames to keep the connection alive. For other libraries, you might need to implement this manually. Use exponential backoff for reconnections and handle incoming messages asynchronously to avoid blocking the connection during high-frequency updates.

Error Handling and Response Validation

Whether you're using REST or WebSocket, it’s crucial to validate responses and handle errors appropriately. REST API errors return standard HTTP codes:

• 400: Bad request (e.g., invalid parameters).
• 401: Unauthorized (e.g., missing or invalid credentials).
• 404: Ticker not found.
• 500: Server error.

WebSocket errors are sent as JSON messages with an error code and description. Common examples include:

• 8 (Unknown channel): Invalid channel name.
• 9 (Auth required): Missing authentication.
• 16 (Market not found): Invalid ticker.

Check for the presence of yes_dollars and no_dollars in responses to ensure data integrity. Use high-precision libraries like Python’s Decimal to handle prices and contract counts, avoiding floating-point issues.

When creating RSA-PSS signatures for authenticated requests, always sign the path without query parameters. For example, sign /trade-api/v2/portfolio/orders even if the request URL includes ?limit=5. Also, ensure the KALSHI-ACCESS-TIMESTAMP reflects the current Unix time in milliseconds, not seconds, to prevent signature validation errors.

API Integration Workflow

After connecting to the API and gathering order book data, the next steps involve market discovery, order management, trade execution, and improving system performance.

Finding Markets and Retrieving Order Books

Begin by identifying available markets with the GET /markets endpoint. You can filter results using parameters like status, event_ticker, and series_ticker to refine your search. For active trading, always include status=open in your query to exclude markets that are settled or initialized.

The response is paginated, with a default limit of 100 results per page. However, you can increase this to 1,000 results by using the limit parameter. To navigate through multiple pages of results, use the cursor parameter. Once you've pinpointed the markets you want, access their order books using GET /markets/{ticker}/orderbook for a specific market or GET /markets/orderbooks to retrieve data for up to 100 tickers at once.

Keep in mind that the API only returns bid data due to the reciprocal pricing model. The order book arrays are sorted in ascending order, with the best bid appearing as the last element.

For real-time updates, use the WebSocket endpoint and subscribe to the appropriate channels. Initially, the server sends an orderbook_snapshot containing the full order book state, followed by incremental orderbook_delta updates. Authentication headers are required during the WebSocket handshake, even for accessing public data like tickers and trades.

Once you've gathered the necessary market data, you can move on to executing trades.

Placing Orders Through the API

Orders are placed using the POST /portfolio/orders endpoint, which requires parameters like ticker, action, side, count, type, and yes_price. Be sure to include a unique client_order_id (UUID) to prevent duplicate orders.

To track the status of your orders, use GET /portfolio/orders. Orders can transition through several states: resting (active in the order book), partially_filled (some contracts matched), filled (all contracts matched), canceled (removed by user), or expired (automatically canceled at expiration). You can modify existing orders with POST /portfolio/orders/{order_id}/amend or cancel them using DELETE /portfolio/orders/{order_id}.

For batch processing, the POST /portfolio/orders/batched endpoint allows you to create multiple orders in a single request. Note that a trading fee of $0.02 per contract applies to executed orders, though API access itself is free.

With the basics of order placement covered, the next step is to fine-tune your connection for better performance.

Reducing Latency and Improving Performance

To minimize latency, rely on WebSocket orderbook_delta subscriptions instead of polling REST endpoints. Process updates asynchronously to handle high-frequency data efficiently. After receiving the initial orderbook_snapshot, apply orderbook_delta updates to maintain a local cache, avoiding the need for repeated full snapshots.

Each user is limited to five concurrent WebSocket connections, so it's best to multiplex subscriptions on a single connection. Only subscribe to the specific market tickers relevant to your strategy to conserve bandwidth and processing power. Use the update_subscription command to add or remove tickers from an active session, rather than opening new connections.

Market metadata, such as titles, expiration times, and series information, changes infrequently. Cache this data locally to reduce unnecessary API calls. If you encounter 429 Too Many Requests errors, implement an exponential backoff strategy - waiting 1 second, then 2, then 4, up to 60 seconds - to avoid further throttling. Public market data REST endpoints allow around 30 requests per second, while authenticated operations like orders and portfolio management are capped at 10 requests per second.

Conclusion

The Kalshi Order Book API brings together real-time market data access and automated trade execution through its REST and WebSocket architecture. For snapshots of the order book, use GET /markets/{ticker}/orderbook, and for incremental updates that reflect market changes, connect to wss://api.elections.kalshi.com/trade-api/ws/v2. This setup allows traders to develop responsive trading systems. By simplifying market discovery, order execution, and real-time updates, the API offers a comprehensive toolkit for automated trading.

To set up authentication, you’ll need to generate RSA key pairs and include the following headers in your requests: KALSHI-ACCESS-KEY, KALSHI-ACCESS-TIMESTAMP, and KALSHI-ACCESS-SIGNATURE. It’s important to note that Kalshi’s order book only provides bid data due to its reciprocal pricing model.

The integration process involves discovering markets with GET /markets, fetching order book data, and placing orders through POST /portfolio/orders. For better performance, subscribe only to the tickers you need, keep a local cache of market metadata, and handle orderbook_delta updates asynchronously to keep up with high-frequency data.

Access to the API is free, though there’s a $0.02 fee per contract for executed orders. Public market data requests are capped at about 30 per second, while authenticated operations allow for 10 requests per second. Before moving to the production environment, test your setup in the demo environment at demo-api.kalshi.co to ensure everything runs smoothly.

FAQs

Why does Kalshi’s order book only show bids?

In Kalshi's binary prediction markets, the order book is streamlined by displaying only bids. Why? Because a bid for YES at a specific price automatically translates to an ask for NO at the complementary price. This setup eliminates the need for separate ask listings, showcasing only the highest prices buyers are ready to pay for either outcome. It’s a clean, efficient way to present the market dynamics.

How do I generate the RSA signature for Kalshi API requests?

To create the RSA signature, start by combining the current timestamp (in milliseconds), the HTTP method, and the request path into a single string (e.g., timestamp + HTTP_METHOD + path). Next, use your private RSA key and the RSA-PSS algorithm to sign this string. Once signed, encode the resulting signature in base64 format. Finally, include this base64-encoded signature in the KALSHI-ACCESS-SIGNATURE header of your API request to authenticate.

When should I use REST vs WebSocket for order book data?

When you need a current snapshot of the order book, REST is the way to go. It's perfect for tasks like initial loading or periodic updates since the REST endpoint gives you the latest full state without needing a constant connection.

On the other hand, for real-time updates, WebSocket is your best option. It starts with an initial snapshot and then sends incremental updates, making it ideal for low-latency applications such as trading bots or live dashboards.