Get Hyperliquid positioning JSON Schema

Source OpenAPI: 0xArchive API 1.10.0; 240 paths; 241 component schemas. Get every listed Hyperliquid core perp 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 Hyperliquid core 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/positioning`
operationId	`getPositioning`
Tag	Hyperliquid - Positioning
Family	Hyperliquid Core
Deprecated or legacy	no

Human endpoint reference

Open GET /v1/hyperliquid/positioning for authentication, parameters, responses, and examples.

Implementation context

Positioning window and typical moves

Request Parameters

Query Parameters

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

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

application/json

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

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

{
  "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": "getPositioning 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

{
  "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

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

{
  "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

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

{
  "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 an ErrorResponse; branch on error_code. A 503 (upstream_unavailable) carries Retry-After.

application/json

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

{
  "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"
}

Endpoint reference

Requests and responses

Datasets

Venues

OpenAPI and schemas

Guides

Get Hyperliquid positioning JSON Schema

Route Metadata

Human endpoint reference

Implementation context

Request Parameters

Query Parameters

Header Parameters

Response Contracts

Status 200

application/json

Status 400

application/json

OpenAPI example: `current_main`

OpenAPI example: `invalid_parameter`

OpenAPI example: `invalid_symbol`

OpenAPI example: `invalid_time_range`

OpenAPI example: `legacy_invalid_query_params`

Status 401

application/json

OpenAPI example

Status 403

application/json

OpenAPI example: `forbidden`

Status 429

application/json

OpenAPI example: `insufficient_credits`

OpenAPI example: `rate_limited`

Status default

application/json

OpenAPI example: `internal_error`

OpenAPI example: `upstream_unavailable`

​Route Metadata

​Human endpoint reference

​Implementation context

​Request Parameters

​Query Parameters

​Header Parameters

​Response Contracts

​Status 200

​application/json

​Status 400

​application/json

OpenAPI example: current_main

OpenAPI example: invalid_parameter

OpenAPI example: invalid_symbol

OpenAPI example: invalid_time_range

OpenAPI example: legacy_invalid_query_params

​Status 401

​application/json

OpenAPI example

​Status 403

​application/json

OpenAPI example: forbidden

​Status 429

​application/json

OpenAPI example: insufficient_credits

OpenAPI example: rate_limited

​Status default

​application/json

OpenAPI example: internal_error

OpenAPI example: upstream_unavailable

Route Metadata

Human endpoint reference

Implementation context

Request Parameters

Query Parameters

Header Parameters

Response Contracts

Status 200

application/json

Status 400

application/json

OpenAPI example: `current_main`

OpenAPI example: `invalid_parameter`

OpenAPI example: `invalid_symbol`

OpenAPI example: `invalid_time_range`

OpenAPI example: `legacy_invalid_query_params`

Status 401

application/json

Status 403

application/json

OpenAPI example: `forbidden`

Status 429

application/json

OpenAPI example: `insufficient_credits`

OpenAPI example: `rate_limited`

Status default

application/json

OpenAPI example: `internal_error`

OpenAPI example: `upstream_unavailable`