Get HIP-3 liquidation levels JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "getHip3LiquidationLevels path parameters",
  "type": "object",
  "required": [
    "symbol"
  ],
  "properties": {
    "symbol": {
      "description": "Trading pair symbol.",
      "type": "string",
      "example": "xyz:TSLA",
      "x-parameter-location": "path"
    }
  }
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "getHip3LiquidationLevels query parameters",
  "type": "object",
  "properties": {
    "range_pct": {
      "description": "Percentage range around the snapshot mid/mark price. Clamped between 1 and 50. Default 10.",
      "type": "number",
      "default": 10,
      "minimum": 1,
      "maximum": 50,
      "x-parameter-location": "query"
    },
    "buckets": {
      "description": "Number of price buckets. Clamped between 10 and 200. Default 50.",
      "type": "integer",
      "default": 50,
      "minimum": 10,
      "maximum": 200,
      "x-parameter-location": "query"
    },
    "side": {
      "description": "Optional side filter. bid/buy/B keeps the long (or bid) side, ask/sell/A keeps the short (or ask) side; the other side is zeroed.",
      "type": "string",
      "enum": [
        "bid",
        "ask",
        "buy",
        "sell",
        "B",
        "A"
      ],
      "x-parameter-location": "query"
    },
    "at": {
      "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"
    }
  }
}

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

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "getHip3LiquidationLevels response 200",
  "description": "API response containing projected forced-liquidation levels for one snapshot.",
  "type": "object",
  "properties": {
    "data": {
      "description": "Projected forced-liquidation levels computed from clearinghouse positions and margin state (positions plus maintenance-margin tiers), aggregated into price buckets around the snapshot mark price. Snapshots are computed roughly every 5 minutes; snapshot_ts identifies the snapshot served.",
      "type": "object",
      "required": [
        "block_number",
        "flagged_notional",
        "levels",
        "mid_price",
        "snapshot_ts",
        "source",
        "total_long",
        "total_short"
      ],
      "properties": {
        "block_number": {
          "description": "Hyperliquid block height the snapshot reflects.",
          "type": "integer",
          "format": "int64"
        },
        "flagged_notional": {
          "description": "Notional reported in totals but computed approximately or not assigned to a returned bucket. For HIP-3, cross-margined exposure is reported here and excluded from buckets.",
          "type": "number"
        },
        "levels": {
          "type": "array",
          "items": {
            "description": "One price bucket of projected forced-liquidation exposure.",
            "type": "object",
            "required": [
              "long_count",
              "long_notional",
              "price",
              "short_count",
              "short_notional"
            ],
            "properties": {
              "long_count": {
                "description": "Number of long positions in this bucket.",
                "type": "integer"
              },
              "long_notional": {
                "description": "USD notional of long positions projected to liquidate in this bucket.",
                "type": "number"
              },
              "price": {
                "description": "Bucket center price.",
                "type": "number"
              },
              "short_count": {
                "description": "Number of short positions in this bucket.",
                "type": "integer"
              },
              "short_notional": {
                "description": "USD notional of short positions projected to liquidate in this bucket.",
                "type": "number"
              }
            }
          }
        },
        "mid_price": {
          "description": "Mark price at the snapshot, center of the requested range.",
          "type": "number",
          "example": 64215
        },
        "snapshot_ts": {
          "description": "UTC snapshot time the levels reflect. Treat snapshots older than 2 hours as stale. By default a UTC string in `YYYY-MM-DD HH:MM:SS.mmm` form. With `0xArchive-Version: 2026-10-01` an RFC 3339 UTC string with millisecond precision, and `snapshot_ts_ms` carries the instant as Unix milliseconds.",
          "type": "string"
        },
        "snapshot_ts_ms": {
          "description": "With `0xArchive-Version: 2026-10-01` only: `snapshot_ts` as Unix milliseconds.",
          "type": "integer",
          "format": "int64",
          "example": 1767225600000
        },
        "source": {
          "description": "Snapshot storage form used to answer the request. raw means query-time bins over stored fine-grained levels; histogram means proportional re-binning of a retained base histogram.",
          "type": "string",
          "enum": [
            "raw",
            "histogram"
          ]
        },
        "source_bin_width": {
          "description": "Stored source-bin width in price units. Present only when source is histogram.",
          "type": "number"
        },
        "total_long": {
          "description": "Total long notional at risk across the whole book, not only the returned window.",
          "type": "number"
        },
        "total_short": {
          "description": "Total short notional at risk across the whole book.",
          "type": "number"
        }
      }
    },
    "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": {
        "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`).",
          "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
    }
  }
}

{
  "success": true,
  "data": {
    "mid_price": 322.86,
    "snapshot_ts": "2026-08-02 18:46:43.000",
    "block_number": 1095610000,
    "total_long": 9707806.14,
    "total_short": 13189198.41,
    "flagged_notional": 15254536.42,
    "levels": [
      {
        "price": 293.8026,
        "long_notional": 221368.31,
        "short_notional": 0,
        "long_count": 64,
        "short_count": 0
      },
      {
        "price": 300.2598,
        "long_notional": 120836.17,
        "short_notional": 0,
        "long_count": 35,
        "short_count": 0
      },
      {
        "price": 306.717,
        "long_notional": 6712.26,
        "short_notional": 0,
        "long_count": 15,
        "short_count": 0
      },
      {
        "price": 313.1742,
        "long_notional": 0,
        "short_notional": 48.75,
        "long_count": 0,
        "short_count": 1
      },
      {
        "price": 319.6314,
        "long_notional": 0,
        "short_notional": 327341.3,
        "long_count": 0,
        "short_count": 10
      },
      {
        "price": 326.0886,
        "long_notional": 0,
        "short_notional": 3690.61,
        "long_count": 0,
        "short_count": 4
      },
      {
        "price": 332.5458,
        "long_notional": 0,
        "short_notional": 59987.71,
        "long_count": 0,
        "short_count": 10
      },
      {
        "price": 339.003,
        "long_notional": 0,
        "short_notional": 55121.89,
        "long_count": 0,
        "short_count": 3
      },
      {
        "price": 345.4602,
        "long_notional": 0,
        "short_notional": 461.37,
        "long_count": 0,
        "short_count": 3
      },
      {
        "price": 351.9174,
        "long_notional": 0,
        "short_notional": 374.52,
        "long_count": 0,
        "short_count": 4
      }
    ],
    "source": "histogram",
    "source_bin_width": 1.6143
  },
  "meta": {
    "count": 10,
    "request_id": "d4e5f6a7-b8c9-4012-bcde-0123456789ab"
  }
}

{
  "success": true,
  "data": {
    "mid_price": 318.98,
    "snapshot_ts": "2026-08-06 13:20:14.000",
    "block_number": 1100170000,
    "total_long": 9439936.86,
    "total_short": 12457314.46,
    "flagged_notional": 15437186.38,
    "levels": [
      {
        "price": 316.1092,
        "long_notional": 2947.38,
        "short_notional": 0,
        "long_count": 4,
        "short_count": 0
      },
      {
        "price": 316.7471,
        "long_notional": 5528.56,
        "short_notional": 0,
        "long_count": 6,
        "short_count": 0
      },
      {
        "price": 317.3851,
        "long_notional": 0,
        "short_notional": 0,
        "long_count": 0,
        "short_count": 0
      },
      {
        "price": 318.0231,
        "long_notional": 2001.92,
        "short_notional": 0,
        "long_count": 4,
        "short_count": 0
      },
      {
        "price": 318.661,
        "long_notional": 0,
        "short_notional": 0,
        "long_count": 0,
        "short_count": 0
      },
      {
        "price": 319.299,
        "long_notional": 0,
        "short_notional": 0,
        "long_count": 0,
        "short_count": 0
      },
      {
        "price": 319.9369,
        "long_notional": 0,
        "short_notional": 0,
        "long_count": 0,
        "short_count": 0
      },
      {
        "price": 320.5749,
        "long_notional": 0,
        "short_notional": 0,
        "long_count": 0,
        "short_count": 0
      },
      {
        "price": 321.2129,
        "long_notional": 0,
        "short_notional": 0,
        "long_count": 0,
        "short_count": 0
      },
      {
        "price": 321.8508,
        "long_notional": 0,
        "short_notional": 0,
        "long_count": 0,
        "short_count": 0
      }
    ],
    "source": "raw"
  },
  "meta": {
    "count": 10,
    "request_id": "c3d4e5f6-a7b8-4901-abcd-f0123456789a"
  }
}

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

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

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

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

{
  "success": false,
  "code": 400,
  "error_code": "invalid_time_range",
  "error": "start must be <= end",
  "request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05"
}

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

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

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

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

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

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

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

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

{
  "success": false,
  "code": 429,
  "error_code": "rate_limited",
  "error": "Rate limit exceeded",
  "request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05"
}

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

{
  "success": false,
  "code": 500,
  "error_code": "internal_error",
  "error": "Internal server error",
  "request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05"
}

{
  "success": false,
  "code": 503,
  "error_code": "upstream_unavailable",
  "error": "The service is temporarily unavailable. Retry shortly.",
  "request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05"
}