> For the complete documentation index, see [llms.txt](https://docs.hello.trade/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hello.trade/developer-tools/websocket-api/market-data/candles.md).

# Candles

OHLCV (Open, High, Low, Close, Volume) candlestick data.

**Channel:** `candles`

## Overview

The candles channel provides real-time OHLCV candlestick data for subscribed instruments with configurable intervals.

## Connection

Connect to the WebSocket endpoint:

```
wss://marketdata.app.hello.trade/ws
```

## Subscription Request

```json
{
  "type": "subscribe",
  "channel": "candles",
  "symbols": ["BTC", "ETH"],
  "timespan": "MINUTE",
  "multiplier": 1
}
```

| Field        | Type      | Required | Description                                                                                                                                         |
| ------------ | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`       | string    | Yes      | Must be `"subscribe"`                                                                                                                               |
| `channel`    | string    | Yes      | Must be `"candles"`                                                                                                                                 |
| `symbols`    | string\[] | Yes      | List of instrument symbols                                                                                                                          |
| `timespan`   | string    | No       | Candle timespan: `"MINUTE"`, `"HOUR"`, or `"DAY"` (default: `"MINUTE"`)                                                                             |
| `multiplier` | Number    | No       | Candle multiplier: `1`, `4`, `5`, or `15` (default: `1`)                                                                                            |
| `from`       | Number    | No       | Start timestamp (Unix seconds) for historical data                                                                                                  |
| `to`         | Number    | No       | End timestamp (Unix seconds) for historical data                                                                                                    |
| `combined`   | boolean   | No       | Batch the historic backfill into a single array message instead of one message per candle (default: `false`). Only takes effect when `from` is set. |

## Unsubscription Request

```json
{
  "type": "unsubscribe",
  "channel": "candles",
  "symbols": ["BTC"]
}
```

## Response

```json
{
  "type": "marketData",
  "channel": "candles",
  "data": {
    "symbol": "BTC",
    "open": "45000.00",
    "high": "45100.00",
    "low": "44950.00",
    "close": "45050.00",
    "volume": "125.50",
    "vwa": "45025.00",
    "timeStamp": 1705596400
  }
}
```

| Field       | Type   | Description                                   |
| ----------- | ------ | --------------------------------------------- |
| `symbol`    | string | Instrument symbol                             |
| `open`      | string | Opening price of the interval                 |
| `high`      | string | Highest price during the interval             |
| `low`       | string | Lowest price during the interval              |
| `close`     | string | Closing price of the interval                 |
| `volume`    | string | Total volume during the interval              |
| `vwa`       | string | Volume weighted average price                 |
| `timeStamp` | Number | Unix timestamp (seconds) of candle start time |

## Combined (batched) historical response

By default, each historic candle in a `from`/`to` backfill is sent as its own `marketData` message, same as live updates. Setting `combined: true` on the subscription request instead batches the entire historic backfill into a single message. This is a one-shot response — no live updates follow on this subscription; subscribe again with a plain `candles` request (no `from`/`to`) for live ticks.

```json
{
  "type": "subscribe",
  "channel": "candles",
  "symbols": ["BTC"],
  "timespan": "MINUTE",
  "from": 1705500000,
  "to": 1705596400,
  "combined": true
}
```

```json
{
  "type": "marketData",
  "channel": "candles",
  "data": {
    "symbol": "BTC",
    "candles": [
      { "symbol": "BTC", "open": "45000.00", "high": "45100.00", "low": "44950.00", "close": "45050.00", "volume": "125.50", "vwa": "45025.00", "timeStamp": 1705500000 },
      { "symbol": "BTC", "open": "45050.00", "high": "45150.00", "low": "45000.00", "close": "45100.00", "volume": "98.20", "vwa": "45075.00", "timeStamp": 1705500060 }
    ]
  }
}
```

## Error Response

```json
{
  "type": "error",
  "message": "Invalid subscription request",
  "code": 400
}
```

## Notes

* **Timespans**: `MINUTE`, `HOUR`, or `DAY`
* **Multipliers**: `1`, `4`, `5`, or `15` (e.g., 1-minute, 4-minute, 5-minute, 15-minute candles)
* **Real-time subscription**: Omit `from` and `to` to receive streaming updates for new candles
* **Historical data**: Set both `from` and `to` timestamps to retrieve historical candles
* Updates are sent as new candles form or when the current candle updates
* Candle timestamps represent the start of the interval