Subscribing

How to subscribe and unsubscribe to real-time data streams, including message formats, field reference, and error codes.

After establishing a WebSocket connection, you can subscribe to real-time data streams by sending JSON messages.

To subscribe to a data stream, send a message with the following format:

{
  "type": "subscribe",
  "channel": "candles",
  "exchange": "binancef",
  "symbol": "btc/usd",
  "tf": "1m"
}

You can optionally include an id field for request correlation:

{
  "type": "subscribe",
  "id": "my-request-123",
  "channel": "candles",
  "exchange": "binancef",
  "symbol": "btc/usd",
  "tf": "1m"
}

Unsubscribe Message

To stop receiving data from a stream, send an unsubscribe message:

{
  "type": "unsubscribe",
  "channel": "candles",
  "exchange": "binancef",
  "symbol": "btc/usd",
  "tf": "1m"
}

Message Fields

Field	Type	Required	Description
`type`	string	Yes	`"subscribe"` or `"unsubscribe"`
`id`	string	No	Optional client-provided correlation ID (echoed in response)
`channel`	string	Yes	The data channel name (see Channels)
`exchange`	string	Yes	Exchange identifier (e.g., `binancef`, `bybitf`). Aggregated format: colon-separated, unique, alphabetically ordered IDs (e.g., `binancef:bybitf`). Invalid aggregate strings return `INVALID_EXCHANGE`.
`symbol`	string	Yes	Unified trading pair with slash separator (e.g., `btc/usd`)
`tf`	string	Conditional	Timeframe (required for `candles`, `stats`, `oi`, `vd`, `volumes`, `heatmap_sd`, `heatmap_hd`, `flat_heatmap_sd`, `flat_heatmap_hd`, `stop_heatmap`, `tp_heatmap`, `liquidation_heatmap`)
`bucket`	integer	Conditional	Bucket group 1-11 (required for `vd` channel only)

Symbol Field

Use Unified Symbols

Use our unified symbols from the /markets endpoint, not exchange-native tickers like BTCUSDT. See Symbols for details.

The symbol must be in slash format (e.g., btc/usd, not btc-usdt or BTCUSDT):

Correct: "symbol": "btc/usd"

Wrong: "symbol": "BTCUSDT" or "symbol": "btc-usdt"

Exchange Field

For channels that support aggregation, you can subscribe using multiple exchanges in one stream.

Example: "exchange": "binancef:bybitf"

Aggregated exchange strings must be unique and alphabetically ordered. If not, the server responds with INVALID_EXCHANGE and a message such as:

invalid aggregated exchange string: exchanges must be ordered alphabetically
invalid aggregated exchange string: duplicate exchanges are not allowed

If your tier does not allow multi-exchange realtime aggregation, the server returns AGG_NOT_ALLOWED (for example, on Basic plans).

stop_heatmap, tp_heatmap, and liquidation_heatmap are single-exchange only and available only for hyperliquid and hyperliquid-xyz. If you provide aggregated exchanges for these channels, the server returns INVALID_PARAMS.

Timeframe Field

The tf field is required for channels that aggregate data over time intervals:

Required for: candles, stats, oi, vd, volumes, heatmap_sd, heatmap_hd, flat_heatmap_sd, flat_heatmap_hd, stop_heatmap, tp_heatmap, liquidation_heatmap
Not used for: trades, depth, liquidations, markets

Valid formats include values like: 1s, 5s, 15s, 30s, 1m, 5m, 15m, 30m, 1h, 4h, 12h, 1d, 1W, 1M.

Limits:

Minimum: 1s
Maximum: 1M (1 month)

Bucket Field

The bucket field is only used with the vd (volume delta) channel:

Valid values: 1 through 11
Each bucket represents a different price range grouping
Tier restrictions may limit available buckets (Basic: bucket 1 only, Pro: buckets 1-11)

Subscription Limits

Each connection has a maximum number of concurrent subscriptions based on your tier:

Tier	Max Subscriptions per Connection
basic	20
pro	100

Success Behavior

When a subscription succeeds, the server sends a subscribed acknowledgment message:

{
  "type": "subscribed",
  "id": "my-request-123",
  "channel": "candles",
  "exchange": "binancef",
  "symbol": "btc/usd",
  "tf": "1m"
}

Field	Type	Description
`type`	string	Always `"subscribed"`
`id`	string	Your correlation ID (if provided in request)
`channel`	string	The subscribed channel
`exchange`	string	Exchange ID
`symbol`	string	Trading pair
`tf`	string	Timeframe (if applicable)
`bucket`	int	Bucket group (if applicable, for `vd` channel)

Similarly, when you unsubscribe, you receive an unsubscribed acknowledgment:

{
  "type": "unsubscribed",
  "id": "my-request-456",
  "channel": "candles",
  "exchange": "binancef",
  "symbol": "btc/usd",
  "tf": "1m"
}

After the subscribed acknowledgment, you will begin receiving data messages for the stream.

Error Responses

If a subscription fails, you will receive an error message:

{
  "type": "error",
  "code": "ERROR_CODE",
  "message": "Human-readable error description"
}

Error Codes

Code	Description
`INVALID_JSON`	Failed to parse message as JSON
`UNKNOWN_TYPE`	Unknown message type (not `subscribe`, `unsubscribe`, `ping`, or `list_subscriptions`)
`INVALID_PARAMS`	Missing required fields (channel, exchange, symbol)
`INVALID_STREAM`	Unknown or invalid channel name
`INVALID_EXCHANGE`	Unknown/unsupported exchange, duplicate exchange in aggregate string, or non-alphabetical aggregate ordering
`INVALID_SYMBOL`	Symbol not found on the specified exchange
`INVALID_TIMEFRAME`	Invalid timeframe format, outside allowed range, or missing when required
`INVALID_BUCKET`	Invalid or restricted bucket group
`AGG_NOT_ALLOWED`	Multi-exchange aggregation not allowed on your tier (Basic plans)
`MAX_SUBS_EXCEEDED`	Connection has reached the subscription limit
`ALREADY_SUBSCRIBED`	Already subscribed to this exact stream
`NOT_SUBSCRIBED`	Attempting to unsubscribe from a stream you are not subscribed to

Examples

{
  "type": "subscribe",
  "channel": "candles",
  "exchange": "binancef",
  "symbol": "btc/usd",
  "tf": "1m"
}

Trades do not require a timeframe:

{
  "type": "subscribe",
  "channel": "trades",
  "exchange": "coinbase",
  "symbol": "btc/usd"
}

Volume delta requires both timeframe and bucket:

{
  "type": "subscribe",
  "channel": "vd",
  "exchange": "bybitf",
  "symbol": "eth/usd",
  "tf": "1m",
  "bucket": 5
}

{
  "type": "subscribe",
  "channel": "oi",
  "exchange": "binancef",
  "symbol": "btc/usd",
  "tf": "1m"
}

Unsubscribe Example

{
  "type": "unsubscribe",
  "channel": "candles",
  "exchange": "binancef",
  "symbol": "btc/usd",
  "tf": "1m"
}

Subscribing

On this page