Skip to navigation
Market Data WebSocket

Candlesticks

Candlestick bars folded from sequenced trades: identical, bar for bar, to the candle history the ClickHouse cascade serves — one event-time axis, one set of bucket rules.

URL wss://marketdata.immix.xyz/

Topic candlestick.{symbol}.{interval}

Topic parameterDescription
symbolrefdata’s canonical symbol, e.g. OKX@BTC/USDT
intervalone of components.schemas.candleInterval, e.g. ONE_MINUTE

Request parameters

ParameterTypeRequiredDescription
opstringYessubscribe
reqIdstringNoclient correlation id, echoed verbatim on the ack
paramsobjectYes
> topicsarray of stringsYesthe dotted topic string, e.g. trade.OKX@BTC/USDT or candlestick.OKX@BTC/USDT.ONE_MINUTE.250ms

Response parameters

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

Push data parameters

ParameterTypeRequiredDescription
eventstringYescandlestick
topicstringYes
seqstringNoprovenance global sequence, as a decimal string
seqTsstringNoprovenance sequencerTs, epoch-ns as a decimal string
dataobjectYes
> snapshotbooleanYestrue exactly on the subscribe-time frame (never conflated); updates carry one bar
> intervalstringYesThe candle interval vocabulary, shared with the candle-history surface so stream closes and history rows describe the same buckets. TEN_SECONDS is deliberately absent: a stream interval the history query cannot return would break stream/history consistency the day it shipped. One of ONE_MINUTE, FIVE_MINUTES, FIFTEEN_MINUTES, THIRTY_MINUTES, ONE_HOUR, FOUR_HOURS, TWELVE_HOURS, ONE_DAY.
> barsarray of objectsYesoldest to newest; apply keyed on timestamp
> > timestampstringYesbucket start, epoch-ns as a decimal string, UTC-aligned to an epoch multiple of the interval — the same normalization the candle-history query applies
> > openstringYesexact decimal string in shortest form, at the scale the bar holds its prices at (high, low and close alike) — the digit count is not a contract
> > highstringYes
> > lowstringYes
> > closestringYes
> > volumestringYesexact decimal string in shortest form, at the scale the bar holds its quantities at
> > countintegerYestrades folded into the bar; 0 marks a carried empty bar
> > closedbooleanYesfinal bars never conflate; re-applying a final — over its own partial, or a repeat received around a subscribe — is idempotent (apply keyed on the bucket timestamp, final values win)

Behaviour

The raw form streams a forming-bar partial per folded trade; the conflated form candlestick.{symbol}.{interval}.{tier} delivers the latest forming bar once per tick. Closed bars never conflate: every elapsed interval closes — zero-trade intervals as a carried close (open = high = low = close = previous close, volume “0”, count 0) — released once the stream’s consumed event-time frontier passes the bucket boundary (never wall clock: under catch-up closes arrive late, never wrong). Per topic, the update flow a session sees after its snapshot delivers exactly one closed: true frame per bucket, before any frame of the next bucket; bucket timestamp continuity is the channel’s integrity signal, and seq/seqTs are fact provenance (repeats legal). Around the subscribe itself, snapshot and topic broadcasts may overlap — a just-subscribed session can receive finals its snapshot already carried, or one older filling toward them; re-applying a final keyed on the bucket timestamp is a no-op, never desync. Subscribing answers live and pushes one snapshot: true frame — the last two closed bars plus the forming bar, oldest to newest, one apply loop — or bars: [] with seq/seqTs omitted for a never-traded instrument, whose boundaries then stay silent until a first close exists. Long-disconnect catch-up is the candle-history query, not this stream. The interval segment is mandatory (components.schemas.candleInterval); the object subscribe form {“channel”:“candlestick”,“instrument”:SYMBOL,“interval”:INTERVAL,“throttle”:TIER} is equivalent and echoed normalized as the dotted string.