Get Hyperliquid Spot order book history JSON Schema

Source OpenAPI: 0xArchive API 1.8.0; 227 paths; 217 component schemas. Get historical Hyperliquid Spot L2 order book snapshots for a pair. The route is scoped to Spot pair symbols such as HYPE-USDC; do not use core perp symbols or HIP identifiers. Explicit endpoint cost is 5 credits per request.

Route Metadata

Field	Value
Method	`GET`
Path	`/v1/hyperliquid/spot/orderbook/{symbol}/history`
operationId	`getHyperliquidSpotOrderbookHistory`
Tag	Hyperliquid Spot - Order Book
Family	Hyperliquid Spot
Deprecated or legacy	no

Human endpoint reference

Open GET /v1/hyperliquid/spot/orderbook/{symbol}/history for authentication, parameters, responses, and examples.

Request Parameters

Path Parameters

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "getHyperliquidSpotOrderbookHistory path parameters",
  "type": "object",
  "required": [
    "symbol"
  ],
  "properties": {
    "symbol": {
      "description": "Hyperliquid Spot pair symbol, for example HYPE-USDC.",
      "type": "string",
      "example": "HYPE-USDC",
      "x-parameter-location": "path"
    }
  }
}

Query Parameters

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "getHyperliquidSpotOrderbookHistory query parameters",
  "type": "object",
  "properties": {
    "start": {
      "description": "Start timestamp in Unix milliseconds. Defaults depend on the route family.",
      "type": "integer",
      "format": "int64",
      "x-parameter-location": "query"
    },
    "end": {
      "description": "End timestamp in Unix milliseconds. Defaults to now.",
      "type": "integer",
      "format": "int64",
      "x-parameter-location": "query"
    },
    "cursor": {
      "description": "Cursor for pagination. Use the value from the previous response metadata.",
      "type": "string",
      "x-parameter-location": "query"
    },
    "limit": {
      "description": "Maximum number of results (default: 100, max: 1000)",
      "type": "integer",
      "default": 100,
      "maximum": 1000,
      "x-parameter-location": "query"
    },
    "depth": {
      "description": "Number of price levels per side.",
      "type": "integer",
      "example": 20,
      "x-parameter-location": "query"
    }
  }
}

Response Contracts

Status 200

Spot order book snapshots

application/json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "getHyperliquidSpotOrderbookHistory response 200",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "description": "L2 order book snapshot",
        "type": "object",
        "required": [
          "asks",
          "bids",
          "coin",
          "symbol",
          "timestamp"
        ],
        "properties": {
          "asks": {
            "description": "Ask price levels (best ask first)",
            "type": "array",
            "items": {
              "description": "Single price level in the order book",
              "type": "object",
              "required": [
                "n",
                "px",
                "sz"
              ],
              "properties": {
                "n": {
                  "description": "Number of orders at this level",
                  "type": "integer",
                  "example": 15
                },
                "px": {
                  "description": "Price",
                  "type": "string",
                  "example": "42150.00"
                },
                "sz": {
                  "description": "Total size at this price level",
                  "type": "string",
                  "example": "1.5"
                }
              }
            }
          },
          "bids": {
            "description": "Bid price levels (best bid first)",
            "type": "array",
            "items": {
              "description": "Single price level in the order book",
              "type": "object",
              "required": [
                "n",
                "px",
                "sz"
              ],
              "properties": {
                "n": {
                  "description": "Number of orders at this level",
                  "type": "integer",
                  "example": 15
                },
                "px": {
                  "description": "Price",
                  "type": "string",
                  "example": "42150.00"
                },
                "sz": {
                  "description": "Total size at this price level",
                  "type": "string",
                  "example": "1.5"
                }
              }
            }
          },
          "coin": {
            "description": "Trading pair symbol (deprecated, use symbol instead)",
            "type": "string",
            "deprecated": true,
            "example": "BTC"
          },
          "mid_price": {
            "description": "Mid price (best bid + best ask) / 2",
            "type": "string",
            "example": "42150.50"
          },
          "spread": {
            "description": "Spread in absolute terms (best ask - best bid)",
            "type": "string",
            "example": "1.00"
          },
          "spread_bps": {
            "description": "Spread in basis points",
            "type": "string",
            "example": "2.37"
          },
          "symbol": {
            "description": "Trading pair symbol",
            "type": "string",
            "example": "BTC"
          },
          "timestamp": {
            "description": "Snapshot timestamp (UTC)",
            "type": "string",
            "format": "date-time",
            "example": "2025-01-21T10:30:45.123Z"
          }
        }
      }
    },
    "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 request

application/json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "getHyperliquidSpotOrderbookHistory 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 required

application/json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "getHyperliquidSpotOrderbookHistory 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 exceeded

application/json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "getHyperliquidSpotOrderbookHistory 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"
}

Endpoint reference

Requests and responses

Datasets

Venues

OpenAPI and schemas

Guides

Get Hyperliquid Spot order book history JSON Schema

Route Metadata

Human endpoint reference

Request Parameters

Path Parameters

Query Parameters

Response Contracts

Status 200

application/json

Status 400

application/json

OpenAPI example

Status 401

application/json

OpenAPI example

Status 429

application/json

OpenAPI example

​Route Metadata

​Human endpoint reference

​Request Parameters

​Path Parameters

​Query Parameters

​Response Contracts

​Status 200

​application/json

​Status 400

​application/json

OpenAPI example

​Status 401

​application/json

OpenAPI example

​Status 429

​application/json

OpenAPI example

Route Metadata

Human endpoint reference

Request Parameters

Path Parameters

Query Parameters

Response Contracts

Status 200

application/json

Status 400

application/json

Status 401

application/json

Status 429

application/json