Skip to navigation

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.

Authenticating. Present exactly one credential on the WebSocket handshake. A browser puts a ticket in the URL (?ticket=…), created just before with the REST API’s POST /ws-tickets and {"stream": "market-data"}: short-lived, single-use, made for a browser that cannot send a header on the handshake. Any other client sends its bearer token as Authorization: Bearer …. Accepted, the session’s first frame is sessionOpened, and the session may subscribe at once — there is no auth op. Refused, there is no session at all: the handshake is answered with an HTTP status, which a browser cannot read (below) — 400 both credentials or a malformed request, 401 no credential, or one that does not verify or has expired, 403 an Origin the deployment does not allow, 503 a member not ready to admit it (retry: a browser with a new ticket, any other client with its bearer token). A session the gateway opened but could not hand its credential to — rare, and only under load — is closed with code 4001: reconnect with a fresh credential.

A refused handshake, in a browser. A browser can read none of those statuses: its WebSocket reports every failed handshake alike — an error event, then close with code 1006, an empty reason and wasClean: false, and no open — whatever the gateway answered, as it reports a gateway it never reached. A browser reads its refusals at POST /ws-tickets instead, which admits the caller as every REST call does: stop on that call’s 401 (a token that does not verify) or 403 (a user the platform refuses). Then treat a handshake that fails on a ticket you have just created as the 503: back off, then create a new ticket and connect with it at once (one created before the wait can expire during it), with a cap on the attempts. This gateway refuses such a ticket only for what a new one cures — a member not ready to admit it, a ticket that expired before it was checked — or for a token that lapsed after the ticket was created, which the next POST /ws-tickets answers 401. What no retry clears is a mistake in the client — tickets created for trading, or one reused across attempts — or a fault of the deployment’s — an origin the REST API serves that this socket does not allow, or a member that cannot verify the REST API’s tickets — and the cap is what bounds those. The 4001 above comes after the socket opened, so a browser reads it on the close event.

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

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 subscribe, unsubscribe, error.
reqIdstringNo
successbooleanYes
errorstringNoOne of 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