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 |
Human endpoint reference
OpenGET /v1/hyperliquid/hip4/orderbook/{symbol}/l4/history for authentication, parameters, responses, and examples.
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"
},
"has_more": {
"description": "Present on cursor-paged routes: true when another page exists. `next_cursor` is present exactly when it is true.",
"type": "boolean"
},
"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"
},
"symbol": {
"description": "Present on per-symbol routes: the symbol the response covers.",
"type": "string"
},
"venue": {
"description": "Present on per-symbol routes: the venue the response covers, for example `hyperliquid` or `hip3`.",
"type": "string"
}
}
},
"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"
},
"param": {
"description": "The parameter at fault, when the error is about one parameter.",
"type": "string"
},
"request_id": {
"description": "Unique request ID for support",
"type": "string",
"format": "uuid"
},
"success": {
"description": "Always false on an error.",
"type": "boolean",
"example": false
}
}
}
OpenAPI example
{
"code": 400,
"error": "Failed to deserialize query string: limit: invalid digit found in string",
"error_code": "invalid_query_params",
"param": "limit",
"request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05",
"success": false
}
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"
},
"param": {
"description": "The parameter at fault, when the error is about one parameter.",
"type": "string"
},
"request_id": {
"description": "Unique request ID for support",
"type": "string",
"format": "uuid"
},
"success": {
"description": "Always false on an error.",
"type": "boolean",
"example": false
}
}
}
OpenAPI example
{
"code": 401,
"error": "Missing authentication credentials. Provide X-API-Key header or Bearer token.",
"error_code": "unauthorized",
"request_id": "71ed4b6f-63ef-4ae1-a123-07ffa47c1c14",
"success": false
}
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"
},
"param": {
"description": "The parameter at fault, when the error is about one parameter.",
"type": "string"
},
"request_id": {
"description": "Unique request ID for support",
"type": "string",
"format": "uuid"
},
"success": {
"description": "Always false on an error.",
"type": "boolean",
"example": false
}
}
}
OpenAPI example
{
"code": 429,
"error": "Rate limit exceeded"
}