Hyperliquid candles

Use candles when you need OHLCV data for one Hyperliquid market and one interval. The same candle schema is available over REST, JSON-RPC, and WebSocket:

Parameters

REST

Use REST when you want a simple HTTP lookup for one completed candle.

GET https://api-hyperliquid-index.n.dwellir.com/YOUR_API_KEY/v1/candles

curl "https://api-hyperliquid-index.n.dwellir.com/YOUR_API_KEY/v1/candles?market=BTC&interval=1m&time=2026-03-30T23:00:00Z"

REST returns the candle object directly. Missing sparse buckets return 404.

JSON-RPC

Use JSON-RPC when your client already expects RPC envelopes or method-based request logging.

POST https://api-hyperliquid-index.n.dwellir.com/YOUR_API_KEY/jsonrpc

Method:

ohlcv_getCandle

curl "https://api-hyperliquid-index.n.dwellir.com/YOUR_API_KEY/jsonrpc" \
  -H "content-type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "ohlcv_getCandle",
    "params": {
      "market": "BTC",
      "interval": "1m",
      "time": "2026-03-30T23:00:00Z"
    }
  }'

JSON-RPC returns the candle object under result. Missing sparse buckets return an error with code: -32004.

WebSocket

Use WebSocket when you want live candle updates pushed to your client for one market and interval.

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

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

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

Send a subscribe message:

{ "type": "subscribe", "market": "BTC", "interval": "1m" }

The stream includes both unfinalized updates and the final closed candle state. Repeated messages with the same cursor are successive states of the same candle.

If you need one interval-wide stream for all active markets, use allCandles.

Candle Field Reference

Discovering Markets

Use Dwellir's Info Endpoint to find valid market values before querying candles.

Native perp symbols

Call meta. Each entry's name in the universe array is the symbol you need.

curl -X POST 'https://api-hyperliquid-mainnet-info.n.dwellir.com/YOUR_API_KEY/info' \
  -H 'Content-Type: application/json' \
  -d '{"type":"meta"}'

Look for entries like { "name": "BTC", "szDecimals": 5, "maxLeverage": 40 } and use market=BTC.

Spot symbols

Call spotMeta. Each pair in the universe array has an index field. Prefix it with @ to get the market symbol.

curl -X POST 'https://api-hyperliquid-mainnet-info.n.dwellir.com/YOUR_API_KEY/info' \
  -H 'Content-Type: application/json' \
  -d '{"type":"spotMeta"}'

To find a specific token's spot pair, cross-reference the tokens and universe arrays:

import requests

data = requests.post(
    "https://api-hyperliquid-mainnet-info.n.dwellir.com/YOUR_API_KEY/info",
    json={"type": "spotMeta"},
).json()

tokens = {t["index"]: t for t in data["tokens"]}

for pair in data["universe"]:
    t0, t1 = pair["tokens"]
    if "BTC" in tokens[t0]["name"].upper():
        symbol = pair["name"] if pair.get("isCanonical") else f"@{pair['index']}"
        print(f"Use market={symbol}")  # market=@142

HIP-3 perpDex symbols

Call perpDexs. Each DEX has an assetToStreamingOiCap array of [symbol, oiCap] pairs. The symbol is what you pass as market.

curl -X POST 'https://api-hyperliquid-mainnet-info.n.dwellir.com/YOUR_API_KEY/info' \
  -H 'Content-Type: application/json' \
  -d '{"type":"perpDexs"}'

Some HIP-3 DEXs currently available:

Behavior

• REST and JSON-RPC return one completed candle per request.
• time is the open time of the candle bucket, not an arbitrary point inside a range.
• WebSocket streams live candle state after subscribe.
• Candle payloads use the same s i t T o h l c v q n x schema across all three transports.
• Candles are sparse. Empty intervals are omitted instead of forward-filled.

Fetching Multiple Historical Candles

Use the time parameter as the iterator. For 1m, advance by one minute per request. For 5m, advance by five minutes. For 1s, advance by one second.

For high-throughput backfills, see the archive backfill guide. It covers HTTP/2, worker pools, sticky-session discovery, rate limiting, sparse bucket handling, and atomic resume state.

When to Use Each Transport