> ## Documentation Index > Fetch the complete documentation index at: https://docs.0xarchive.io/llms.txt > Use this file to discover all available pages before exploring further. # Get HIP-3 positioning JSON Schema > Get HIP-3 positioning JSON Schema contract. Includes route metadata, request parameters, response statuses, examples, and JSON fields for implementation. Source OpenAPI: 0xArchive API 1.10.0; 240 paths; 241 component schemas. Get every HIP-3 perp with open interest in the last hour over a trailing window in one response: open interest and mark at the window's start and end, taker buy and sell notional, long and short liquidations, and the market's typical move over windows of the same length, so HIP-3 markets can be ranked or grouped by positioning without a history read per market. Included with the Build, Pro, Scale and Enterprise plans. A key on another plan receives 403 `forbidden` naming the dataset, the plans that include it and where to upgrade, and is not charged. **Window:** `window` is required: `1h`, `4h` or `24h`. The window is `[window_start, window_end)` and ends at the newest 5-minute boundary at least 4 minutes old; `meta.as_of` names it. Shortly after a new boundary a response can still describe the previous one while the next is prepared, so compare `meta.as_of` across responses. Current window only: history is not served, and every parameter other than `window` is refused with 400 `invalid_parameter` naming it. **Records:** one per market, sorted by symbol, not paged. `oi_start` and `mark_start` are the 5-minute readings of the bucket before the window, `oi_end` and `mark_end` those of its last bucket; each is null, never 0, when its bucket has no reading. `typical_price`, `typical_oi` and `typical_flow` are the median absolute move over every window of the same length sliding by 5 minutes through the last 2,000 five-minute buckets (about 6.9 days); under 288 counted windows they are null. If the cross-section is still being prepared, the route answers 503 `upstream_unavailable` with `Retry-After`. **Credits:** 1 credit per request. ## Route Metadata | Field | Value | | - | - | | Method | `GET` | | Path | `/v1/hyperliquid/hip3/positioning` | | operationId | `getHip3Positioning` | | Tag | HIP-3 Builder Perps - Positioning | | Family | HIP-3 | | Deprecated or legacy | no | ## Human endpoint reference Open [`GET /v1/hyperliquid/hip3/positioning`](https://docs.0xarchive.io/api-reference/hip-3-builder-perps--positioning/get-hip-3-positioning) for authentication, parameters, responses, and examples. ## Implementation context * [Positioning window and typical moves](https://docs.0xarchive.io/rest-api/positioning.md) ## Request Parameters ### Query Parameters ```json theme={"theme":"github-dark"} { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "getHip3Positioning query parameters", "type": "object", "required": [ "window" ], "properties": { "window": { "description": "The trailing window. Required.", "type": "string", "enum": [ "1h", "4h", "24h" ], "x-parameter-location": "query" } } } ``` ### Header Parameters ```json theme={"theme":"github-dark"} { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "getHip3Positioning header parameters", "type": "object", "properties": { "0xArchive-Version": { "description": "Selects the 2026-10 response contract. Send `2026-10-01`; any dated version on or after it selects the same shapes. Without the header every response keeps its existing shape. With it:\n\n- The data quality routes, `/v1/status/coverage` and `/v1/symbols` answer the standard `{success, data, meta}` envelope.\n- Record times that are integer milliseconds by default become RFC 3339 UTC strings with millisecond precision, and the integer moves to a `*_ms` field: L4 resting-order `timestamp` (`timestamp_ms`), CVD buckets, HIP-3 oracle reads, Lighter and Lighter on Robinhood Chain liquidations and liquidation volume. Levels and trigger-levels `snapshot_ts` become RFC 3339 with `snapshot_ts_ms`.\n- Error bodies carry the contract `error_code` names: `invalid_parameter` instead of `invalid_query_params` and `invalid_path_params`, `historical_depth_exceeded` instead of `history_window_exceeded`, and `historical_range_exceeded` instead of `request_range_exceeded`; a malformed cursor that fails to parse answers 400 `invalid_cursor` instead of `invalid_query_params`. With `0xArchive-Version: 2026-10-01`, malformed cursors on trades, liquidations, L2 and L4 diffs, order history, TP/SL and order-flow routes answer 400 `invalid_cursor`. Without the header, the first six route families treat a malformed cursor as no cursor and return the first page; order flow answers 400 `invalid_query_params`. Malformed trade time inputs answer 400 `invalid_time_range` with the header and 400 `invalid_query_params` without it.\n\nThe response echoes the selected version in its own `0xArchive-Version` header.", "type": "string", "enum": [ "2026-10-01" ], "example": "2026-10-01", "x-parameter-location": "header" } } } ``` ## Response Contracts ### Status 200 One positioning record per HIP-3 perp #### application/json ```json theme={"theme":"github-dark"} { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "getHip3Positioning response 200", "description": "API response containing one positioning record per listed perp, sorted by symbol. `meta.as_of` is the 5-minute close the records describe.", "type": "object", "properties": { "data": { "type": "array", "items": { "description": "One listed perp over the trailing window.", "type": "object", "required": [ "buy_usd", "liq_long_count", "liq_long_usd", "liq_short_count", "liq_short_usd", "mark_end", "mark_start", "oi_buckets", "oi_end", "oi_start", "sell_usd", "symbol", "typical_flow", "typical_oi", "typical_price", "typical_windows", "window", "window_end", "window_end_ms", "window_start", "window_start_ms" ], "properties": { "buy_usd": { "description": "Taker buy notional in the window, USD to the cent. 0 means none.", "type": "number", "format": "double", "example": 426153898.11 }, "liq_long_count": { "description": "Long liquidations in the window.", "type": "integer", "format": "int64", "example": 35 }, "liq_long_usd": { "description": "Notional of long positions liquidated in the window, USD to the cent.", "type": "number", "format": "double", "example": 132411.14 }, "liq_short_count": { "description": "Short liquidations in the window.", "type": "integer", "format": "int64", "example": 1 }, "liq_short_usd": { "description": "Notional of short positions liquidated in the window, USD to the cent.", "type": "number", "format": "double", "example": 5186.43 }, "mark_end": { "description": "Mark price at the window's last 5-minute reading. Null when that bucket has no reading.", "type": "number", "format": "double", "nullable": true, "example": 80010 }, "mark_start": { "description": "Mark price at the 5-minute reading before the window. Null when that bucket has no reading.", "type": "number", "format": "double", "nullable": true, "example": 80139 }, "oi_buckets": { "description": "Number of 5-minute open interest readings inside the window.", "type": "integer", "example": 48 }, "oi_end": { "description": "Open interest in contracts at the window's last 5-minute reading. Null when that bucket has no reading.", "type": "number", "format": "double", "nullable": true, "example": 39592.93574 }, "oi_start": { "description": "Open interest in contracts at the 5-minute reading before the window. Null when that bucket has no reading, never 0.", "type": "number", "format": "double", "nullable": true, "example": 41558.2733 }, "sell_usd": { "description": "Taker sell notional in the window, USD to the cent. 0 means none.", "type": "number", "format": "double", "example": 452128639.73 }, "symbol": { "description": "The market's symbol.", "type": "string", "example": "BTC" }, "typical_flow": { "description": "Median absolute taker imbalance, (buy - sell) / (buy + sell), over the same windows. Null under 288 counted windows.", "type": "number", "format": "double", "nullable": true, "example": 0.10512875847481765 }, "typical_oi": { "description": "Median absolute relative change of open interest over the same windows. Null under 288 counted windows.", "type": "number", "format": "double", "nullable": true, "example": 0.010328192376292733 }, "typical_price": { "description": "Median absolute relative change of the mark over every window of this length in the last 2,000 five-minute buckets. Null under 288 counted windows.", "type": "number", "format": "double", "nullable": true, "example": 0.003597216644913026 }, "typical_windows": { "description": "Windows counted for the `typical_*` figures.", "type": "integer", "example": 1952 }, "window": { "description": "The requested window.", "type": "string", "enum": [ "1h", "4h", "24h" ], "example": "4h" }, "window_end": { "description": "End of the window, exclusive: the 5-minute close the cross-section is as of. Equal to `meta.as_of`.", "type": "string", "format": "date-time", "example": "2026-11-04T20:00:00.000Z" }, "window_end_ms": { "description": "`window_end` as Unix milliseconds.", "type": "integer", "format": "int64", "example": 1793822400000 }, "window_start": { "description": "Start of the window, inclusive.", "type": "string", "format": "date-time", "example": "2026-11-04T16:00:00.000Z" }, "window_start_ms": { "description": "`window_start` as Unix milliseconds.", "type": "integer", "format": "int64", "example": 1793808000000 } } } }, "meta": { "description": "Response metadata. Every 2xx JSON response carries `meta.request_id`; list payloads add `count`; cursor-paged routes add `has_more` and, when another page follows, `next_cursor`; per-symbol routes add `symbol` and `venue`. Fields that do not apply to a route are omitted.", "type": "object", "required": [ "request_id" ], "properties": { "as_of": { "description": "Positioning: the 5-minute close the records describe, equal to each record's `window_end`.", "type": "string", "format": "date-time" }, "built_through": { "description": "Trade intent: how far the series is built. A second without a record had no trades up to this instant; after it nothing is known yet.", "type": "string", "format": "date-time" }, "clamped_to": { "description": "The boundary the request's `end` was clamped to, when clamping occurred.", "type": "string", "format": "date-time", "nullable": true }, "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" }, "finalized_through": { "description": "Two-tier datasets (Lighter trades): data at or before this instant is final; later data is preliminary.", "type": "string", "format": "date-time" }, "has_more": { "description": "Cursor-paged routes: whether another page follows. `next_cursor` is present exactly when this is `true`. A final page can be empty when the previous page was exactly full; `has_more` is `false` on it.", "type": "boolean" }, "next_cursor": { "description": "Opaque cursor for the next page, present exactly when `has_more` is `true`. Pass it back unchanged as `cursor` with the same filters. Do not parse or construct it.", "type": "string" }, "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" }, "preliminary_row_count": { "description": "Number of preliminary rows in this response, on routes that intentionally serve preliminary data (Lighter `/recent`, trade intent).", "type": "integer", "nullable": true }, "request_id": { "description": "Unique request ID for support", "type": "string", "format": "uuid" }, "requested_end": { "description": "The `end` the request asked for, echoed when it was clamped to `finalized_through`.", "type": "string", "format": "date-time", "nullable": true }, "symbol": { "description": "Per-symbol routes: the canonical public symbol the response describes (for example `BTC`, `xyz:TSLA`, `HYPE-USDC`, `#0`).", "type": "string", "example": "BTC" }, "venue": { "description": "Per-symbol routes: the venue the response describes.", "type": "string", "enum": [ "hyperliquid", "hip3", "hip4", "spot", "lighter", "rh-lighter" ], "example": "hyperliquid" } } }, "success": { "type": "boolean", "example": true } } } ``` ### Status 400 Invalid request: a parameter, symbol, interval, cursor or time range failed validation. See `error_code`. #### application/json ```json theme={"theme":"github-dark"} { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "getHip3Positioning response 400", "description": "Body of every non-2xx JSON response. `code` repeats the HTTP status, `error_code` is the stable machine-readable code (see `ErrorCode`), `error` is a human-readable message, and `request_id` identifies the request for support. Validation failures add `param` and, where the accepted set is fixed, `valid_values`. A 404 for a datatype the venue does not offer (`unsupported_for_venue`) adds `venue`, `datatype` and `available_on`; any other unknown path answers 404 `route_not_found`.", "type": "object", "required": [ "code", "error", "error_code", "request_id", "success" ], "properties": { "available_on": { "description": "`unsupported_for_venue` only: the venues and routes that serve the datatype.", "type": "array", "items": { "type": "object", "required": [ "route", "venue" ], "properties": { "route": { "type": "string", "example": "/v1/hyperliquid/orders/{symbol}/flow" }, "venue": { "type": "string", "example": "hyperliquid" } } } }, "code": { "description": "HTTP status code.", "type": "integer", "example": 400 }, "credits_limit": { "description": "`insufficient_credits` only: the period's credit allowance.", "type": "integer", "format": "int64" }, "credits_used": { "description": "`insufficient_credits` only: credits used this period.", "type": "integer", "format": "int64" }, "datatype": { "description": "`unsupported_for_venue` and plan refusals (`forbidden`): the datatype the request asked for, as `GET /v1/capabilities` names it.", "type": "string", "example": "order_flow" }, "error": { "description": "Human-readable message. Wording can change; do not parse it.", "type": "string" }, "error_code": { "description": "Stable, machine-readable error code. Branch on this value, not on the `error` text.\n\n**Contract codes**\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `invalid_parameter` | 400 | A parameter failed to parse or validate. `param` names it and `valid_values` lists accepted values where the set is fixed. |\n| `invalid_symbol` | 400 | The symbol is not listed on this venue. |\n| `invalid_interval` | 400 | The `interval` (bucket width) is not one this route accepts. |\n| `invalid_cursor` | 400 | The `cursor` is malformed, stale, or was issued for other filters. Restart pagination without a cursor. Trades, liquidations, L2 and L4 diffs, order history and TP/SL routes currently return the first page for a malformed cursor instead. |\n| `invalid_time_range` | 400 | `start` is after `end`, or a time value could not be parsed. |\n| `range_before_coverage` | 400 | The whole requested range ends before the first instant this dataset is served from. |\n| `historical_range_exceeded` | 403 | The requested span is longer than the plan allows in one request or replay. |\n| `historical_depth_exceeded` | 403 | The request reaches further back than the plan's history window. |\n| `unsupported_for_venue` | 404 | The venue does not offer this datatype. The message, `datatype` and `available_on` name where it is served. |\n| `route_not_found` | 404 | No route matches the path or method. `GET /v1/capabilities` lists the routes each venue serves. |\n| `not_found` | 404 | The route exists but the requested resource (for example an incident, endpoint or outcome id) does not. |\n| `unauthorized` | 401 | The API key is missing or invalid. |\n| `forbidden` | 403 | The key is valid but not allowed to make this request, including a dataset its plan does not include: `datatype`, `required_plans` and `upgrade_url` name it. A refused request is not charged. |\n| `insufficient_credits` | 429 | The monthly credit allowance is spent (402 on pay-per-request routes). |\n| `rate_limited` | 429 | Too many requests or concurrent queries. Retry after the interval in the rate-limit headers. |\n| `conflict` | 409 | The request conflicts with the current state of the resource. |\n| `upstream_unavailable` | 503 | A dependency is unavailable or saturated. Retry shortly; the response carries `Retry-After`. |\n| `internal_error` | 500 | An unexpected server error. Quote `request_id` when contacting support. |\n\n**WebSocket only** (sent in `{\"type\":\"error\"}` messages, never by REST)\n\n| Code | Where | Meaning |\n|---|---|---|\n| `endpoint_unsupported` | WebSocket | This WebSocket endpoint does not serve the channel or operation. The message names the endpoint that does. |\n| `slow_consumer` | WebSocket | The connection fell behind a stream and messages were dropped. Re-subscribe, or restart the replay, to resynchronise. |\n\n**Route-specific codes**\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `positions_unavailable` | 503 | Account positions are temporarily unavailable for this venue. |\n| `reconstruction_unavailable` | 503 | The as-of positions state for this instant cannot be reconstructed right now. |\n| `snapshot_advanced` | 409 | A positions market cursor pinned a snapshot that has since been replaced or expired. Restart pagination. |\n| `pagination_unavailable` | 503 | The next positions page cannot be served right now. Retry the same cursor shortly. |\n| `api_key_limit_reached` | 403 | The account already holds the maximum number of API keys for its plan. |\n| `wallet_requires_plan` | 402 | A wallet-authenticated key needs an active plan for this request. |\n| `wallet_account_required` | 403 | Wallet sign-in needs an existing account linked to the wallet. |\n| `wallet_free_signup_retired` | 410 | Free wallet sign-up is no longer offered. |\n| `account_disabled` | 403 | The account is disabled. |\n| `oauth_not_permitted` | 403 | This route is not available to OAuth access tokens. |\n| `insufficient_scope` | 403 | The OAuth access token lacks the scope this route requires. |\n\n**Legacy names.** Requests without `0xArchive-Version: 2026-10-01` keep the four names that predate the contract; with the header they receive the contract names instead.\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `invalid_query_params` | 400 | Legacy name of `invalid_parameter` (query parameter), or of `invalid_cursor` when the parameter is `cursor`, sent without the version header. |\n| `invalid_path_params` | 400 | Legacy name of `invalid_parameter` (path parameter), sent without the version header. |\n| `history_window_exceeded` | 403 | Legacy name of `historical_depth_exceeded`, sent without the version header. |\n| `request_range_exceeded` | 403 | Legacy name of `historical_range_exceeded`, sent without the version header. |\n\nTreat any value not listed here as a generic error of the HTTP status.", "type": "string", "enum": [ "invalid_parameter", "invalid_symbol", "invalid_interval", "invalid_cursor", "invalid_time_range", "range_before_coverage", "historical_range_exceeded", "historical_depth_exceeded", "unsupported_for_venue", "route_not_found", "not_found", "unauthorized", "forbidden", "insufficient_credits", "rate_limited", "conflict", "upstream_unavailable", "internal_error", "endpoint_unsupported", "slow_consumer", "positions_unavailable", "reconstruction_unavailable", "snapshot_advanced", "pagination_unavailable", "api_key_limit_reached", "wallet_requires_plan", "wallet_account_required", "wallet_free_signup_retired", "account_disabled", "oauth_not_permitted", "insufficient_scope", "invalid_query_params", "invalid_path_params", "history_window_exceeded", "request_range_exceeded" ], "example": "invalid_parameter" }, "max_concurrent": { "description": "`rate_limited` concurrency refusals only: simultaneous queries the plan allows.", "type": "integer" }, "param": { "description": "The parameter that failed validation, when one did.", "type": "string", "example": "side" }, "request_id": { "description": "Unique request ID for support.", "type": "string", "format": "uuid" }, "required_plans": { "description": "Plan refusals (`forbidden`) only: the plans that include the datatype.", "type": "array", "items": { "type": "string" }, "example": [ "build", "pro", "scale", "enterprise" ] }, "success": { "description": "Always `false` on an error.", "type": "boolean", "enum": [ false ] }, "suggestion": { "description": "Present when the symbol exists on another venue: where to request it instead.", "type": "object", "properties": { "endpoint": { "type": "string", "example": "/v1/hyperliquid/hip3/trades/xyz:TSLA" }, "symbol": { "type": "string", "example": "xyz:TSLA" }, "venue": { "type": "string", "example": "hip3" } } }, "upgrade_url": { "description": "Plan refusals (`forbidden`) only: where to change plan.", "type": "string", "format": "uri", "example": "https://0xarchive.io/pricing" }, "valid_values": { "description": "Accepted values of `param`, when the set is fixed.", "type": "array", "items": { "type": "string" }, "example": [ "buy", "sell" ] }, "venue": { "description": "`unsupported_for_venue` only: the venue the request asked.", "type": "string", "example": "spot" } } } ``` ##### OpenAPI example: `current_main` ```json theme={"theme":"github-dark"} { "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 } ``` ##### OpenAPI example: `invalid_parameter` ```json theme={"theme":"github-dark"} { "success": false, "code": 400, "error_code": "invalid_parameter", "error": "Invalid side 'up'. Use buy or sell.", "request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05", "param": "side", "valid_values": [ "buy", "sell" ] } ``` ##### OpenAPI example: `invalid_symbol` ```json theme={"theme":"github-dark"} { "success": false, "code": 400, "error_code": "invalid_symbol", "error": "The symbol 'ZZZ' does not exist. Please see /v1/hyperliquid/instruments for available symbols.", "request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05", "param": "symbol" } ``` ##### OpenAPI example: `invalid_time_range` ```json theme={"theme":"github-dark"} { "success": false, "code": 400, "error_code": "invalid_time_range", "error": "start must be <= end", "request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05" } ``` ##### OpenAPI example: `legacy_invalid_query_params` ```json theme={"theme":"github-dark"} { "success": false, "code": 400, "error_code": "invalid_query_params", "error": "Failed to deserialize query string: limit: invalid digit found in string", "request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05" } ``` ### Status 401 Authentication required: the API key is missing or invalid. #### application/json ```json theme={"theme":"github-dark"} { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "getHip3Positioning response 401", "description": "Body of every non-2xx JSON response. `code` repeats the HTTP status, `error_code` is the stable machine-readable code (see `ErrorCode`), `error` is a human-readable message, and `request_id` identifies the request for support. Validation failures add `param` and, where the accepted set is fixed, `valid_values`. A 404 for a datatype the venue does not offer (`unsupported_for_venue`) adds `venue`, `datatype` and `available_on`; any other unknown path answers 404 `route_not_found`.", "type": "object", "required": [ "code", "error", "error_code", "request_id", "success" ], "properties": { "available_on": { "description": "`unsupported_for_venue` only: the venues and routes that serve the datatype.", "type": "array", "items": { "type": "object", "required": [ "route", "venue" ], "properties": { "route": { "type": "string", "example": "/v1/hyperliquid/orders/{symbol}/flow" }, "venue": { "type": "string", "example": "hyperliquid" } } } }, "code": { "description": "HTTP status code.", "type": "integer", "example": 400 }, "credits_limit": { "description": "`insufficient_credits` only: the period's credit allowance.", "type": "integer", "format": "int64" }, "credits_used": { "description": "`insufficient_credits` only: credits used this period.", "type": "integer", "format": "int64" }, "datatype": { "description": "`unsupported_for_venue` and plan refusals (`forbidden`): the datatype the request asked for, as `GET /v1/capabilities` names it.", "type": "string", "example": "order_flow" }, "error": { "description": "Human-readable message. Wording can change; do not parse it.", "type": "string" }, "error_code": { "description": "Stable, machine-readable error code. Branch on this value, not on the `error` text.\n\n**Contract codes**\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `invalid_parameter` | 400 | A parameter failed to parse or validate. `param` names it and `valid_values` lists accepted values where the set is fixed. |\n| `invalid_symbol` | 400 | The symbol is not listed on this venue. |\n| `invalid_interval` | 400 | The `interval` (bucket width) is not one this route accepts. |\n| `invalid_cursor` | 400 | The `cursor` is malformed, stale, or was issued for other filters. Restart pagination without a cursor. Trades, liquidations, L2 and L4 diffs, order history and TP/SL routes currently return the first page for a malformed cursor instead. |\n| `invalid_time_range` | 400 | `start` is after `end`, or a time value could not be parsed. |\n| `range_before_coverage` | 400 | The whole requested range ends before the first instant this dataset is served from. |\n| `historical_range_exceeded` | 403 | The requested span is longer than the plan allows in one request or replay. |\n| `historical_depth_exceeded` | 403 | The request reaches further back than the plan's history window. |\n| `unsupported_for_venue` | 404 | The venue does not offer this datatype. The message, `datatype` and `available_on` name where it is served. |\n| `route_not_found` | 404 | No route matches the path or method. `GET /v1/capabilities` lists the routes each venue serves. |\n| `not_found` | 404 | The route exists but the requested resource (for example an incident, endpoint or outcome id) does not. |\n| `unauthorized` | 401 | The API key is missing or invalid. |\n| `forbidden` | 403 | The key is valid but not allowed to make this request, including a dataset its plan does not include: `datatype`, `required_plans` and `upgrade_url` name it. A refused request is not charged. |\n| `insufficient_credits` | 429 | The monthly credit allowance is spent (402 on pay-per-request routes). |\n| `rate_limited` | 429 | Too many requests or concurrent queries. Retry after the interval in the rate-limit headers. |\n| `conflict` | 409 | The request conflicts with the current state of the resource. |\n| `upstream_unavailable` | 503 | A dependency is unavailable or saturated. Retry shortly; the response carries `Retry-After`. |\n| `internal_error` | 500 | An unexpected server error. Quote `request_id` when contacting support. |\n\n**WebSocket only** (sent in `{\"type\":\"error\"}` messages, never by REST)\n\n| Code | Where | Meaning |\n|---|---|---|\n| `endpoint_unsupported` | WebSocket | This WebSocket endpoint does not serve the channel or operation. The message names the endpoint that does. |\n| `slow_consumer` | WebSocket | The connection fell behind a stream and messages were dropped. Re-subscribe, or restart the replay, to resynchronise. |\n\n**Route-specific codes**\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `positions_unavailable` | 503 | Account positions are temporarily unavailable for this venue. |\n| `reconstruction_unavailable` | 503 | The as-of positions state for this instant cannot be reconstructed right now. |\n| `snapshot_advanced` | 409 | A positions market cursor pinned a snapshot that has since been replaced or expired. Restart pagination. |\n| `pagination_unavailable` | 503 | The next positions page cannot be served right now. Retry the same cursor shortly. |\n| `api_key_limit_reached` | 403 | The account already holds the maximum number of API keys for its plan. |\n| `wallet_requires_plan` | 402 | A wallet-authenticated key needs an active plan for this request. |\n| `wallet_account_required` | 403 | Wallet sign-in needs an existing account linked to the wallet. |\n| `wallet_free_signup_retired` | 410 | Free wallet sign-up is no longer offered. |\n| `account_disabled` | 403 | The account is disabled. |\n| `oauth_not_permitted` | 403 | This route is not available to OAuth access tokens. |\n| `insufficient_scope` | 403 | The OAuth access token lacks the scope this route requires. |\n\n**Legacy names.** Requests without `0xArchive-Version: 2026-10-01` keep the four names that predate the contract; with the header they receive the contract names instead.\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `invalid_query_params` | 400 | Legacy name of `invalid_parameter` (query parameter), or of `invalid_cursor` when the parameter is `cursor`, sent without the version header. |\n| `invalid_path_params` | 400 | Legacy name of `invalid_parameter` (path parameter), sent without the version header. |\n| `history_window_exceeded` | 403 | Legacy name of `historical_depth_exceeded`, sent without the version header. |\n| `request_range_exceeded` | 403 | Legacy name of `historical_range_exceeded`, sent without the version header. |\n\nTreat any value not listed here as a generic error of the HTTP status.", "type": "string", "enum": [ "invalid_parameter", "invalid_symbol", "invalid_interval", "invalid_cursor", "invalid_time_range", "range_before_coverage", "historical_range_exceeded", "historical_depth_exceeded", "unsupported_for_venue", "route_not_found", "not_found", "unauthorized", "forbidden", "insufficient_credits", "rate_limited", "conflict", "upstream_unavailable", "internal_error", "endpoint_unsupported", "slow_consumer", "positions_unavailable", "reconstruction_unavailable", "snapshot_advanced", "pagination_unavailable", "api_key_limit_reached", "wallet_requires_plan", "wallet_account_required", "wallet_free_signup_retired", "account_disabled", "oauth_not_permitted", "insufficient_scope", "invalid_query_params", "invalid_path_params", "history_window_exceeded", "request_range_exceeded" ], "example": "invalid_parameter" }, "max_concurrent": { "description": "`rate_limited` concurrency refusals only: simultaneous queries the plan allows.", "type": "integer" }, "param": { "description": "The parameter that failed validation, when one did.", "type": "string", "example": "side" }, "request_id": { "description": "Unique request ID for support.", "type": "string", "format": "uuid" }, "required_plans": { "description": "Plan refusals (`forbidden`) only: the plans that include the datatype.", "type": "array", "items": { "type": "string" }, "example": [ "build", "pro", "scale", "enterprise" ] }, "success": { "description": "Always `false` on an error.", "type": "boolean", "enum": [ false ] }, "suggestion": { "description": "Present when the symbol exists on another venue: where to request it instead.", "type": "object", "properties": { "endpoint": { "type": "string", "example": "/v1/hyperliquid/hip3/trades/xyz:TSLA" }, "symbol": { "type": "string", "example": "xyz:TSLA" }, "venue": { "type": "string", "example": "hip3" } } }, "upgrade_url": { "description": "Plan refusals (`forbidden`) only: where to change plan.", "type": "string", "format": "uri", "example": "https://0xarchive.io/pricing" }, "valid_values": { "description": "Accepted values of `param`, when the set is fixed.", "type": "array", "items": { "type": "string" }, "example": [ "buy", "sell" ] }, "venue": { "description": "`unsupported_for_venue` only: the venue the request asked.", "type": "string", "example": "spot" } } } ``` ##### OpenAPI example ```json theme={"theme":"github-dark"} { "success": false, "code": 401, "error_code": "unauthorized", "error": "Missing authentication credentials. Provide X-API-Key header or Bearer token.", "request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05" } ``` ### Status 403 The dataset is not included with the key's plan. The body names the datatype, the plans that include it and where to upgrade. A refused request is not charged. #### application/json ```json theme={"theme":"github-dark"} { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "getHip3Positioning response 403", "description": "Body of every non-2xx JSON response. `code` repeats the HTTP status, `error_code` is the stable machine-readable code (see `ErrorCode`), `error` is a human-readable message, and `request_id` identifies the request for support. Validation failures add `param` and, where the accepted set is fixed, `valid_values`. A 404 for a datatype the venue does not offer (`unsupported_for_venue`) adds `venue`, `datatype` and `available_on`; any other unknown path answers 404 `route_not_found`.", "type": "object", "required": [ "code", "error", "error_code", "request_id", "success" ], "properties": { "available_on": { "description": "`unsupported_for_venue` only: the venues and routes that serve the datatype.", "type": "array", "items": { "type": "object", "required": [ "route", "venue" ], "properties": { "route": { "type": "string", "example": "/v1/hyperliquid/orders/{symbol}/flow" }, "venue": { "type": "string", "example": "hyperliquid" } } } }, "code": { "description": "HTTP status code.", "type": "integer", "example": 400 }, "credits_limit": { "description": "`insufficient_credits` only: the period's credit allowance.", "type": "integer", "format": "int64" }, "credits_used": { "description": "`insufficient_credits` only: credits used this period.", "type": "integer", "format": "int64" }, "datatype": { "description": "`unsupported_for_venue` and plan refusals (`forbidden`): the datatype the request asked for, as `GET /v1/capabilities` names it.", "type": "string", "example": "order_flow" }, "error": { "description": "Human-readable message. Wording can change; do not parse it.", "type": "string" }, "error_code": { "description": "Stable, machine-readable error code. Branch on this value, not on the `error` text.\n\n**Contract codes**\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `invalid_parameter` | 400 | A parameter failed to parse or validate. `param` names it and `valid_values` lists accepted values where the set is fixed. |\n| `invalid_symbol` | 400 | The symbol is not listed on this venue. |\n| `invalid_interval` | 400 | The `interval` (bucket width) is not one this route accepts. |\n| `invalid_cursor` | 400 | The `cursor` is malformed, stale, or was issued for other filters. Restart pagination without a cursor. Trades, liquidations, L2 and L4 diffs, order history and TP/SL routes currently return the first page for a malformed cursor instead. |\n| `invalid_time_range` | 400 | `start` is after `end`, or a time value could not be parsed. |\n| `range_before_coverage` | 400 | The whole requested range ends before the first instant this dataset is served from. |\n| `historical_range_exceeded` | 403 | The requested span is longer than the plan allows in one request or replay. |\n| `historical_depth_exceeded` | 403 | The request reaches further back than the plan's history window. |\n| `unsupported_for_venue` | 404 | The venue does not offer this datatype. The message, `datatype` and `available_on` name where it is served. |\n| `route_not_found` | 404 | No route matches the path or method. `GET /v1/capabilities` lists the routes each venue serves. |\n| `not_found` | 404 | The route exists but the requested resource (for example an incident, endpoint or outcome id) does not. |\n| `unauthorized` | 401 | The API key is missing or invalid. |\n| `forbidden` | 403 | The key is valid but not allowed to make this request, including a dataset its plan does not include: `datatype`, `required_plans` and `upgrade_url` name it. A refused request is not charged. |\n| `insufficient_credits` | 429 | The monthly credit allowance is spent (402 on pay-per-request routes). |\n| `rate_limited` | 429 | Too many requests or concurrent queries. Retry after the interval in the rate-limit headers. |\n| `conflict` | 409 | The request conflicts with the current state of the resource. |\n| `upstream_unavailable` | 503 | A dependency is unavailable or saturated. Retry shortly; the response carries `Retry-After`. |\n| `internal_error` | 500 | An unexpected server error. Quote `request_id` when contacting support. |\n\n**WebSocket only** (sent in `{\"type\":\"error\"}` messages, never by REST)\n\n| Code | Where | Meaning |\n|---|---|---|\n| `endpoint_unsupported` | WebSocket | This WebSocket endpoint does not serve the channel or operation. The message names the endpoint that does. |\n| `slow_consumer` | WebSocket | The connection fell behind a stream and messages were dropped. Re-subscribe, or restart the replay, to resynchronise. |\n\n**Route-specific codes**\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `positions_unavailable` | 503 | Account positions are temporarily unavailable for this venue. |\n| `reconstruction_unavailable` | 503 | The as-of positions state for this instant cannot be reconstructed right now. |\n| `snapshot_advanced` | 409 | A positions market cursor pinned a snapshot that has since been replaced or expired. Restart pagination. |\n| `pagination_unavailable` | 503 | The next positions page cannot be served right now. Retry the same cursor shortly. |\n| `api_key_limit_reached` | 403 | The account already holds the maximum number of API keys for its plan. |\n| `wallet_requires_plan` | 402 | A wallet-authenticated key needs an active plan for this request. |\n| `wallet_account_required` | 403 | Wallet sign-in needs an existing account linked to the wallet. |\n| `wallet_free_signup_retired` | 410 | Free wallet sign-up is no longer offered. |\n| `account_disabled` | 403 | The account is disabled. |\n| `oauth_not_permitted` | 403 | This route is not available to OAuth access tokens. |\n| `insufficient_scope` | 403 | The OAuth access token lacks the scope this route requires. |\n\n**Legacy names.** Requests without `0xArchive-Version: 2026-10-01` keep the four names that predate the contract; with the header they receive the contract names instead.\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `invalid_query_params` | 400 | Legacy name of `invalid_parameter` (query parameter), or of `invalid_cursor` when the parameter is `cursor`, sent without the version header. |\n| `invalid_path_params` | 400 | Legacy name of `invalid_parameter` (path parameter), sent without the version header. |\n| `history_window_exceeded` | 403 | Legacy name of `historical_depth_exceeded`, sent without the version header. |\n| `request_range_exceeded` | 403 | Legacy name of `historical_range_exceeded`, sent without the version header. |\n\nTreat any value not listed here as a generic error of the HTTP status.", "type": "string", "enum": [ "invalid_parameter", "invalid_symbol", "invalid_interval", "invalid_cursor", "invalid_time_range", "range_before_coverage", "historical_range_exceeded", "historical_depth_exceeded", "unsupported_for_venue", "route_not_found", "not_found", "unauthorized", "forbidden", "insufficient_credits", "rate_limited", "conflict", "upstream_unavailable", "internal_error", "endpoint_unsupported", "slow_consumer", "positions_unavailable", "reconstruction_unavailable", "snapshot_advanced", "pagination_unavailable", "api_key_limit_reached", "wallet_requires_plan", "wallet_account_required", "wallet_free_signup_retired", "account_disabled", "oauth_not_permitted", "insufficient_scope", "invalid_query_params", "invalid_path_params", "history_window_exceeded", "request_range_exceeded" ], "example": "invalid_parameter" }, "max_concurrent": { "description": "`rate_limited` concurrency refusals only: simultaneous queries the plan allows.", "type": "integer" }, "param": { "description": "The parameter that failed validation, when one did.", "type": "string", "example": "side" }, "request_id": { "description": "Unique request ID for support.", "type": "string", "format": "uuid" }, "required_plans": { "description": "Plan refusals (`forbidden`) only: the plans that include the datatype.", "type": "array", "items": { "type": "string" }, "example": [ "build", "pro", "scale", "enterprise" ] }, "success": { "description": "Always `false` on an error.", "type": "boolean", "enum": [ false ] }, "suggestion": { "description": "Present when the symbol exists on another venue: where to request it instead.", "type": "object", "properties": { "endpoint": { "type": "string", "example": "/v1/hyperliquid/hip3/trades/xyz:TSLA" }, "symbol": { "type": "string", "example": "xyz:TSLA" }, "venue": { "type": "string", "example": "hip3" } } }, "upgrade_url": { "description": "Plan refusals (`forbidden`) only: where to change plan.", "type": "string", "format": "uri", "example": "https://0xarchive.io/pricing" }, "valid_values": { "description": "Accepted values of `param`, when the set is fixed.", "type": "array", "items": { "type": "string" }, "example": [ "buy", "sell" ] }, "venue": { "description": "`unsupported_for_venue` only: the venue the request asked.", "type": "string", "example": "spot" } } } ``` ##### OpenAPI example: `forbidden` ```json theme={"theme":"github-dark"} { "success": false, "code": 403, "error_code": "forbidden", "error": "Trade intent is included with the Build, Pro, Scale and Enterprise plans. Upgrade at https://0xarchive.io/pricing.", "request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05", "datatype": "trade_intent", "required_plans": [ "build", "pro", "scale", "enterprise" ], "upgrade_url": "https://0xarchive.io/pricing" } ``` ### Status 429 Rate limit, concurrency limit or monthly credits exceeded. See `error_code`. #### application/json ```json theme={"theme":"github-dark"} { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "getHip3Positioning response 429", "description": "Body of every non-2xx JSON response. `code` repeats the HTTP status, `error_code` is the stable machine-readable code (see `ErrorCode`), `error` is a human-readable message, and `request_id` identifies the request for support. Validation failures add `param` and, where the accepted set is fixed, `valid_values`. A 404 for a datatype the venue does not offer (`unsupported_for_venue`) adds `venue`, `datatype` and `available_on`; any other unknown path answers 404 `route_not_found`.", "type": "object", "required": [ "code", "error", "error_code", "request_id", "success" ], "properties": { "available_on": { "description": "`unsupported_for_venue` only: the venues and routes that serve the datatype.", "type": "array", "items": { "type": "object", "required": [ "route", "venue" ], "properties": { "route": { "type": "string", "example": "/v1/hyperliquid/orders/{symbol}/flow" }, "venue": { "type": "string", "example": "hyperliquid" } } } }, "code": { "description": "HTTP status code.", "type": "integer", "example": 400 }, "credits_limit": { "description": "`insufficient_credits` only: the period's credit allowance.", "type": "integer", "format": "int64" }, "credits_used": { "description": "`insufficient_credits` only: credits used this period.", "type": "integer", "format": "int64" }, "datatype": { "description": "`unsupported_for_venue` and plan refusals (`forbidden`): the datatype the request asked for, as `GET /v1/capabilities` names it.", "type": "string", "example": "order_flow" }, "error": { "description": "Human-readable message. Wording can change; do not parse it.", "type": "string" }, "error_code": { "description": "Stable, machine-readable error code. Branch on this value, not on the `error` text.\n\n**Contract codes**\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `invalid_parameter` | 400 | A parameter failed to parse or validate. `param` names it and `valid_values` lists accepted values where the set is fixed. |\n| `invalid_symbol` | 400 | The symbol is not listed on this venue. |\n| `invalid_interval` | 400 | The `interval` (bucket width) is not one this route accepts. |\n| `invalid_cursor` | 400 | The `cursor` is malformed, stale, or was issued for other filters. Restart pagination without a cursor. Trades, liquidations, L2 and L4 diffs, order history and TP/SL routes currently return the first page for a malformed cursor instead. |\n| `invalid_time_range` | 400 | `start` is after `end`, or a time value could not be parsed. |\n| `range_before_coverage` | 400 | The whole requested range ends before the first instant this dataset is served from. |\n| `historical_range_exceeded` | 403 | The requested span is longer than the plan allows in one request or replay. |\n| `historical_depth_exceeded` | 403 | The request reaches further back than the plan's history window. |\n| `unsupported_for_venue` | 404 | The venue does not offer this datatype. The message, `datatype` and `available_on` name where it is served. |\n| `route_not_found` | 404 | No route matches the path or method. `GET /v1/capabilities` lists the routes each venue serves. |\n| `not_found` | 404 | The route exists but the requested resource (for example an incident, endpoint or outcome id) does not. |\n| `unauthorized` | 401 | The API key is missing or invalid. |\n| `forbidden` | 403 | The key is valid but not allowed to make this request, including a dataset its plan does not include: `datatype`, `required_plans` and `upgrade_url` name it. A refused request is not charged. |\n| `insufficient_credits` | 429 | The monthly credit allowance is spent (402 on pay-per-request routes). |\n| `rate_limited` | 429 | Too many requests or concurrent queries. Retry after the interval in the rate-limit headers. |\n| `conflict` | 409 | The request conflicts with the current state of the resource. |\n| `upstream_unavailable` | 503 | A dependency is unavailable or saturated. Retry shortly; the response carries `Retry-After`. |\n| `internal_error` | 500 | An unexpected server error. Quote `request_id` when contacting support. |\n\n**WebSocket only** (sent in `{\"type\":\"error\"}` messages, never by REST)\n\n| Code | Where | Meaning |\n|---|---|---|\n| `endpoint_unsupported` | WebSocket | This WebSocket endpoint does not serve the channel or operation. The message names the endpoint that does. |\n| `slow_consumer` | WebSocket | The connection fell behind a stream and messages were dropped. Re-subscribe, or restart the replay, to resynchronise. |\n\n**Route-specific codes**\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `positions_unavailable` | 503 | Account positions are temporarily unavailable for this venue. |\n| `reconstruction_unavailable` | 503 | The as-of positions state for this instant cannot be reconstructed right now. |\n| `snapshot_advanced` | 409 | A positions market cursor pinned a snapshot that has since been replaced or expired. Restart pagination. |\n| `pagination_unavailable` | 503 | The next positions page cannot be served right now. Retry the same cursor shortly. |\n| `api_key_limit_reached` | 403 | The account already holds the maximum number of API keys for its plan. |\n| `wallet_requires_plan` | 402 | A wallet-authenticated key needs an active plan for this request. |\n| `wallet_account_required` | 403 | Wallet sign-in needs an existing account linked to the wallet. |\n| `wallet_free_signup_retired` | 410 | Free wallet sign-up is no longer offered. |\n| `account_disabled` | 403 | The account is disabled. |\n| `oauth_not_permitted` | 403 | This route is not available to OAuth access tokens. |\n| `insufficient_scope` | 403 | The OAuth access token lacks the scope this route requires. |\n\n**Legacy names.** Requests without `0xArchive-Version: 2026-10-01` keep the four names that predate the contract; with the header they receive the contract names instead.\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `invalid_query_params` | 400 | Legacy name of `invalid_parameter` (query parameter), or of `invalid_cursor` when the parameter is `cursor`, sent without the version header. |\n| `invalid_path_params` | 400 | Legacy name of `invalid_parameter` (path parameter), sent without the version header. |\n| `history_window_exceeded` | 403 | Legacy name of `historical_depth_exceeded`, sent without the version header. |\n| `request_range_exceeded` | 403 | Legacy name of `historical_range_exceeded`, sent without the version header. |\n\nTreat any value not listed here as a generic error of the HTTP status.", "type": "string", "enum": [ "invalid_parameter", "invalid_symbol", "invalid_interval", "invalid_cursor", "invalid_time_range", "range_before_coverage", "historical_range_exceeded", "historical_depth_exceeded", "unsupported_for_venue", "route_not_found", "not_found", "unauthorized", "forbidden", "insufficient_credits", "rate_limited", "conflict", "upstream_unavailable", "internal_error", "endpoint_unsupported", "slow_consumer", "positions_unavailable", "reconstruction_unavailable", "snapshot_advanced", "pagination_unavailable", "api_key_limit_reached", "wallet_requires_plan", "wallet_account_required", "wallet_free_signup_retired", "account_disabled", "oauth_not_permitted", "insufficient_scope", "invalid_query_params", "invalid_path_params", "history_window_exceeded", "request_range_exceeded" ], "example": "invalid_parameter" }, "max_concurrent": { "description": "`rate_limited` concurrency refusals only: simultaneous queries the plan allows.", "type": "integer" }, "param": { "description": "The parameter that failed validation, when one did.", "type": "string", "example": "side" }, "request_id": { "description": "Unique request ID for support.", "type": "string", "format": "uuid" }, "required_plans": { "description": "Plan refusals (`forbidden`) only: the plans that include the datatype.", "type": "array", "items": { "type": "string" }, "example": [ "build", "pro", "scale", "enterprise" ] }, "success": { "description": "Always `false` on an error.", "type": "boolean", "enum": [ false ] }, "suggestion": { "description": "Present when the symbol exists on another venue: where to request it instead.", "type": "object", "properties": { "endpoint": { "type": "string", "example": "/v1/hyperliquid/hip3/trades/xyz:TSLA" }, "symbol": { "type": "string", "example": "xyz:TSLA" }, "venue": { "type": "string", "example": "hip3" } } }, "upgrade_url": { "description": "Plan refusals (`forbidden`) only: where to change plan.", "type": "string", "format": "uri", "example": "https://0xarchive.io/pricing" }, "valid_values": { "description": "Accepted values of `param`, when the set is fixed.", "type": "array", "items": { "type": "string" }, "example": [ "buy", "sell" ] }, "venue": { "description": "`unsupported_for_venue` only: the venue the request asked.", "type": "string", "example": "spot" } } } ``` ##### OpenAPI example: `insufficient_credits` ```json theme={"theme":"github-dark"} { "success": false, "code": 429, "error_code": "insufficient_credits", "error": "Monthly credit limit exceeded. Please upgrade your plan.", "request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05", "credits_used": 50000, "credits_limit": 50000 } ``` ##### OpenAPI example: `rate_limited` ```json theme={"theme":"github-dark"} { "success": false, "code": 429, "error_code": "rate_limited", "error": "Rate limit exceeded", "request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05" } ``` ### Status default Any other error. The body is an `ErrorResponse`; branch on `error_code`. A 503 (`upstream_unavailable`) carries `Retry-After`. #### application/json ```json theme={"theme":"github-dark"} { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "getHip3Positioning response default", "description": "Body of every non-2xx JSON response. `code` repeats the HTTP status, `error_code` is the stable machine-readable code (see `ErrorCode`), `error` is a human-readable message, and `request_id` identifies the request for support. Validation failures add `param` and, where the accepted set is fixed, `valid_values`. A 404 for a datatype the venue does not offer (`unsupported_for_venue`) adds `venue`, `datatype` and `available_on`; any other unknown path answers 404 `route_not_found`.", "type": "object", "required": [ "code", "error", "error_code", "request_id", "success" ], "properties": { "available_on": { "description": "`unsupported_for_venue` only: the venues and routes that serve the datatype.", "type": "array", "items": { "type": "object", "required": [ "route", "venue" ], "properties": { "route": { "type": "string", "example": "/v1/hyperliquid/orders/{symbol}/flow" }, "venue": { "type": "string", "example": "hyperliquid" } } } }, "code": { "description": "HTTP status code.", "type": "integer", "example": 400 }, "credits_limit": { "description": "`insufficient_credits` only: the period's credit allowance.", "type": "integer", "format": "int64" }, "credits_used": { "description": "`insufficient_credits` only: credits used this period.", "type": "integer", "format": "int64" }, "datatype": { "description": "`unsupported_for_venue` and plan refusals (`forbidden`): the datatype the request asked for, as `GET /v1/capabilities` names it.", "type": "string", "example": "order_flow" }, "error": { "description": "Human-readable message. Wording can change; do not parse it.", "type": "string" }, "error_code": { "description": "Stable, machine-readable error code. Branch on this value, not on the `error` text.\n\n**Contract codes**\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `invalid_parameter` | 400 | A parameter failed to parse or validate. `param` names it and `valid_values` lists accepted values where the set is fixed. |\n| `invalid_symbol` | 400 | The symbol is not listed on this venue. |\n| `invalid_interval` | 400 | The `interval` (bucket width) is not one this route accepts. |\n| `invalid_cursor` | 400 | The `cursor` is malformed, stale, or was issued for other filters. Restart pagination without a cursor. Trades, liquidations, L2 and L4 diffs, order history and TP/SL routes currently return the first page for a malformed cursor instead. |\n| `invalid_time_range` | 400 | `start` is after `end`, or a time value could not be parsed. |\n| `range_before_coverage` | 400 | The whole requested range ends before the first instant this dataset is served from. |\n| `historical_range_exceeded` | 403 | The requested span is longer than the plan allows in one request or replay. |\n| `historical_depth_exceeded` | 403 | The request reaches further back than the plan's history window. |\n| `unsupported_for_venue` | 404 | The venue does not offer this datatype. The message, `datatype` and `available_on` name where it is served. |\n| `route_not_found` | 404 | No route matches the path or method. `GET /v1/capabilities` lists the routes each venue serves. |\n| `not_found` | 404 | The route exists but the requested resource (for example an incident, endpoint or outcome id) does not. |\n| `unauthorized` | 401 | The API key is missing or invalid. |\n| `forbidden` | 403 | The key is valid but not allowed to make this request, including a dataset its plan does not include: `datatype`, `required_plans` and `upgrade_url` name it. A refused request is not charged. |\n| `insufficient_credits` | 429 | The monthly credit allowance is spent (402 on pay-per-request routes). |\n| `rate_limited` | 429 | Too many requests or concurrent queries. Retry after the interval in the rate-limit headers. |\n| `conflict` | 409 | The request conflicts with the current state of the resource. |\n| `upstream_unavailable` | 503 | A dependency is unavailable or saturated. Retry shortly; the response carries `Retry-After`. |\n| `internal_error` | 500 | An unexpected server error. Quote `request_id` when contacting support. |\n\n**WebSocket only** (sent in `{\"type\":\"error\"}` messages, never by REST)\n\n| Code | Where | Meaning |\n|---|---|---|\n| `endpoint_unsupported` | WebSocket | This WebSocket endpoint does not serve the channel or operation. The message names the endpoint that does. |\n| `slow_consumer` | WebSocket | The connection fell behind a stream and messages were dropped. Re-subscribe, or restart the replay, to resynchronise. |\n\n**Route-specific codes**\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `positions_unavailable` | 503 | Account positions are temporarily unavailable for this venue. |\n| `reconstruction_unavailable` | 503 | The as-of positions state for this instant cannot be reconstructed right now. |\n| `snapshot_advanced` | 409 | A positions market cursor pinned a snapshot that has since been replaced or expired. Restart pagination. |\n| `pagination_unavailable` | 503 | The next positions page cannot be served right now. Retry the same cursor shortly. |\n| `api_key_limit_reached` | 403 | The account already holds the maximum number of API keys for its plan. |\n| `wallet_requires_plan` | 402 | A wallet-authenticated key needs an active plan for this request. |\n| `wallet_account_required` | 403 | Wallet sign-in needs an existing account linked to the wallet. |\n| `wallet_free_signup_retired` | 410 | Free wallet sign-up is no longer offered. |\n| `account_disabled` | 403 | The account is disabled. |\n| `oauth_not_permitted` | 403 | This route is not available to OAuth access tokens. |\n| `insufficient_scope` | 403 | The OAuth access token lacks the scope this route requires. |\n\n**Legacy names.** Requests without `0xArchive-Version: 2026-10-01` keep the four names that predate the contract; with the header they receive the contract names instead.\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `invalid_query_params` | 400 | Legacy name of `invalid_parameter` (query parameter), or of `invalid_cursor` when the parameter is `cursor`, sent without the version header. |\n| `invalid_path_params` | 400 | Legacy name of `invalid_parameter` (path parameter), sent without the version header. |\n| `history_window_exceeded` | 403 | Legacy name of `historical_depth_exceeded`, sent without the version header. |\n| `request_range_exceeded` | 403 | Legacy name of `historical_range_exceeded`, sent without the version header. |\n\nTreat any value not listed here as a generic error of the HTTP status.", "type": "string", "enum": [ "invalid_parameter", "invalid_symbol", "invalid_interval", "invalid_cursor", "invalid_time_range", "range_before_coverage", "historical_range_exceeded", "historical_depth_exceeded", "unsupported_for_venue", "route_not_found", "not_found", "unauthorized", "forbidden", "insufficient_credits", "rate_limited", "conflict", "upstream_unavailable", "internal_error", "endpoint_unsupported", "slow_consumer", "positions_unavailable", "reconstruction_unavailable", "snapshot_advanced", "pagination_unavailable", "api_key_limit_reached", "wallet_requires_plan", "wallet_account_required", "wallet_free_signup_retired", "account_disabled", "oauth_not_permitted", "insufficient_scope", "invalid_query_params", "invalid_path_params", "history_window_exceeded", "request_range_exceeded" ], "example": "invalid_parameter" }, "max_concurrent": { "description": "`rate_limited` concurrency refusals only: simultaneous queries the plan allows.", "type": "integer" }, "param": { "description": "The parameter that failed validation, when one did.", "type": "string", "example": "side" }, "request_id": { "description": "Unique request ID for support.", "type": "string", "format": "uuid" }, "required_plans": { "description": "Plan refusals (`forbidden`) only: the plans that include the datatype.", "type": "array", "items": { "type": "string" }, "example": [ "build", "pro", "scale", "enterprise" ] }, "success": { "description": "Always `false` on an error.", "type": "boolean", "enum": [ false ] }, "suggestion": { "description": "Present when the symbol exists on another venue: where to request it instead.", "type": "object", "properties": { "endpoint": { "type": "string", "example": "/v1/hyperliquid/hip3/trades/xyz:TSLA" }, "symbol": { "type": "string", "example": "xyz:TSLA" }, "venue": { "type": "string", "example": "hip3" } } }, "upgrade_url": { "description": "Plan refusals (`forbidden`) only: where to change plan.", "type": "string", "format": "uri", "example": "https://0xarchive.io/pricing" }, "valid_values": { "description": "Accepted values of `param`, when the set is fixed.", "type": "array", "items": { "type": "string" }, "example": [ "buy", "sell" ] }, "venue": { "description": "`unsupported_for_venue` only: the venue the request asked.", "type": "string", "example": "spot" } } } ``` ##### OpenAPI example: `internal_error` ```json theme={"theme":"github-dark"} { "success": false, "code": 500, "error_code": "internal_error", "error": "Internal server error", "request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05" } ``` ##### OpenAPI example: `upstream_unavailable` ```json theme={"theme":"github-dark"} { "success": false, "code": 503, "error_code": "upstream_unavailable", "error": "The service is temporarily unavailable. Retry shortly.", "request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05" } ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.