Hyperliquid Historical Orde | Hyperliquid API Docs

Query historical Hyperliquid order book state from the Dwellir Hyperliquid Index over REST and JSON-RPC single-block and range retrieval surfaces.

Historical orderbooks expose reconstructed Hyperliquid book state at historical blocks. Use this surface when you need point-in-time best bid/offer, aggregated price levels, or individual resting orders for analytics and backtesting.

The request shape mirrors Dwellir's live Order Book WebSocket subscriptions:

type: "l2Book" returns aggregated price levels.
type: "l2Book" with nLevels: 1 is the BBO view.
type: "l4Book" returns the individual resting orders that traditional market data systems usually call L3/order-level book data.

Endpoints

REST:

Text

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

JSON-RPC:

Text

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

Available Markets

Use the published UTC date ranges in this table for production backfills. If a market or date range is not listed, do not assume historical orderbook coverage is available for that span.

Market	Book types	Available UTC date ranges
`BTC`	`l2Book`, BBO (`nLevels: 1`), `l4Book`	Published ranges are maintained here as coverage is enabled.

Method

Method	REST path	JSON-RPC method	Use case
`orderbook_getBook`	`/v1/orderbook`	`orderbook_getBook`	Historical `l2Book` or `l4Book` state at one block
`orderbook_getBookRange`	`/v1/orderbook/range`	`orderbook_getBookRange`	Paginated historical `l2Book` or `l4Book` state for a block range

L2 and BBO responses are derived from the same reconstructed order-level state at request time. They do not use precomputed L2 or BBO aggregate tables.

Shared Parameters

Field	Type	Required	Description
`type`	string	yes	`l2Book` or `l4Book`.
`coin`	string	yes	Hyperliquid market symbol, for example `BTC`, `xyz:MSTR`, `@150`, or `#31`.
`blockNumber`	number	yes	Hyperliquid block number to reconstruct.
`nSigFigs`	number	no	L2 price aggregation significant figures, matching the live order book stream.
`nLevels`	number	no	L2 levels per side. Use `1` for BBO. Applies only to `l2Book`.

l4Book returns the full reconstructed order-level book and does not accept nLevels, nSigFigs, mantissa, or limit.

Bulk Range Requests

Bulk range requests use the same book parameters as single-block lookup, plus block range and pagination fields:

Field	Type	Required	Description
`startBlock`	number	yes	Inclusive first Hyperliquid block to consider.
`endBlock`	number	yes	Inclusive final Hyperliquid block to consider.
`pageSize`	number	no	Page size for returned book objects. Defaults to `20`, max `100`.
`cursor`	string	no	Cursor returned by the previous page.

Example JSON-RPC range request:

JSON

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "orderbook_getBookRange",
  "params": {
    "type": "l2Book",
    "coin": "BTC",
    "startBlock": 985450000,
    "endBlock": 985480000,
    "nSigFigs": 5,
    "nLevels": 20,
    "pageSize": 100
  }
}

The response uses a paginated envelope with data, nextCursor, and hasMore, matching the candle range pattern. Each object in data is the same book object returned by orderbook_getBook. The first page includes the reconstructed book at startBlock, then subsequent reconstructed books at changed blocks through endBlock. Follow-up pages pass cursor=nextCursor and return changed blocks strictly after that cursor.

Billing

Historical orderbook retrieval uses backend-signaled response billing:

single-block orderbook_getBook responses bill as 1 returned book
range pages bill by len(data), not as one flat request
empty successful range pages bill as 0 responses/API credits
error responses are not charged

For example, if a block range returns 18,000 reconstructed BBO snapshots across paginated REST/JSON-RPC calls, it counts as 18,000 responses/API credits. Use nLevels, pageSize, and bounded block ranges to control payload size during backfills.

Hyperliquid Historical Orderbooks