Guides··9 min read

Kalshi WebSocket API: Authentication, Books & Recovery

Use Kalshi WebSocket endpoints and authentication correctly. Learn snapshot replacement, sequence-gap recovery and heartbeats with an original offline Python exercise.

Kalshi WebSocket API: Authentication, Books & Recovery
On this page

Kalshi’s WebSocket API streams market and account updates through an authenticated connection. A successful connection is only the first step: a market-data client also needs subscription tracking, an initial book, ordered updates and a recovery policy when data is missing.

Reviewed November 21, 2026. This guide covers Kalshi’s prediction-market Trade API, not every Perps or FIX service. It includes an original offline Python lesson. No API key, account connection or order is used by that download.

Kalshi WebSocket endpoint: production vs demo

The official WebSocket overview recommends dedicated hosts for new integrations:

EnvironmentDedicated WebSocket URL
Productionwss://external-api-ws.kalshi.com/trade-api/ws/v2
Demowss://external-api-ws.demo.kalshi.co/trade-api/ws/v2

The overview says older shared hosts remain supported and describes forward-compatible handling of new fields or message types. A host change alone does not mean the API’s authentication model has changed. Keep the selected environment visible in your configuration and logs.

Does Kalshi WebSocket require an API key?

Yes. The official WebSocket quick start requires authentication at the handshake, including for sessions carrying public market-data channels. It lists the key ID, signature and millisecond timestamp headers, with signing input formed from the timestamp, GET and the WebSocket path.

This differs from certain public REST market-data requests. “Public data” does not automatically mean “unauthenticated transport.” Our Kalshi API-key guide and signing-message builder cover the separate signing concepts; verify the current key algorithm, permissions and environment before implementing a connection.

The quick start also distinguishes channel permissions: a market-data-limited key can access order-book data, but cannot access channels containing only the account’s own activity. A handshake success is therefore not proof that every channel is authorized. Never publish key material as part of a troubleshooting example.

Track commands, subscriptions and markets separately

A command identity, a subscription identity and a market ticker serve different roles. In your own logs, record which request produced which subscription, what markets belong to it and whether each market has received its initial data. A socket-level “connected” badge cannot answer those questions.

The order-book channel reference specifies ticker-based filters, initial snapshots and later deltas. Repeated subscriptions add markets; they do not automatically rebuild existing books. An acknowledgement alone does not establish usable data.

Snapshot replacement vs incremental updates

In an original simplified model, suppose a price level at 0.60 has quantity 10. A signed quantity change of −3 leaves 7. That is different from replacing the quantity with −3 or treating the message as a new whole book.

A later complete snapshot containing only quantity 9 at price 0.55 should replace the old model state. Keeping the old 0.60 level alongside it would invent liquidity absent from the replacement. The channel reference explicitly calls for replacement snapshots, including empty snapshots for determined markets.

Use exact fixed-point or decimal arithmetic for prices and quantities rather than relying on binary floating-point equality as a level key. Our offline example uses Python’s standard-library Decimal. Its field names are teaching labels, not a drop-in decoder for Kalshi’s wire format.

Why a sequence gap can affect more than one market

The channel reference distinguishes subscription-local seq from market-specific exchange clock. It instructs clients to check the subscription sequence for missing messages. For conflated updates, it also warns against discarding a delta merely because its clock is lower than a preceding clock.

Consider this constructed single-subscription stream. All quantities and identifiers are invented:

SequenceTeaching eventModel result
101Snapshot A: 0.60 →10A seeded
102Snapshot B: 0.40 →8B seeded
103A delta: 0.60 →−3 changeA quantity becomes 7
105B delta, with 104 missingInvalidate both local books in this lesson
106A delta while unseededIgnore it pending recovery
107Fresh snapshot A: 0.55 →9A replaced; B still unseeded
108Empty snapshot BB replaced with an empty book

Filtering out B before checking sequence would make the jump from A’s 101 to 103 appear suspicious even though 102 was received correctly. Conversely, ignoring a real subscription gap because it happened near a B message could leave A incorrectly labeled current. Observe sequence at the subscription scope before distributing events to individual market models.

Invalidating all included books is the conservative policy chosen for this lesson. The missing 104 could have affected either market. The official recovery instruction is to request snapshots for all subscribed markets or unsubscribe and resubscribe; simply repeating subscribe does not resynchronize existing books.

Offline Kalshi WebSocket Python recovery lesson

Download the original offline Python exercise, then run:

python3 kalshi-websocket-recovery.py

It prints A’s quantity after the valid delta, confirms both books become unseeded after the gap, and shows A’s replacement and B’s empty recovery snapshot. It deliberately makes no network calls and has no signing or order functions. It is a runnable state-management exercise, not an authenticated WebSocket client or production replay engine.

The lesson uses one fictional subscription and one price-side map per market. A real integration must decode the current schema, track both outcome books, validate quantities and permissions, handle protocol errors and preserve channel lifecycle. Neither the exercise nor passing its examples proves a live feed is complete.

Heartbeat frames are different from text messages

The official keep-alive reference describes WebSocket Ping/Pong control frames. Kalshi sends its heartbeat after ten seconds without a data message; ongoing data restarts that timer. A stream with frequent data may therefore have no recent heartbeat Ping without being dead.

Use the library’s actual control-frame handling rather than inventing a text-message heartbeat from another platform. Track transport activity separately from book freshness: a responsive connection can still have a missing subscription or an unseeded market.

Reconnect with recovery, not just another socket

The quick start says subscriptions and their IDs do not survive disconnection. It recommends backoff and explains that a 429 handshake rejection can reflect either connection concurrency or opening connections too quickly. Preserve the environment and error context rather than assuming every failure means an invalid key.

In your application, a reconnect should enter a recovery state. Keep an old book only as explicitly stale history, clear the previous session’s active subscription identities, subscribe again and wait for the required replacement state. A new transport does not make old prices fresh.

Separate local receipt time, source timestamps, sequence continuity and connection status in monitoring. They answer different questions. Even a newly received book does not guarantee an order of a particular size will later execute at its displayed price.

For the separate budget model, read Kalshi API rate limits, token costs and 429 errors, including an offline burst-capacity example.

A Kalshi streaming review checklist

  1. Confirm Trade API product, environment and current endpoint.
  2. Validate handshake signing and channel-level permissions separately.
  3. Record command, subscription and ticker identities.
  4. Seed each book and replace it when a fresh snapshot arrives.
  5. Check sequence before filtering individual markets.
  6. Distinguish clocks, timestamps and sequence numbers.
  7. Recover all affected markets after a missing-message interval.
  8. Keep transport health separate from data-state health.

For the broader data workflow, read our Kalshi API guide. For another venue’s distinct stream and heartbeat behavior, see Polymarket WebSocket. Alphascope’s market-linked research provides event context alongside these implementation lessons; it does not certify a feed’s execution quality.

Frequently Asked Questions

Does Kalshi WebSocket require authentication for market data?▾

Yes. The current quick start requires an authenticated handshake even for public market-data channels. Channel permissions are a separate check.

Does reconnecting restore Kalshi subscriptions?▾

No. The quick start says subscriptions and their IDs do not carry over. Recreate subscriptions and rebuild the required state rather than treating an old book as current.

Should a new order-book snapshot be merged into old levels?▾

The channel reference instructs clients to replace the local book with the received snapshot. The offline lesson shows why retaining omitted levels invents liquidity.

Is a missing heartbeat Ping proof that the connection is dead?▾

No. The keep-alive reference says incoming data resets the server heartbeat timer. Monitor both data and control-frame activity, plus subscription and book state.

Does the Python download connect to Kalshi?▾

No. It is a standard-library offline state-management exercise with invented events. It uses no credentials, networking, signing or order submission.