Skip to main content
Streams OHLCV candle buckets that match the subscription’s filters, updating each bucket as it forms. Each update identifies the series it belongs to, so one subscription can feed many chart series, and {} matches every token bucket on every chain. Subscribe on an open stream connection. See WebSocket streams for connections, frames and reconnection, and Filtering streams for how keys, lists and ranges combine.

Filters

Token and pool buckets

Without pools, the buckets are token buckets, and each one aggregates every pool the token trades in. With pools, the buckets are the named pools’ buckets.
  • tokens and pools each cover every chain in their address family that chains includes.
  • Omit a list to match every address. An empty list is rejected.
  • pools rejects the zero address.
  • A pool bucket has no liquidity value, so it never matches liquidityUsd or liquidityNative.

Bucket values

  • changePct and rangePct are computed from the bucket in the subscription’s metric and denomination. A bucket with a zero open never matches either key.
  • An omitted timeframes matches every timeframe.

Token state

token tests the latest state of the bucket’s token, as on spot.trades. A token has a state only after it changes while a subscription with a token key is open, and the state expires after 15 minutes without a change.

Options

These options are top-level fields of the subscribe frame, alongside filters, not inside it.
string
default:"marketCap"
price for price candles, or marketCap for market-cap candles.
string
default:"usd"
usd for US dollars, or native for the chain’s native unit.
boolean
default:"false"
Sends only each bucket’s final state instead of every update. Cannot be combined with throttleMs.
integer
default:"0"
Minimum interval between updates of one series, in milliseconds, from 0 to 60,000. The first update in an interval is sent immediately. Later updates in the same interval are merged into the newest, which is sent when the interval ends. 0 sends every update.
To follow several metrics or denominations, open a separate subscription for each.

Closed buckets

With closedOnly: true, a bucket’s final state is sent 2 seconds after the bucket ends, or as soon as a newer bucket of the same series opens.
  • A bucket whose final state does not match the filter is not sent.
  • A late change to a bucket that was already sent is sent again, as a correction.
  • One subscription tracks at most 10,000 open buckets. Beyond that, new series are not sent, so narrow the filter with tokens or timeframes.

Message format

Each update’s data is the current state of one bucket, in the same shape that OHLCV candles returns, plus the four fields that identify its series. An open bucket is sent again on every trade, so key each candle on chain, token, pool, timeframe and time: replace a candle with the same key, and append a new one.
string
required
string
required
Token address.
string | null
required
Pool address of a pool bucket; null on a token bucket.
string
required
Bucket size, such as 1m.
integer
required
Bucket open time, in milliseconds.
number
required
First value in the bucket.
number
required
Highest value in the bucket.
number
required
Lowest value in the bucket.
number
required
Latest value in the bucket.
number
required
Traded volume in the bucket, in the subscription’s denomination.
Candle values are JSON numbers, not decimal strings. See Candles are numbers. To load history from before the stream starts, read candles with the same timeframe, metric and denomination from OHLCV candles.

Errors

Unsupported filters

spot.candles rejects the following filters. Use the replacement in the right column instead.