Skip to main content
Live in production, still flag-gated. Perpetuals are gated by PERPETUALS_PUBLIC_API_ENABLED, enabled in production and staging today; a deployment with the flag off returns 404 for every perpetual route. Read Overview before writing code.
What a perpetual book contains, how deep you can ask for, which books are refused as invalid, and why a book can vanish from the stream without anything being broken. Perp books use direct bid and ask prices. They do not use prediction-market complement arithmetic. A book can contain far more levels than a prediction book, so depth, aggregation, backpressure, and recovery are first-class parts of the contract.
Beta: Read-only REST snapshots and live v2 WebSocket book snapshots are available for Hyperliquid Perps, Polymarket Perps, and Kalshi Margin.

​
Canonical book view

A book view is identified by:
  • instrument
  • venue connection and source epoch
  • book_view_id
  • requested or available maximum depth
  • price aggregation rule
Snapshots from different views cannot be combined. A venue’s unaggregated book, a 100-level view, and a grouped-price view are distinct states even when they describe the same instrument. Never merge books across venues, epochs, or book_view_id values.
Each level has an exact price and exact quantity. Sides are explicit. Bids are ordered highest first and asks lowest first.

​
Snapshot

A snapshot contains the complete state for its declared view, plus sequence, source cursor, timestamps, and source context. A snapshot with an incorrect instrument, view, connection, or epoch is rejected before it can alter state.
An empty book is refused, not published. The general Kairos model treats an empty, correctly identified snapshot as valid — it clears the book. The perpetual v2 stream does not. Both the producer and the gateway refuse a snapshot with no bids and no asks, so a book that empties out stops publishing rather than publishing a cleared book. A one-sided book (bids only, or asks only) is valid and does publish. Treat prolonged silence, not an empty frame, as the signal that a perpetual book has drained.

​
Book validity

Best bid equal to best ask — a locked book — is where the two live surfaces differ, and the difference is deliberate rather than a gap:
A perpetual book that locks disappears from the v2 stream until it unlocks. Do not read that gap as a connection fault. The same instrument polled over REST during the lock returns normally.

​
Live v2 book stream

All perpetual venues publish the same kairos.v2.BookSnapshot. Prices and quantities use ExactDecimal, so small-token prices and large quantities do not depend on a fixed integer scale and cannot be silently clamped into a plausible but false book. Every message is a complete replacement. Hyperliquid and Polymarket Perps originate as venue book images. Kalshi Margin applies authenticated venue updates to an internal book, then publishes the complete validated image. The producer refuses empty or crossed books, missing ownership epochs, non-canonical metadata, and invalid values. The public gateway independently checks subject/payload identity, positive exact values, side ordering, crossing, view metadata, source context, and sequence monotonicity before fan-out. Two view fields are fixed for every perpetual venue today, and max_depth is checked against the payload:
checksum is defined on the message but never populated for perpetuals. Do not build a recovery rule that waits for one.
See Streaming and recovery for the 0x40 0x02 frame and reconnect algorithm.

​
Deep-book controls

Depth is not silently truncated. Any cap is declared in the view metadata. Request only the depth you can process, bound your buffers, and resnapshot instead of allowing unbounded lag. Coalescing is allowed only when it preserves the documented state contract.

​
The depth parameter

?depth= on the REST snapshot is optional and defaults to the venue’s own ceiling: A flat default would mark every Hyperliquid snapshot depth-limited for no reason and ask Kalshi for less book than it has.

​
Depth reporting

The REST snapshot reports what it actually got:

​
Per-venue book metadata

The v2 stream never populates order_count.

​
Deltas: defined, not published

No perpetual delta is published in the beta. Every perpetual venue is emitted as BOOK_FEED_MODE_SNAPSHOT_ONLY, and the gateway rejects any other feed mode. Read this section as the shape a future delta feed would take, not as a message you will receive today.
The canonical schema defines kairos.v2.BookDelta with level updates keyed by (side, price, action), where BOOK_UPDATE_ACTION_DELETE removes a level and BOOK_UPDATE_ACTION_UPSERT replaces its quantity. A delta applies only when source_epoch matches and previous_sequence equals the consumer’s current sequence. The canonical sequence is a Kairos sequence for one declared stream scope. The venue’s native sequence is retained separately, in source_sequence, with its scope named in transport_sequence_domain. Native sequence numbers may be connection-wide or shared across instruments and therefore must not be assumed contiguous per instrument.

​
Applying a stream

The general algorithm, for a feed that has deltas:
  1. Subscribe and buffer incoming deltas.
  2. Fetch or receive a snapshot for the same view and source epoch.
  3. Validate identity and install the snapshot.
  4. Discard buffered events already covered by the snapshot fence.
  5. Apply the remaining contiguous canonical deltas.
  6. On a gap, epoch change, checksum failure, or view mismatch, invalidate the state and repeat recovery.
Consumers must not display or trade from a book while it is invalid.
For the perpetual beta this collapses to steps 3 and 4 alone. There are no deltas to buffer and no checksum to fail, so every frame installs directly. Streaming and recovery gives the snapshot-only algorithm that actually applies.

​
Snapshot-only venues

Some sources deliver full-book images instead of true deltas. Kairos preserves that fact. It may publish snapshots at each update or derive deltas only when the derivation is deterministic and marked as derived. A derived delta does not acquire a venue-native sequence that never existed. Next: Trades and candles.