Hyperliquid candle ranges

Retrieve paginated historical Hyperliquid OHLCV candle ranges for one market over REST or JSON-RPC, billed by returned candle rows.

Use candle ranges when you need many historical candles for one Hyperliquid market without iterating the single-candle endpoint one bucket at a time.

Transport	Best for	Endpoint
REST	Simple paginated historical pulls	`GET /v1/candles/range`
JSON-RPC	Method-based clients and RPC logging	`POST /jsonrpc` with `ohlcv_getCandlesRange`

Billed by returned candles

Successful non-empty range pages are billed by the number of candle objects in data, not as one flat request. Empty successful sparse ranges are not billed.

Exclusive end timestamp

start is inclusive and end is exclusive. Use start=2025-10-01T00:00:00Z&end=2025-11-01T00:00:00Z for a clean October 2025 range.

Parameters

Field	Required	Description
`market`	yes	Hyperliquid market symbol. See market types for perp, spot, and HIP-3 formats.
`interval`	yes	Candle interval, one of `1s`, `1m`, `5m`.
`start`	no	Inclusive ISO-8601 UTC lower bound. Omit to start from the first available sparse candle for the market.
`end`	no	Exclusive ISO-8601 UTC upper bound. Omit to read through the last completed bucket.
`limit`	no	Page size. Defaults to `2000` and is capped at `5000`.
`cursor`	no	Opaque cursor returned as `nextCursor` from the previous page.

start, end, and cursor must align to the requested interval. Requests that include the current in-progress bucket or a future bucket fail rather than returning provisional candles.

REST

Text

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

Fetch BTC 1s candles for October 2025:

Bash

curl "https://api-hyperliquid-index.n.dwellir.com/YOUR_API_KEY/v1/candles/range?market=BTC&interval=1s&start=2025-10-01T00:00:00Z&end=2025-11-01T00:00:00Z&limit=5000"

REST returns a paginated envelope. Continue while hasMore is true by sending the returned nextCursor:

Bash

curl "https://api-hyperliquid-index.n.dwellir.com/YOUR_API_KEY/v1/candles/range?market=BTC&interval=1s&end=2025-11-01T00:00:00Z&limit=5000&cursor=1759276801000"

JSON-RPC

Text

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

Method:

Text

ohlcv_getCandlesRange

Bash

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_getCandlesRange",
    "params": {
      "market": "BTC",
      "interval": "1m",
      "start": "2025-10-01T00:00:00Z",
      "end": "2025-11-01T00:00:00Z",
      "limit": 5000
    }
  }'

JSON-RPC returns the same range page under result.

Response

JSON

{
  "data": [
    {
      "s": "BTC",
      "i": "1s",
      "t": 1759276800000,
      "T": 1759276800999,
      "o": "117845",
      "h": "117862",
      "l": "117840",
      "c": "117851",
      "v": "3.48221",
      "q": "410385.79284",
      "n": 42,
      "x": true
    }
  ],
  "nextCursor": "1759276801000",
  "hasMore": true
}

Field	Description
`data`	Array of sparse finalized candle objects.
`nextCursor`	Cursor for the next page. Present only when `hasMore=true`.
`hasMore`	`true` when another page is available.

Sparse Range Behavior

Candles are sparse. The API returns only stored candles with trading activity and does not synthesize zero-volume carry-forward intervals.

An empty sparse range returns:

JSON

{
  "data": [],
  "hasMore": false
}

Empty successful ranges do not include X-Iris-Billing-Weight.

Billing

Range pages use backend-signaled row billing:

X-Iris-Billing-Weight: <len(data)> on successful non-empty REST and JSON-RPC pages
no billing header on empty successful pages
no billing header on error responses
sparse gaps do not count toward billing

For example, if a requested 1s month contains 1,800,000 stored candles, only those returned candle objects are billed across the pages you actually fetch.

When to Use Candle Ranges

backfilling one market into a charting store
retrieving full-month or full-day candle windows
resuming long historical jobs with cursor pagination
pulling all available sparse candles for a market and interval

For one known candle timestamp, use candles. For live all-market updates, use allCandles.

Parameters

REST

JSON-RPC

Response

Sparse Range Behavior

Billing

When to Use Candle Ranges

On this page