# Hyperliquid allCandles WebSocket API

Use `allCandles` when you want one live stream of candle changes across every active Hyperliquid market for a single interval. The stream is sparse: each data frame contains only markets that emitted a candle update for that batch.

If you need one specific market, use [`candles`](https://www.dwellir.com/docs/hyperliquid/hyperliquid-index/ohlcv-data/candles).

The `allCandles` stream is not a historical replay API. It starts delivering live batches after a successful subscription.

## Billing

`allCandles` WebSocket data frames are billed by the number of candle objects delivered in `data`, not as one response per WebSocket
frame. A frame with `87` candle objects counts as `87` responses.

Sparse markets that do not emit a candle object in a frame do not add to the response count. Subscription acknowledgements and other control messages establish the stream but do not add candle responses.

## Endpoint

```text
wss://api-hyperliquid-index.n.dwellir.com/YOUR_API_KEY
```

If your client expects an explicit WebSocket path, this compatible form also works:

```text
wss://api-hyperliquid-index.n.dwellir.com/YOUR_API_KEY/ws
```

## Subscribe Message

Send a subscribe message with `subscription.type` set to `allCandles`. Unlike the single-market stream, this subscription does not include `market`.

```json
{
  "method": "subscribe",
  "subscription": {
    "type": "allCandles",
    "interval": "1m"
  }
}
```

Supported intervals are `1s`, `1m`, and `5m`.

### Subscription Parameters

| Parameter               | Type   | Required | Description                                                      |
| ----------------------- | ------ | -------- | ---------------------------------------------------------------- |
| `method`                | string | Yes      | Must be `"subscribe"`                                            |
| `subscription.type`     | string | Yes      | Must be `"allCandles"`                                           |
| `subscription.interval` | string | Yes      | Candle interval. Supported values are `"1s"`, `"1m"`, and `"5m"` |

## Request Parameters

- `method` (`string, required`): Must be `"subscribe"`
- `subscription.type` (`string, required`): Must be `"allCandles"`
- `subscription.interval` (`string, required`): Candle interval: `"1s"`, `"1m"`, or `"5m"`

## Request Example

```json
{
  "method": "subscribe",
  "subscription": {
    "type": "allCandles",
    "interval": "1m"
  }
}
```

## Response Fields

- `type` (`string, required`): Always `"allCandles"` for data messages
- `seq` (`number, required`): Per-subscription sequence number
- `cursor` (`string, required`): Candle open time encoded as Unix milliseconds
- `data` (`array, required`): Array of emitted candle objects. Billing counts one response per candle object in this array.
- `data[].s` (`string, required`): Hyperliquid market symbol
- `data[].i` (`string, required`): Candle interval
- `data[].t` (`number, required`): Candle open time in Unix milliseconds
- `data[].T` (`number, required`): Candle close time in Unix milliseconds
- `data[].o` (`string, required`): First trade price in the interval
- `data[].h` (`string, required`): Highest trade price in the interval
- `data[].l` (`string, required`): Lowest trade price in the interval
- `data[].c` (`string, required`): Last trade price in the interval
- `data[].v` (`string, required`): Total traded size in base units
- `data[].q` (`string, required`): Total traded notional in quote units
- `data[].n` (`number, required`): Number of contributing trades
- `data[].x` (`boolean, required`): Candle finalization flag

## Successful Response

```json
{
  "type": "allCandles",
  "seq": 12,
  "cursor": "1775601060000",
  "data": [
    {
      "s": "BTC",
      "i": "1m",
      "t": 1775601060000,
      "T": 1775601119999,
      "o": "71564",
      "h": "71578",
      "l": "71563",
      "c": "71577",
      "v": "0.21291",
      "q": "15238.32632",
      "n": 57,
      "x": false
    },
    {
      "s": "ETH",
      "i": "1m",
      "t": 1775601060000,
      "T": 1775601119999,
      "o": "3864.2",
      "h": "3865.1",
      "l": "3863.9",
      "c": "3864.8",
      "v": "14.893",
      "q": "57555.8064",
      "n": 31,
      "x": false
    }
  ]
}
```

## Example Flow

Client sends:

```json
{
  "method": "subscribe",
  "subscription": {
    "type": "allCandles",
    "interval": "1m"
  }
}
```

Server acknowledges:

```json
{
  "type": "subscribed",
  "interval": "1m",
  "subscriptionType": "allCandles"
}
```

Then sends `allCandles` events. Each event contains a `data` array of candle objects:

```json
{
  "type": "allCandles",
  "seq": 12,
  "cursor": "1775601060000",
  "data": [
    {
      "s": "BTC",
      "i": "1m",
      "t": 1775601060000,
      "T": 1775601119999,
      "o": "71564",
      "h": "71578",
      "l": "71563",
      "c": "71577",
      "v": "0.21291",
      "q": "15238.32632",
      "n": 57,
      "x": false
    },
    {
      "s": "ETH",
      "i": "1m",
      "t": 1775601060000,
      "T": 1775601119999,
      "o": "3864.2",
      "h": "3865.1",
      "l": "3863.9",
      "c": "3864.8",
      "v": "14.893",
      "q": "57555.8064",
      "n": 31,
      "x": false
    }
  ]
}
```

## Response Field Reference

| Field    | Description                                                                                                          |
| -------- | -------------------------------------------------------------------------------------------------------------------- |
| `seq`    | Per-subscription sequence number. Starts at `1` for the first `allCandles` event and increases on every data message |
| `cursor` | Candle open time encoded as a Unix millisecond timestamp string                                                      |
| `data`   | Array of candle objects emitted for the batch                                                                        |
| `data.s` | Hyperliquid market symbol, for example `BTC`, `@142`, or `hyna:ETH`                                                  |
| `data.i` | Candle interval, one of `1s`, `1m`, `5m`                                                                             |
| `data.t` | Candle open time in Unix milliseconds                                                                                |
| `data.T` | Candle close time in Unix milliseconds                                                                               |
| `data.o` | First trade price in the interval                                                                                    |
| `data.h` | Highest trade price in the interval                                                                                  |
| `data.l` | Lowest trade price in the interval                                                                                   |
| `data.c` | Last trade price in the interval                                                                                     |
| `data.v` | Total traded size in base units                                                                                      |
| `data.q` | Total traded notional in quote units                                                                                 |
| `data.n` | Number of contributing trades                                                                                        |
| `data.x` | Candle finalization flag. `false` means the candle is still open and `true` means it is finalized                    |

## Behavior

- subscription is keyed by `interval`
- the stream emits arrays of changed candle snapshots across active markets
- each frame contains only markets with a candle update in that batch
- `seq` is per-subscription ordering and starts at `1` for the first `allCandles` event
- `cursor` is the candle open time encoded as a Unix millisecond timestamp string
- candle payloads use the same `s i t T o h l c v q n x` schema as REST, JSON-RPC, and the single-market WebSocket stream
- `x=false` means the candle is still open, and `x=true` means it is finalized

## Authentication

- include your Dwellir API key in the WebSocket path: `wss://api-hyperliquid-index.n.dwellir.com/YOUR_API_KEY`
- `wss://api-hyperliquid-index.n.dwellir.com/YOUR_API_KEY/ws` is also accepted for clients that expect an explicit WebSocket path
- both forms connect to the same live `allCandles` stream

## When to Use allCandles

- full-market dashboards
- alerting systems that scan every active market
- analytics pipelines that need one interval-wide stream instead of one WebSocket subscription per market