limit parameter defaults to 100 and is capped at 1000. Within each price level, bids and asks are ordered by true queue priority (ALO priority insertions included), not by placement time. Depth truncation is by order count, so the orders at a depth cut can differ from responses served before 2026-07-21.
Route Metadata
| Field | Value |
|---|---|
| Method | GET |
| Path | /v1/hyperliquid/hip4/orderbook/{symbol}/l4/history |
| operationId | getHip4L4History |
| Tag | HIP-4 Outcomes - Order Book |
| Family | HIP-4 |
| Deprecated or legacy | no |
Request Parameters
Path Parameters
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "getHip4L4History path parameters",
"type": "object",
"required": [
"symbol"
],
"properties": {
"symbol": {
"description": "HIP-4 coin id (e.g., `0` for outcome 0 Yes side, `1` for No side). The `#`-prefixed form (`#0`, `#1`) is also accepted.",
"type": "string",
"example": "0",
"x-parameter-location": "path"
}
}
}
Query Parameters
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "getHip4L4History query parameters",
"type": "object",
"properties": {
"start": {
"description": "Start of the requested window as a Unix timestamp in milliseconds. ISO 8601 strings are rejected.",
"type": "integer",
"format": "int64",
"example": 1777680000000,
"x-parameter-location": "query"
},
"end": {
"description": "End of the requested window as a Unix timestamp in milliseconds. ISO 8601 strings are rejected.",
"type": "integer",
"format": "int64",
"example": 1777766400000,
"x-parameter-location": "query"
},
"cursor": {
"description": "Timestamp cursor in Unix milliseconds from the previous response metadata.",
"type": "integer",
"format": "int64",
"x-parameter-location": "query"
},
"limit": {
"description": "Maximum number of results (default: 100, max: 1000)",
"type": "integer",
"format": "int64",
"default": 100,
"maximum": 1000,
"x-parameter-location": "query"
}
}
}
Response Contracts
Status 200
Typed L4 orderbook checkpoint arrayapplication/json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "getHip4L4History response 200",
"type": "object",
"required": [
"data",
"meta",
"success"
],
"properties": {
"data": {
"type": "array",
"items": {
"description": "Current or reconstructed Hyperliquid-family L4 orderbook snapshot.",
"type": "object",
"required": [
"ask_count",
"asks",
"bid_count",
"bids",
"checkpoint_timestamp",
"coin",
"diffs_applied",
"last_block_number",
"timestamp",
"total_ask_size",
"total_bid_size"
],
"properties": {
"ask_count": {
"description": "Number of ask orders in the full stored/reconstructed checkpoint before optional depth truncates returned bids/asks.",
"type": "integer",
"example": 15
},
"asks": {
"description": "Ask-side resting orders, best price first.",
"type": "array",
"items": {
"description": "Individual resting order in a Hyperliquid-family L4 snapshot.",
"type": "object",
"required": [
"oid",
"price",
"side",
"size",
"timestamp",
"user_address"
],
"properties": {
"oid": {
"description": "Hyperliquid order identifier.",
"type": "integer",
"format": "int64",
"example": 18499128731
},
"price": {
"description": "Venue-native resting order price.",
"type": "number",
"example": 105384.5
},
"side": {
"description": "Book side: B for bid or A for ask.",
"type": "string",
"enum": [
"B",
"A"
],
"example": "B"
},
"size": {
"description": "Venue-native remaining order size.",
"type": "number",
"example": 0.824
},
"timestamp": {
"description": "Queue-join timestamp in Unix epoch milliseconds; 0 when unknown.",
"type": "integer",
"format": "int64",
"example": 1773273600123
},
"user_address": {
"description": "Address attributed to the resting order.",
"type": "string",
"example": "0x0000000000000000000000000000000000000000"
}
}
}
},
"bid_count": {
"description": "Number of bid orders in the full stored/reconstructed checkpoint before optional depth truncates returned bids/asks.",
"type": "integer",
"example": 12
},
"bids": {
"description": "Bid-side resting orders, best price first.",
"type": "array",
"items": {
"description": "Individual resting order in a Hyperliquid-family L4 snapshot.",
"type": "object",
"required": [
"oid",
"price",
"side",
"size",
"timestamp",
"user_address"
],
"properties": {
"oid": {
"description": "Hyperliquid order identifier.",
"type": "integer",
"format": "int64",
"example": 18499128731
},
"price": {
"description": "Venue-native resting order price.",
"type": "number",
"example": 105384.5
},
"side": {
"description": "Book side: B for bid or A for ask.",
"type": "string",
"enum": [
"B",
"A"
],
"example": "B"
},
"size": {
"description": "Venue-native remaining order size.",
"type": "number",
"example": 0.824
},
"timestamp": {
"description": "Queue-join timestamp in Unix epoch milliseconds; 0 when unknown.",
"type": "integer",
"format": "int64",
"example": 1773273600123
},
"user_address": {
"description": "Address attributed to the resting order.",
"type": "string",
"example": "0x0000000000000000000000000000000000000000"
}
}
}
},
"checkpoint_timestamp": {
"description": "Timestamp of the checkpoint used for this snapshot.",
"type": "string",
"format": "date-time",
"example": "2026-03-12T00:00:00.000Z"
},
"coin": {
"description": "Trading pair or market symbol.",
"type": "string",
"example": "BTC"
},
"diffs_applied": {
"description": "Number of L4 diffs applied after the checkpoint.",
"type": "integer",
"example": 0
},
"is_crossed": {
"description": "True only when a reconstructed historical book has best bid greater than or equal to best ask; omitted for clean snapshots.",
"type": "boolean",
"example": true
},
"last_block_number": {
"description": "Last Hyperliquid block represented by this snapshot.",
"type": "integer",
"format": "int64",
"example": 1023882395
},
"timestamp": {
"description": "Snapshot timestamp in UTC.",
"type": "string",
"format": "date-time",
"example": "2026-03-12T00:00:00.000Z"
},
"total_ask_size": {
"description": "Aggregate venue-native ask size in the full stored/reconstructed checkpoint before optional depth truncates returned bids/asks.",
"type": "number",
"example": 98.76
},
"total_bid_size": {
"description": "Aggregate venue-native bid size in the full stored/reconstructed checkpoint before optional depth truncates returned bids/asks.",
"type": "number",
"example": 102.34
}
}
}
},
"meta": {
"description": "Response metadata",
"type": "object",
"properties": {
"count": {
"description": "Number of records returned",
"type": "integer"
},
"coverage_from": {
"description": "Earliest coverage for the requested symbol and data type. Present only when the requested window ends before coverage begins.",
"type": "string",
"format": "date-time"
},
"next_cursor": {
"description": "Cursor for pagination (timestamp). Use this value as the `cursor` parameter to fetch the next page of results.",
"type": "string",
"nullable": true
},
"notice": {
"description": "Human-readable advisory about the response. Used when the requested window ends before coverage begins for the symbol, and on CVD responses that are one page of several; may carry other advisories in future.",
"type": "string"
},
"request_id": {
"description": "Unique request ID for support",
"type": "string",
"format": "uuid"
}
}
},
"success": {
"type": "boolean",
"example": true
}
}
}
Status 400
Invalid requestapplication/json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "getHip4L4History response 400",
"description": "Error response",
"type": "object",
"properties": {
"code": {
"description": "HTTP status code",
"type": "integer"
},
"error": {
"description": "Error message",
"type": "string"
},
"error_code": {
"description": "Machine-readable error code. Common values: `invalid_query_params` (a query parameter failed to parse or validate) and `invalid_path_params` (a path parameter failed to parse). Other endpoint-specific codes exist; treat unknown codes as generic errors of the given HTTP status.",
"type": "string"
},
"request_id": {
"description": "Unique request ID for support",
"type": "string",
"format": "uuid"
}
}
}
OpenAPI example
{
"code": 400,
"error": "Failed to deserialize query string: limit: invalid digit found in string",
"error_code": "invalid_query_params",
"request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05"
}
Status 401
Authentication requiredapplication/json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "getHip4L4History response 401",
"description": "Error response",
"type": "object",
"properties": {
"code": {
"description": "HTTP status code",
"type": "integer"
},
"error": {
"description": "Error message",
"type": "string"
},
"error_code": {
"description": "Machine-readable error code. Common values: `invalid_query_params` (a query parameter failed to parse or validate) and `invalid_path_params` (a path parameter failed to parse). Other endpoint-specific codes exist; treat unknown codes as generic errors of the given HTTP status.",
"type": "string"
},
"request_id": {
"description": "Unique request ID for support",
"type": "string",
"format": "uuid"
}
}
}
OpenAPI example
{
"code": 401,
"error": "Missing or invalid API key. Provide X-API-Key header."
}
Status 429
Rate limit exceededapplication/json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "getHip4L4History response 429",
"description": "Error response",
"type": "object",
"properties": {
"code": {
"description": "HTTP status code",
"type": "integer"
},
"error": {
"description": "Error message",
"type": "string"
},
"error_code": {
"description": "Machine-readable error code. Common values: `invalid_query_params` (a query parameter failed to parse or validate) and `invalid_path_params` (a path parameter failed to parse). Other endpoint-specific codes exist; treat unknown codes as generic errors of the given HTTP status.",
"type": "string"
},
"request_id": {
"description": "Unique request ID for support",
"type": "string",
"format": "uuid"
}
}
}
OpenAPI example
{
"code": 429,
"error": "Rate limit exceeded"
}