activated, waitingForTrigger, finished, terminated, stopped, and error. Each event carries the TWAP size, executed size and notional, duration, and trigger settings. This route returns the events of one wallet on Hyperliquid perpetuals. History starts June 17, 2026 18:00 UTC. Events are ordered oldest first. Page with meta.next_cursor until meta.has_more is false. A page never ends partway through a millisecond, so it can hold fewer events than limit.
Route Metadata
| Field | Value |
|---|---|
| Method | GET |
| Path | /v1/hyperliquid/twap/user/{user} |
| operationId | getHyperliquidUserTwap |
| Tag | Hyperliquid - Orders |
| Family | Hyperliquid Core |
| Deprecated or legacy | no |
Human endpoint reference
OpenGET /v1/hyperliquid/twap/user/{user} for authentication, parameters, responses, and examples.
Request Parameters
Path Parameters
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "getHyperliquidUserTwap path parameters",
"type": "object",
"required": [
"user"
],
"properties": {
"user": {
"description": "Wallet address: 0x followed by 40 hex characters (case-insensitive).",
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$",
"example": "0x31ca8395cf837de08b24da3f660e77761dfb974b",
"x-parameter-location": "path"
}
}
}
Query Parameters
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "getHyperliquidUserTwap query parameters",
"type": "object",
"properties": {
"start": {
"description": "An instant: Unix milliseconds, or an RFC 3339 string such as `2026-01-01T00:00:00Z` (encode a `+` offset as `%2B`). An unparsable value answers 400 `invalid_time_range`.",
"oneOf": [
{
"description": "Unix milliseconds.",
"type": "integer",
"format": "int64",
"example": 1767225600000
},
{
"description": "RFC 3339 instant.",
"type": "string",
"format": "date-time",
"example": "2026-01-01T00:00:00Z"
}
],
"x-parameter-location": "query"
},
"end": {
"description": "An instant: Unix milliseconds, or an RFC 3339 string such as `2026-01-01T00:00:00Z` (encode a `+` offset as `%2B`). An unparsable value answers 400 `invalid_time_range`.",
"oneOf": [
{
"description": "Unix milliseconds.",
"type": "integer",
"format": "int64",
"example": 1767225600000
},
{
"description": "RFC 3339 instant.",
"type": "string",
"format": "date-time",
"example": "2026-01-01T00:00:00Z"
}
],
"x-parameter-location": "query"
},
"cursor": {
"description": "Value of `meta.next_cursor` from the previous page. The next page starts after it.",
"type": "string",
"x-parameter-location": "query"
},
"limit": {
"description": "Maximum number of events to return (default: 100, max: 1000; larger values are capped at 1000).",
"type": "integer",
"default": 100,
"minimum": 1,
"maximum": 1000,
"x-parameter-location": "query"
}
}
}
Header Parameters
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "getHyperliquidUserTwap 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
TWAP order status events for the walletapplication/json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "getHyperliquidUserTwap response 200",
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"description": "One TWAP order status event.",
"type": "object",
"required": [
"block_number",
"block_time",
"coin",
"executed_notional",
"executed_size",
"minutes",
"randomize",
"reduce_only",
"side",
"size",
"started_at",
"status",
"timestamp",
"twap_id",
"user_address"
],
"properties": {
"block_number": {
"description": "Hyperliquid block number.",
"type": "integer",
"format": "int64"
},
"block_time": {
"description": "Time of the block that carried the event (RFC 3339, UTC).",
"type": "string",
"format": "date-time"
},
"coin": {
"description": "Market symbol.",
"type": "string",
"example": "HYPE"
},
"executed_notional": {
"description": "Notional filled so far, in quote units.",
"type": "number"
},
"executed_size": {
"description": "Size filled so far, in base units.",
"type": "number"
},
"minutes": {
"description": "TWAP duration in minutes.",
"type": "integer"
},
"randomize": {
"description": "True when slice timing is randomized.",
"type": "boolean"
},
"reduce_only": {
"description": "True for a reduce-only TWAP.",
"type": "boolean"
},
"side": {
"description": "`B` (buy) or `A` (sell).",
"type": "string",
"enum": [
"B",
"A"
]
},
"size": {
"description": "Total TWAP size, in base units.",
"type": "number"
},
"started_at": {
"description": "When the TWAP started (RFC 3339, UTC).",
"type": "string",
"format": "date-time"
},
"status": {
"description": "`activated`, `waitingForTrigger`, `finished`, `terminated`, `stopped`, or `error`.",
"type": "string",
"example": "activated"
},
"stop_px": {
"description": "Price bound that ends the TWAP: the highest price for a buy, the lowest for a sell. Omitted when not set.",
"type": "number"
},
"timestamp": {
"description": "When the status event happened (RFC 3339, UTC).",
"type": "string",
"format": "date-time"
},
"trigger_above": {
"description": "True when the TWAP activates at or above `trigger_px`. Omitted for a TWAP without a trigger.",
"type": "boolean"
},
"trigger_px": {
"description": "Activation trigger price. Omitted for a TWAP without a trigger.",
"type": "number"
},
"twap_id": {
"description": "TWAP order ID. Every event of one TWAP carries the same ID.",
"type": "integer",
"format": "int64"
},
"user_address": {
"description": "Wallet that placed the TWAP, lowercase.",
"type": "string"
}
}
}
},
"meta": {
"description": "Deprecated name of `ResponseMeta`, kept so existing references resolve.",
"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"
}
},
"allOf": [
{
"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"
}
}
}
],
"deprecated": true
},
"success": {
"type": "boolean",
"example": true
}
}
}
Status 400
Invalid request: a parameter, symbol, interval, cursor or time range failed validation. Seeerror_code.
application/json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "getHyperliquidUserTwap 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`, a time value could not be parsed, or an order-book `timestamp` is outside the supported range. |\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
{
"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
{
"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
{
"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
{
"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
{
"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
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "getHyperliquidUserTwap 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`, a time value could not be parsed, or an order-book `timestamp` is outside the supported range. |\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
{
"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 request is outside the plan’s history window or per-request span, or the key is not allowed to make it.application/json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "getHyperliquidUserTwap 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`, a time value could not be parsed, or an order-book `timestamp` is outside the supported range. |\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: historical_depth_exceeded
{
"success": false,
"code": 403,
"error_code": "historical_depth_exceeded",
"error": "Your plan includes the most recent 30 days of history: this request starts at 2026-01-01T00:00:00Z, before the earliest allowed timestamp 2026-08-30T00:00:00Z. Requests cannot be chunked across the age boundary.",
"request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05"
}
OpenAPI example: historical_range_exceeded
{
"success": false,
"code": 403,
"error_code": "historical_range_exceeded",
"error": "Maximum range is 30 days per request on your plan. Requested range is 45 days.",
"request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05"
}
Status 429
Rate limit, concurrency limit or monthly credits exceeded. Seeerror_code.
application/json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "getHyperliquidUserTwap 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`, a time value could not be parsed, or an order-book `timestamp` is outside the supported range. |\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
{
"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
{
"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 anErrorResponse; branch on error_code. A 503 (upstream_unavailable) carries Retry-After.
application/json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "getHyperliquidUserTwap 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`, a time value could not be parsed, or an order-book `timestamp` is outside the supported range. |\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
{
"success": false,
"code": 500,
"error_code": "internal_error",
"error": "Internal server error",
"request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05"
}
OpenAPI example: upstream_unavailable
{
"success": false,
"code": 503,
"error_code": "upstream_unavailable",
"error": "The service is temporarily unavailable. Retry shortly.",
"request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05"
}