candles

Stream real-time OHLCV candle updates for a specific coin and interval.

Currently we offer 1s candlesticks which are not available on Hyperliquid natively. Our candlesticks endpoint also return more than 5k last candles available through the native Hyperliquid API.

Streams real-time candle updates as trades happen. Each message contains the latest state of the current candle for the subscribed coin and interval. When a candle closes and a new one opens, both events are sent.

Subscribe

{
    "method": "subscribe",
    "subscription": {
        "type": "candle",
        "coin": "BTC",
        "interval": "1m"
    }
}

Field	Type	Required	Description
coin	string	Yes	Coin name (e.g. "BTC", "ETH", "hyna:ETH")
interval	string	Yes	Candle interval: 1s*, 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 8h, 12h, 1d, 3d, 1w, 1M

*1s requires Growth tier or above.

Unsubscribe

{
    "method": "unsubscribe",
    "subscription": {
        "type": "candle",
        "coin": "BTC",
        "interval": "1m"
    }
}

Update data format

Each message contains a full candle snapshot. The x field indicates whether the candle is finalized (true) or still accumulating trades (false).

{
    "type": "candle",
    "seq": 42,
    "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
    }
}

Field definitions

Envelope fields:

Field	Type	Description
type	string	Always "candle"
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 (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

Examples

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: 'candle',
                coin: 'BTC',
                interval: '1m'
            }
        }));
    } else if (msg.type === 'ping') {
        ws.send(JSON.stringify({ type: 'pong' }));
    } else if (msg.type === 'candle') {
        const c = 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}`);
    }
});

Python

Common errors

Error	Cause
Invalid interval	Interval string not in the valid list
Invalid coin	Coin contains invalid characters or exceeds max length
Connection timeout	Not responding to ping messages — reply with {"type": "pong"}