Skip to navigation
Market Data WebSocket

Overview

Client-facing market data distribution: OKX trades, L2 books with the syncing/stale contract, and top-of-book — raw or conflated per tier.

URL wss://marketdata.immix.xyz/

Subscriptions are acknowledged per topic (live, syncing for a book the gateway does not yet hold synced, or error); a subscribed tob topic immediately receives the current image, a subscribed synced book its snapshot, as session-targeted pushes; a syncing book’s snapshot is pushed unprompted the moment the gateway syncs (at latest one connector restate interval). A mid-stream chain break pushes the book stale marker; the healing restatement follows. A session whose send queue overflows is disconnected, not throttled — reconnect and resubscribe; snapshots are local reads. Every session receives a heartbeat carrying the stream-freshness floor. Client-configured aggregated books (agg_book) compose the served book folds per subscription — object-form subscribe entries, tier-only conflation, full images with per-venue attribution, and explicit degraded/recovered facts when a source cannot be served.

Topics

TopicPage
trade.{symbol}Trades
tob.{symbol}Top of book
ticker.{symbol}Ticker
candlestick.{symbol}.{interval}Candlesticks
index.{pair}Index price
mark.{symbol}Mark price
funding.{symbol}Funding rate
oi.{symbol}Open interest
book.{symbol}Order book
agg_book.{name}.{tier}Aggregated book
vol_book.{name}.{tier}Volume ladder
healthVenue health

Auth request

Present a JWT verified against the deployment’s JWK domain — signature and the registered exp/nbf claims, plus the aud/iss claims the deployment configures (unconfigured, any unexpired token from the domain is accepted). Required before subscribe when auth is enabled.

ParameterTypeRequiredDescription
opstringYesauth
reqIdstringNoclient correlation id, echoed verbatim on the ack
paramsobjectYes
> tokenstringYes

Subscribe request

Subscribe to topics. The ack answers per topic with state live (data flows now) or error; partial acceptance is explicit — one bad symbol never rejects the batch.

ParameterTypeRequiredDescription
opstringYessubscribe
reqIdstringNoclient correlation id, echoed verbatim on the ack
paramsobjectYes
> topicsarray of strings or objectsYes

Unsubscribe request

ParameterTypeRequiredDescription
opstringYesunsubscribe
reqIdstringNoclient correlation id, echoed verbatim on the ack
paramsobjectYes
> topicsarray of stringsYes

Op ack

ParameterTypeRequiredDescription
opstringYesOne of auth, subscribe, unsubscribe, error.
reqIdstringNo
successbooleanYes
errorstringNoOne of auth_required, invalid_token, unknown_op, malformed, too_many_topics.
topicsarray of objectsNoanswers ride in request order — the correlator for entries whose topic could not compose (error rows echo the composed topic best-effort, absent parts empty)
> topicstringYes
> statestringYeslive: data flows now (latest-image lanes — tob, mark, funding, oi, ticker — answer live whether or not an image is held yet; the first image flows on arrival). syncing (book topics): the gateway holds no synced book yet — the snapshot is pushed unprompted the moment it syncs, at latest one connector restate interval. error on a plain (string-topic) row, no code: the topic composed nothing, and it never arms retroactively. Either the channel is outside the vocabulary or the tier suffix is outside the configured set (an unrecognized suffix reads as part of the symbol) — correct the topic — or the symbol is unknown to the gateway’s refdata fold (derivative symbols are refdata’s ccxt spelling BASE/QUOTE:SETTLE, e.g. OKX@BTC/USDT:USDT — there is no :SWAP form) — resubscribe once refdata holds the instrument. Composite rows: live iff every enabled source book is synced, stated within the topic’s output scales, AND every required FX pair is current (the full image pushes immediately); syncing otherwise, kept by the first tick at which the composite becomes computable — a source out for precision is named by a degraded frame at that tick, since syncing alone does not say it; a composite error row carries code. One of live, syncing, error, unsubscribed, not_subscribed.
> priceScaleintegerNocomposite live/syncing rows only — the resolved output price scale (max over all configured sources’ reference records, disabled included), bounding the fractional digits any price on the topic can carry; never padding. It holds until a status rescaled frame on the topic restates it
> qtyScaleintegerNocomposite rows only — the resolved output qty scale; as priceScale
> codestringNocomposite error rows only — the closed vocabulary clients parse; every validation failure maps to exactly one code. One of unknown_channel, bad_name, bad_tier, tier_required, name_in_use, unknown_instrument, duplicate_source, mixed_base_asset, unit_mismatch, bad_normalisation, bad_depth, bad_ladder, too_many_sources, budget_exceeded, malformed.
> messagestringNosupplementary human text naming the offending source or field — never something a client parses

Heartbeat event

ParameterTypeRequiredDescription
eventstringYesheartbeat
dataobjectYes
> streamAgeMsintegerYesthe stream-freshness floor — a quiet market vs a stalled pipeline