> For the complete documentation index, see [llms.txt](https://docs.hydromancer.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hydromancer.xyz/readme/websocket/allcandles.md).

# allCandles

{% hint style="info" %}
This endpoint requires special permission on your API key. Contact us to enable it.
{% endhint %}

Streams candle updates for **every coin** at a given interval, batched per block. Each message contains an array of candle snapshots — one per coin that had trading activity in that block. This is ideal for building dashboards, heatmaps, or any application that needs cross-market candle data without managing individual per-coin subscriptions.

For single-coin candle streaming, see [`candles`](/readme/websocket/candles.md).

### Subscribe

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

| Field      | Type   | Required | Description                                                                                                                |
| ---------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| `interval` | string | Yes      | Candle interval: `1s`, `15s`, `30s`, `1m`, `3m`, `5m`, `15m`, `30m`, `1h`, `2h`, `4h`, `8h`, `12h`, `1d`, `3d`, `1w`, `1M` |

### Unsubscribe

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

### Update data format

Each message contains an array of candle snapshots batched per block. Only coins with trading activity in the block are included.

```json
{
    "type": "allCandles",
    "seq": 5,
    "cursor": "1700000040000",
    "data": [
        {
            "s": "BTC",
            "i": "1m",
            "t": 1700000040000,
            "T": 1700000099999,
            "o": "45000.00",
            "h": "45100.50",
            "l": "44980.00",
            "c": "45050.25",
            "v": "123.45",
            "q": "5560125.00",
            "n": 312,
            "x": false
        },
        {
            "s": "ETH",
            "i": "1m",
            "t": 1700000040000,
            "T": 1700000099999,
            "o": "2150.00",
            "h": "2155.50",
            "l": "2148.00",
            "c": "2153.25",
            "v": "456.78",
            "q": "982345.00",
            "n": 189,
            "x": false
        }
    ]
}
```

### Field definitions

**Envelope fields:**

| Field    | Type   | Description                                                            |
| -------- | ------ | ---------------------------------------------------------------------- |
| `type`   | string | Always `"allCandles"`                                                  |
| `seq`    | number | Per-subscription sequence number (starts at 1, increments per message) |
| `cursor` | string | Candle open time as millisecond timestamp string (for session replay)  |

**Candle fields (each item in `data`):**

| Field | Type    | Description                                                     |
| ----- | ------- | --------------------------------------------------------------- |
| `s`   | string  | Coin name                                                       |
| `i`   | string  | Interval string                                                 |
| `t`   | number  | Candle open time (milliseconds, interval start)                 |
| `T`   | number  | Candle close time (milliseconds, interval end)                  |
| `o`   | string  | Open price                                                      |
| `h`   | string  | High price                                                      |
| `l`   | string  | Low price                                                       |
| `c`   | string  | Close (latest) price                                            |
| `v`   | string  | Volume in base asset                                            |
| `q`   | string  | Quote volume (notional value)                                   |
| `n`   | number  | Number of trades                                                |
| `x`   | boolean | `true` if the candle is closed/finalized, `false` if still open |

### Chunking

`allCandles` supports live message chunking. When enabled via `liveFormat=chunked-v1` in your connection URL, large batches are split into smaller messages with `chunk`, `totalChunks`, and `batchId` fields. See [Live Message Chunking](/readme/websocket/live-message-chunking.md) for details.

### Session replay

`allCandles` supports session replay. On reconnect with a session, missed candle updates are replayed from the cursor. The cursor represents the candle open timestamp.

### Limits

Only one `allCandles` subscription is allowed per API key. To stream multiple intervals, subscribe once per interval (each counts as a separate subscription).

### Examples

{% tabs %}
{% tab title="JavaScript" %}

```javascript
const WebSocket = require('ws');

const ws = new WebSocket(`wss://api.hydromancer.xyz/ws?token=${process.env.HYDROMANCER_API_KEY}`);

ws.on('message', (data) => {
    const msg = JSON.parse(data);

    if (msg.type === 'connected') {
        ws.send(JSON.stringify({
            method: 'subscribe',
            subscription: {
                type: 'allCandles',
                interval: '1m'
            }
        }));
    } else if (msg.type === 'ping') {
        ws.send(JSON.stringify({ type: 'pong' }));
    } else if (msg.type === 'allCandles') {
        for (const c of msg.data) {
            const status = c.x ? 'CLOSED' : 'open';
            console.log(`[${status}] ${c.s} ${c.i}  O=${c.o} H=${c.h} L=${c.l} C=${c.c} V=${c.v} trades=${c.n}`);
        }
    }
});
```

{% endtab %}

{% tab title="Python" %}

```python
import websocket
import json
import os

def on_message(ws, message):
    msg = json.loads(message)

    if msg['type'] == 'connected':
        ws.send(json.dumps({
            "method": "subscribe",
            "subscription": {
                "type": "allCandles",
                "interval": "1m"
            }
        }))
    elif msg['type'] == 'ping':
        ws.send(json.dumps({'type': 'pong'}))
    elif msg['type'] == 'allCandles':
        for c in msg['data']:
            status = 'CLOSED' if c['x'] else 'open'
            print(f"[{status}] {c['s']} {c['i']}  O={c['o']} H={c['h']} L={c['l']} C={c['c']} V={c['v']} trades={c['n']}")

ws = websocket.WebSocketApp(
    f"wss://api.hydromancer.xyz/ws?token={os.environ.get('HYDROMANCER_API_KEY')}",
    on_message=on_message
)
ws.run_forever()
```

{% endtab %}
{% endtabs %}

### Common errors

| Error                | Cause                                                           |
| -------------------- | --------------------------------------------------------------- |
| `Invalid interval`   | Interval string not in the valid list                           |
| `Permission denied`  | API key does not have the required permission                   |
| `Connection timeout` | Not responding to ping messages — reply with `{"type": "pong"}` |