> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.immix.xyz/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.immix.xyz/_mcp/server. # Overview **`Auth request — sent`** ```json title="Auth request — sent" { "op": "auth", "params": { "token": "" } } ``` **`Subscribe request — sent`** ```json title="Subscribe request — sent" { "op": "subscribe", "params": { "topics": [ "trade.{symbol}" ] } } ``` **`Unsubscribe request — sent`** ```json title="Unsubscribe request — sent" { "op": "unsubscribe", "params": { "topics": [ "trade.{symbol}" ] } } ``` **`Op ack — received`** ```json title="Op ack — received" { "op": "subscribe", "success": true, "topics": [ { "topic": "trade.{symbol}", "state": "live" } ] } ``` **`Heartbeat event — received`** ```json title="Heartbeat event — received" { "event": "heartbeat", "data": { "streamAgeMs": 0 } } ``` Each frame is its shape, read off the contract: `` stands for a value, and a union shows its first form. **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 | Topic | Page | | --------------------------------- | ------------------------------------------------------------- | | `trade.{symbol}` | [Trades](/api-reference/market-data/trades) | | `tob.{symbol}` | [Top of book](/api-reference/market-data/top-of-book) | | `ticker.{symbol}` | [Ticker](/api-reference/market-data/ticker) | | `candlestick.{symbol}.{interval}` | [Candlesticks](/api-reference/market-data/candlesticks) | | `index.{pair}` | [Index price](/api-reference/market-data/index-price) | | `mark.{symbol}` | [Mark price](/api-reference/market-data/mark-price) | | `funding.{symbol}` | [Funding rate](/api-reference/market-data/funding-rate) | | `oi.{symbol}` | [Open interest](/api-reference/market-data/open-interest) | | `book.{symbol}` | [Order book](/api-reference/market-data/order-book) | | `agg_book.{name}.{tier}` | [Aggregated book](/api-reference/market-data/aggregated-book) | | `vol_book.{name}.{tier}` | [Volume ladder](/api-reference/market-data/volume-ladder) | | `health` | [Venue health](/api-reference/market-data/venue-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. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------------------- | | `op` | string | Yes | `auth` | | `reqId` | string | No | client correlation id, echoed verbatim on the ack | | `params` | object | Yes | | | > `token` | string | Yes | | ## 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. | Parameter | Type | Required | Description | | ---------- | --------------------------- | -------- | ------------------------------------------------- | | `op` | string | Yes | `subscribe` | | `reqId` | string | No | client correlation id, echoed verbatim on the ack | | `params` | object | Yes | | | > `topics` | array of strings or objects | Yes | | ## Unsubscribe request | Parameter | Type | Required | Description | | ---------- | ---------------- | -------- | ------------------------------------------------- | | `op` | string | Yes | `unsubscribe` | | `reqId` | string | No | client correlation id, echoed verbatim on the ack | | `params` | object | Yes | | | > `topics` | array of strings | Yes | | ## Op ack | Parameter | Type | Required | Description | | -------------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `op` | string | Yes | One of `auth`, `subscribe`, `unsubscribe`, `error`. | | `reqId` | string | No | | | `success` | boolean | Yes | | | `error` | string | No | One of `auth_required`, `invalid_token`, `unknown_op`, `malformed`, `too_many_topics`. | | `topics` | array of objects | No | answers ride in request order — the correlator for entries whose topic could not compose (error rows echo the composed topic best-effort, absent parts empty) | | > `topic` | string | Yes | | | > `state` | string | Yes | live: 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`. | | > `priceScale` | integer | No | composite 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 | | > `qtyScale` | integer | No | composite rows only — the resolved output qty scale; as priceScale | | > `code` | string | No | composite 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`. | | > `message` | string | No | supplementary human text naming the offending source or field — never something a client parses | ## Heartbeat event | Parameter | Type | Required | Description | | --------------- | ------- | -------- | ----------------------------------------------------------------- | | `event` | string | Yes | `heartbeat` | | `data` | object | Yes | | | > `streamAgeMs` | integer | Yes | the stream-freshness floor — a quiet market vs a stalled pipeline |