# Hyperliquid candle ranges

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` |

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.

`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.

ze. 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.

## Request Parameters

- `market` (`string, required`): Hyperliquid market symbol, for example `"BTC"`, `"@142"`, or `"hyna:ETH"`.
- `interval` (`string, required`): Candle interval, one of `"1s"`, `"1m"`, or `"5m"`.
- `start` (`string, optional`): Inclusive ISO-8601 UTC lower bound aligned to the interval.
- `end` (`string, optional`): Exclusive ISO-8601 UTC upper bound aligned to the interval.
- `limit` (`number, optional`): Page size. Defaults to `2000` and is capped at `5000`.
- `cursor` (`string, optional`): Opaque cursor returned as `nextCursor` by the previous page.

## Request Example

```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"
```

## Response Fields

- `data` (`array, required`): Array of returned sparse candle objects. Billing counts one response per 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. Historical range responses return finalized candles with `x=true`.
- `nextCursor` (`string, optional`): Cursor for the next page. Present only when `hasMore=true`.
- `hasMore` (`boolean, required`): Whether another page is available.

## Successful 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
}
```

## Error Responses

### Invalid range

- Code: `400 / -32602`
- Description: Invalid interval, malformed timestamp, non-aligned timestamp, malformed cursor, or `end` before `start`.

### Current or future bucket

- Code: `400 / -32001`
- Description: The requested `end` includes the current in-progress bucket or a future bucket.

## 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`.

zed 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`](https://www.dwellir.com/docs/hyperliquid/hyperliquid-index/ohlcv-data/candles). For live all-market updates, use [`allCandles`](https://www.dwellir.com/docs/hyperliquid/hyperliquid-index/ohlcv-data/all-candles).