> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metastreams.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# spot.candles

> One token's candles at one timeframe, metric and denomination, as they form.

Subscribe on an open stream connection. See [Connecting to streams](/streams/overview) for the connection, frames and reconnecting.

## Filters

<ParamField body="chain" type="string" required>
  The [chain slug](/concepts/chains).
</ParamField>

<ParamField body="token" type="string" required>
  The token's address.
</ParamField>

<ParamField body="timeframe" type="string" default="1m">
  The bucket size: `1s`, `5s`, `15s`, `30s`, `1m`, `3m`, `5m`, `15m`, `30m`, `1h`, `4h`, `6h`, `12h`, `1d` or `7d`.
</ParamField>

<ParamField body="metric" type="string" default="marketCap">
  `price` for price candles, or `marketCap` for market-cap candles.
</ParamField>

<ParamField body="denomination" type="string" default="usd">
  `usd` for US dollars, or `native` for the chain's native unit.
</ParamField>

To follow several timeframes or metrics for one token, open one subscription for each.

## Update

Each update's `data` is the current state of one bucket. A bucket can arrive several times while it is open. Replace the candle that has the same `time`, and append one with a new `time`.

<ResponseField name="time" type="integer" required>
  The bucket's open time, in milliseconds.
</ResponseField>

<ResponseField name="open" type="number" required>
  The first value in the bucket.
</ResponseField>

<ResponseField name="high" type="number" required>
  The highest value in the bucket.
</ResponseField>

<ResponseField name="low" type="number" required>
  The lowest value in the bucket.
</ResponseField>

<ResponseField name="close" type="number" required>
  The latest value in the bucket.
</ResponseField>

<ResponseField name="volume" type="number" required>
  Traded volume in the bucket, in the subscription's denomination.
</ResponseField>

Candle values are JSON numbers, not decimal strings. See [the candle exception](/concepts/reading-responses#the-candle-exception).

To draw history before the stream starts, read candles with the same `timeframe`, `metric` and `denomination` from `GET /v1/tokens/{chain}/{address}/ohlcv`.

## Errors

| Code | When |
| - | - |
| `VALIDATION_ERROR` | `chain` or `token` missing; an address in the wrong format for the chain; an unknown `timeframe`, `metric` or `denomination`; an unknown filter field |
| `UNSUPPORTED_CHAIN` | `chain` is not a supported slug |

<RequestExample>
  ```json Subscribe theme={null}
  {
    "action": "subscribe",
    "channel": "spot.candles",
    "filters": {
      "chain": "solana",
      "token": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
      "timeframe": "1m",
      "metric": "price",
      "denomination": "usd"
    }
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Update theme={null}
  {
    "type": "update",
    "channel": "spot.candles",
    "subscriptionId": "9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
    "data": {
      "time": 1789632000000,
      "open": 0.0000216,
      "high": 0.0000218,
      "low": 0.0000215,
      "close": 0.0000217,
      "volume": 48211.7
    }
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.