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

{
  "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

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

Response

{
  "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.

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

{
  "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

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

Unknown symbols are rejected with a 400 that names them. See Unknown symbols.

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