Skip to main content
⚠ Live in production, flag-gated, no SLA The perpetual surface is behind a rollout flag, on in production and staging today. Where it is off, every REST route returns 404 and the WebSocket refuses a perps_book subscription — treat both as “not enabled here”, not as an outage. Beta contracts can change before general availability and do not carry a production SLA. “Beta” is the maturity of the feature. It is not a promise that every environment has the rollout flag enabled at the same time.
What is deployed today, what the pipeline validates before you see a byte, how it fails, and what is explicitly out of scope. Read this before you decide how much to trust a frame. The beta is one implementation, not a collection of mock contracts. Venue discovery enrolls instruments, the streamer maintains live books, the canonical v2 protobuf is published through NATS, a compacted checkpoint is written for recovery, and the WebSocket gateway validates and fans out that same v2 payload.

​
Live beta status

Every item in this table is deployed as part of the beta: The beta endpoint is:
Staging serves the same contract at wss://staging-stream.kairos.trade for integration testing.

​
Supported book venues

Use the canonical instrument_id returned by GET /perpetuals/instruments. Do not send a display symbol such as BTC when the catalog returns a different ID.
The REST snapshot is addressed the other way round — by the venue-native id. BTC there, hl-mainnet-btc-usdt here. See Overview.

​
Coverage is not the whole venue

Enrollment decides which books are warm, and it is not uniform: Hyperliquid is capped because the adapter opens one socket per instrument and the venue limits connections per IP. Delisted assets are skipped, and two symbols that differ only by case collapse to one canonical id and occupy one slot.
A venue can be listed here and still be dark in your environment. Enrollment sits behind a runtime rollout flag plus a per-provider enable flag. An instrument that is not enrolled has no live book and no checkpoint — and a subscription to it succeeds and stays silent.

​
What the book stream guarantees

A delivered WebSocket snapshot has passed all of these checks:
  • the NATS subject, provider enum, and InstrumentRef.instrument_id agree
  • required instrument, asset-role, environment, integration, and source fields are populated
  • prices and quantities are positive canonical ExactDecimal values
  • bids are strictly descending, asks are strictly ascending, and the best bid is strictly below the best ask — a locked book is refused along with a crossed one
  • at least one side has a level; a fully empty book is refused
  • source_epoch, sequence, and received_time_ns are nonzero, and event_time_ns is either absent or nonzero
  • the feed declares BOOK_FEED_MODE_SNAPSHOT_ONLY
  • aggregation is price, book_view_id and transport_sequence_domain are non-empty, and max_depth is at least the number of levels carried
  • instrument_type is INSTRUMENT_TYPE_PERPETUAL and the source context is SOURCE_MODE_DIRECT
  • stale or duplicate sequence values are dropped within a source epoch, and an older epoch is dropped outright
The beta emits snapshots only. It does not dual-publish a v1 perpetual book and a v2 perpetual book. Prediction-market v1 channels are unaffected.

​
Failure behavior

The pipeline fails closed:
  • an instrument absent from the canonical catalog is not published
  • catalog responses are revalidated and refreshed, including after new auto-enrolled listings appear
  • a missing ownership epoch, empty or crossed book, invalid decimal, identity mismatch, or malformed protobuf is dropped before public fan-out
  • checkpoint stream initialization is required when the beta is enabled; the producer does not silently run without its recovery boundary
  • an owner or upstream-connection change advances the source epoch and starts a new sequence lineage; a sequence regression inside one epoch is rejected
⚠ Every one of these rejections is silent There is no error frame for bad data. The frame is simply not fanned out. The only WebSocket errors a perpetual client sees are control-request rejections, listed in Streaming and recovery. Acknowledgment proves that the request is valid. It is not a freshness guarantee, and — because the gateway does not check the instrument id against the catalog — it is not proof that the instrument exists either. If a subscription is acknowledged before the first snapshot is cached, the client waits for the next live snapshot.

​
REST snapshot staleness fences

The read-only snapshot also fails closed rather than serving old data. A composite that violates any of these returns 502 upstream instead of a partially stale body: The composite fetch itself has a 12-second deadline across all upstream venue calls, and concurrent requests for the same (venue, instrument, depth) share one in-flight fetch.
A 502 from the snapshot can mean “the data was stale”, not “the venue is down”. Retry with backoff rather than assuming an outage.

​
Recovery boundary

The checkpoint subject stores the newest complete BookSnapshot for each venue and instrument. Internal consumers use it as the state boundary after a restart or sequence gap. Public WebSocket clients receive full replacement snapshots, so their recovery rule is simpler:
  1. Treat every 0x40 0x02 frame as a complete replacement.
  2. Track (source_epoch, sequence) per instrument.
  3. Accept a larger epoch and reset the local sequence.
  4. Within one epoch, accept only a strictly larger sequence.
  5. Reconnect if the stream becomes stale according to your own product limit.
Do not merge books across venues, epochs, or book_view_id values.

​
Outside the public market-data beta

Private balances, positions, orders, fills, authenticated venue feeds, and order entry are not part of this public market-data beta. Their design pages describe intended semantics, not callable endpoints — the canonical schema carries no message type for any of them. Retention, regional latency targets, rate limits for a generally available product, and an SLA will be published separately. Also defined in the schema but never published:
  • perpetual book deltas
  • public trades
  • trade and quote candles
  • market-state updates
  • funding-rate updates
  • public liquidations
The book snapshot is the only v2 perpetual message on the wire. Everything else public reaches you through the REST snapshot.
There is no perpetual history API. Every REST field is proxied live from the venue at request time, and being enabled in production does not mean Kairos stores a perpetual history you can backfill from. There is no endpoint that serves one, for any venue. Treat the snapshot as a point-in-time read and keep your own history.
Market data can be delayed, unavailable, or differ from the price used by a venue risk engine. It is not an execution, margin, liquidation, or investment guarantee.
Next: Streaming and recovery.