{
  "openapi": "3.0.3",
  "info": {
    "title": "0xArchive API",
    "description": "Replayable market data API across Hyperliquid, Lighter.xyz, Hyperliquid HIP-3, and Hyperliquid HIP-4 (outcome markets). Use X-API-Key on market-data requests. Use /v1/auth/web3/challenge and /v1/web3/* when a script must start from a wallet. GET /health is the unauthenticated liveness check and /v1/data-quality/* covers coverage, incidents, latency, and SLA monitoring. Legacy /v1/* wrappers remain compatibility paths. Endpoint descriptions declare exact plan gates where they apply. Public docs and contract files live at /openapi.json, /llms.txt, /docs.md, and /docs/ai-clients.md.",
    "version": "1.5.0",
    "termsOfService": "https://www.0xarchive.io/terms/",
    "contact": {
      "name": "0xArchive Support",
      "url": "https://www.0xarchive.io",
      "email": "support@0xarchive.io"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://www.0xarchive.io/terms/"
    }
  },
  "externalDocs": {
    "description": "Public docs home plus markdown pages for fast reading in Claude, ChatGPT, or your own tools",
    "url": "https://www.0xarchive.io/docs/"
  },
  "servers": [
    {
      "url": "https://api.0xarchive.io",
      "description": "Production API"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "System",
      "description": "Health checks and system status"
    },
    {
      "name": "Hyperliquid - Instruments",
      "description": "Hyperliquid available trading instruments and their specifications. 220+ perpetual futures markets."
    },
    {
      "name": "Hyperliquid - Order Book",
      "description": "Hyperliquid high-frequency L2 order book snapshots. Snapshot spacing varies by market activity and query window. Data from April 2023."
    },
    {
      "name": "Hyperliquid - Trades",
      "description": "Hyperliquid historical trade/fill data with full execution details. Data from April 2023."
    },
    {
      "name": "Hyperliquid - Candles",
      "description": "Hyperliquid OHLCV candle data. Intervals: 1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w."
    },
    {
      "name": "Hyperliquid - Open Interest",
      "description": "Hyperliquid historical open interest and market context data. Data from May 2023."
    },
    {
      "name": "Hyperliquid - Funding",
      "description": "Hyperliquid funding rate history. Data from May 2023."
    },
    {
      "name": "Hyperliquid - Liquidations",
      "description": "Hyperliquid liquidation events with user attribution. Data from December 2025."
    },
    {
      "name": "Hyperliquid - L4 Order Book",
      "description": "Individual order-level (L4) orderbook data for Hyperliquid perpetuals. Includes user attribution and order lifecycle events."
    },
    {
      "name": "Hyperliquid - Orders",
      "description": "Order lifecycle events for Hyperliquid perpetuals: placements, cancellations, fills, and TP/SL triggers."
    },
    {
      "name": "Hyperliquid - Convenience",
      "description": "Hyperliquid convenience endpoints: freshness, summary, and price history."
    },
    {
      "name": "HIP-3 Builder Perps - Instruments",
      "description": "HIP-3 Builder Perps instrument discovery. 125+ markets across 6 builders: xyz (XYZ), flx (Felix Exchange), hyna (HyENA), km (Kinetiq Markets), vntl (Ventuals), cash (dreamcash)."
    },
    {
      "name": "HIP-3 Builder Perps - Order Book",
      "description": "HIP-3 Builder Perps L2 order book snapshots. Data from February 2026."
    },
    {
      "name": "HIP-3 Builder Perps - Trades",
      "description": "HIP-3 Builder Perps historical trade/fill data. Data from February 2026. Free tier: km:US500 only."
    },
    {
      "name": "HIP-3 Builder Perps - Candles",
      "description": "HIP-3 Builder Perps OHLCV candle data. Intervals: 1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w. Data from February 2026."
    },
    {
      "name": "HIP-3 Builder Perps - Open Interest",
      "description": "HIP-3 Builder Perps historical open interest data. Data from February 2026."
    },
    {
      "name": "HIP-3 Builder Perps - Funding",
      "description": "HIP-3 Builder Perps funding rate history. Data from February 2026."
    },
    {
      "name": "HIP-3 Builder Perps - Liquidations",
      "description": "HIP-3 Builder Perps liquidation-related fills. Data from February 2026."
    },
    {
      "name": "HIP-3 Builder Perps - L4 Order Book",
      "description": "Individual order-level (L4) orderbook data for HIP-3 builder perps."
    },
    {
      "name": "HIP-3 Builder Perps - Orders",
      "description": "Order lifecycle events for HIP-3 builder perps."
    },
    {
      "name": "HIP-3 Builder Perps - Convenience",
      "description": "HIP-3 convenience endpoints: freshness, summary, and price history."
    },
    {
      "name": "HIP-4 Outcomes - Outcomes",
      "description": "HIP-4 outcome market discovery (one row per outcome, both sides combined). Use these to enumerate live and settled binary outcome markets. Data from May 2026."
    },
    {
      "name": "HIP-4 Outcomes - Instruments",
      "description": "HIP-4 per-side instrument discovery (one row per `#N` coin). Each outcome has two sides: side 0 (Yes) and side 1 (No). Coins are `#`-prefixed. Data from May 2026."
    },
    {
      "name": "HIP-4 Outcomes - Order Book",
      "description": "HIP-4 outcome markets L2 and L4 order book snapshots and diffs. Coins are referenced by numeric id (0, 1, 10, 11, ...); the `#`-prefixed form is also accepted. Data from May 2026."
    },
    {
      "name": "HIP-4 Outcomes - Trades",
      "description": "HIP-4 outcome markets historical trade/fill data. Data from May 2026."
    },
    {
      "name": "HIP-4 Outcomes - Open Interest",
      "description": "HIP-4 outcome markets per-side open interest history. Display/paired/parity aggregates live on the `/outcomes/{outcome_id}` detail endpoint, not here. Data from May 2026."
    },
    {
      "name": "HIP-4 Outcomes - Orders",
      "description": "Order lifecycle events for HIP-4 outcome markets: placements, cancellations, fills, and TP/SL triggers."
    },
    {
      "name": "HIP-4 Outcomes - Convenience",
      "description": "HIP-4 convenience endpoints: freshness, summary, and price history. `mark_price` for HIP-4 is an implied probability in [0,1], not a USD price."
    },
    {
      "name": "Lighter - Instruments",
      "description": "Lighter.xyz available trading instruments and their specifications."
    },
    {
      "name": "Lighter - Order Book",
      "description": "Lighter.xyz L2 order book snapshots with configurable granularity. Checkpoint history starts January 29, 2026; 30s/10s/1s start January 30, 2026; tick reconstruction is Enterprise-only."
    },
    {
      "name": "Lighter - Trades",
      "description": "Lighter.xyz historical trade/fill data. Data from August 2025."
    },
    {
      "name": "Lighter - Candles",
      "description": "Lighter.xyz OHLCV candle data. Intervals: 1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w. Data from August 2025."
    },
    {
      "name": "Lighter - Open Interest",
      "description": "Lighter.xyz historical open interest data. Data from August 2025."
    },
    {
      "name": "Lighter - Funding",
      "description": "Lighter.xyz funding rate history. Data from August 2025."
    },
    {
      "name": "Lighter - L3 Order Book",
      "description": "Individual order-level (L3) orderbook data for Lighter.xyz. Data from March 2026."
    },
    {
      "name": "Lighter - Convenience",
      "description": "Lighter.xyz convenience endpoints: freshness, summary, and price history."
    },
    {
      "name": "Data Quality",
      "description": "Data quality monitoring: system status, coverage, incidents, latency, and SLA metrics."
    },
    {
      "name": "Web3 Authentication",
      "description": "Wallet-based authentication via SIWE (Sign-In with Ethereum). Get API keys programmatically without a browser."
    },
    {
      "name": "Legacy",
      "description": "Deprecated endpoints that default to Hyperliquid. Use the exchange-specific endpoints (`/v1/hyperliquid/*`, `/v1/lighter/*`, `/v1/hyperliquid/hip3/*`) instead."
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "tags": [
          "System"
        ],
        "summary": "Health check",
        "description": "Check API health status. No authentication required.",
        "operationId": "healthCheck",
        "security": [],
        "responses": {
          "200": {
            "description": "API is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "ok"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/orderbook/{symbol}": {
      "get": {
        "tags": [
          "Legacy"
        ],
        "summary": "Get order book (Deprecated)",
        "description": "**Deprecated:** Use `/v1/hyperliquid/orderbook/{symbol}` or `/v1/lighter/orderbook/{symbol}` instead.\n\nGet the latest order book snapshot for a coin, or at a specific timestamp. Returns L2 depth with price, size, and order count at each level.",
        "operationId": "getOrderbook",
        "deprecated": true,
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "Trading pair symbol (e.g., BTC, ETH, SOL)",
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "example": "BTC"
          },
          {
            "name": "timestamp",
            "in": "query",
            "description": "Unix timestamp in milliseconds. If not provided, returns latest snapshot.",
            "schema": {
              "type": "integer",
              "format": "int64",
              "example": 1704067200000
            }
          },
          {
            "name": "depth",
            "in": "query",
            "description": "Number of price levels per side. Tier limits: Free=20, Build=200, Pro=Full Depth, Enterprise=Full Depth",
            "schema": {
              "type": "integer",
              "example": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Order book snapshot",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseOrderBook"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/orderbook/{symbol}/history": {
      "get": {
        "tags": [
          "Legacy"
        ],
        "summary": "Get order book history (Deprecated)",
        "description": "**Deprecated:** Use `/v1/hyperliquid/orderbook/{symbol}/history` or `/v1/lighter/orderbook/{symbol}/history` instead.\n\nGet historical order book snapshots within a time range. Snapshot spacing varies by market activity and query window.",
        "operationId": "getOrderbookHistory",
        "deprecated": true,
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "description": "Trading pair symbol (e.g., BTC, ETH, SOL)",
            "example": "BTC"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp in Unix milliseconds. Defaults to 24h ago.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp in Unix milliseconds. Defaults to now.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination (timestamp from previous response's `next_cursor`). If not provided, starts from the beginning of the range.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 100, max: 1000)",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 1000
            }
          },
          {
            "name": "depth",
            "in": "query",
            "description": "Number of price levels per side. Tier limits: Free=20, Build=200, Pro=Full Depth, Enterprise=Full Depth",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of order book snapshots",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseOrderBookArray"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/trades/{symbol}": {
      "get": {
        "tags": [
          "Legacy"
        ],
        "summary": "Get trades (Deprecated)",
        "description": "**Deprecated:** Use `/v1/hyperliquid/trades/{symbol}` or `/v1/lighter/trades/{symbol}` instead.\n\nGet historical trades (fills) for a coin within a time range. Includes full execution details like fees, PnL, and position direction.\n\n**Pagination:** Use the `cursor` parameter with the timestamp from the previous response's `next_cursor` for efficient pagination through large datasets.",
        "operationId": "getTrades",
        "deprecated": true,
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "description": "Trading pair symbol (e.g., BTC, ETH, SOL)",
            "example": "BTC"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp in Unix milliseconds. Defaults to 24h ago.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp in Unix milliseconds. Defaults to now.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "**Recommended.** Cursor for pagination (use the value from previous response's `next_cursor`). The cursor is an opaque string that should be passed as-is.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 100, max: 1000)",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 1000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of trades with cursor for next page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseTradeArray"
                },
                "example": {
                  "success": true,
                  "data": [],
                  "meta": {
                    "count": 100,
                    "next_cursor": "1704067200123_456789",
                    "request_id": "550e8400-e29b-41d4-a716-446655440000"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/trades/{symbol}/cursor": {
      "get": {
        "tags": [
          "Legacy"
        ],
        "summary": "Get trades with cursor pagination (Deprecated)",
        "description": "**Deprecated:** Use `/v1/hyperliquid/trades/{symbol}` or `/v1/lighter/trades/{symbol}` instead.\n\nGet historical trades using cursor-based pagination. This is the same as `/v1/trades/{symbol}` with cursor pagination (which is now the default). This endpoint is maintained for backwards compatibility and explicit cursor-only usage.",
        "operationId": "getTradesCursor",
        "deprecated": true,
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "description": "Trading pair symbol (e.g., BTC, ETH, SOL)",
            "example": "BTC"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp in Unix milliseconds. Defaults to 24h ago.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp in Unix milliseconds. Defaults to now.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination (use the value from previous response's `next_cursor`). The cursor is an opaque string that should be passed as-is.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 100, max: 1000)",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 1000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of trades with cursor for next page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseTradeArray"
                },
                "example": {
                  "success": true,
                  "data": [],
                  "meta": {
                    "count": 100,
                    "next_cursor": "1704067200123_456789",
                    "request_id": "550e8400-e29b-41d4-a716-446655440000"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/instruments": {
      "get": {
        "tags": [
          "Legacy"
        ],
        "summary": "List instruments (Deprecated)",
        "description": "**Deprecated:** Use `/v1/hyperliquid/instruments` or `/v1/lighter/instruments` instead.\n\nGet all available trading instruments with their specifications.",
        "operationId": "listInstruments",
        "deprecated": true,
        "responses": {
          "200": {
            "description": "List of instruments",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseInstrumentArray"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/instruments/{symbol}": {
      "get": {
        "tags": [
          "Legacy"
        ],
        "summary": "Get instrument (Deprecated)",
        "description": "**Deprecated:** Use `/v1/hyperliquid/instruments/{symbol}` or `/v1/lighter/instruments/{symbol}` instead.\n\nGet details for a specific trading instrument.",
        "operationId": "getInstrument",
        "deprecated": true,
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "description": "Trading pair symbol (e.g., BTC, ETH, SOL)",
            "example": "BTC"
          }
        ],
        "responses": {
          "200": {
            "description": "Instrument details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseInstrument"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/openinterest/{symbol}": {
      "get": {
        "tags": [
          "Legacy"
        ],
        "summary": "Get open interest history (Deprecated)",
        "description": "**Deprecated:** Use `/v1/hyperliquid/openinterest/{symbol}` or `/v1/lighter/openinterest/{symbol}` instead.\n\nGet historical open interest data with associated market context (mark price, oracle price, volume, etc.).",
        "operationId": "getOpenInterest",
        "deprecated": true,
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "description": "Trading pair symbol (e.g., BTC, ETH, SOL)",
            "example": "BTC"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp in Unix milliseconds. Defaults to 24h ago.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp in Unix milliseconds. Defaults to now.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination (timestamp from previous response's `next_cursor`). If not provided, starts from the beginning of the range.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 100, max: 1000)",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 1000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Open interest data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseOpenInterestArray"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/openinterest/{symbol}/current": {
      "get": {
        "tags": [
          "Legacy"
        ],
        "summary": "Get current open interest (Deprecated)",
        "description": "**Deprecated:** Use `/v1/hyperliquid/openinterest/{symbol}/current` or `/v1/lighter/openinterest/{symbol}/current` instead.\n\nGet the latest open interest value and market context.",
        "operationId": "getCurrentOpenInterest",
        "deprecated": true,
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "description": "Trading pair symbol (e.g., BTC, ETH, SOL)",
            "example": "BTC"
          }
        ],
        "responses": {
          "200": {
            "description": "Current open interest",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseOpenInterest"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/funding/{symbol}": {
      "get": {
        "tags": [
          "Legacy"
        ],
        "summary": "Get funding rate history (Deprecated)",
        "description": "**Deprecated:** Use `/v1/hyperliquid/funding/{symbol}` or `/v1/lighter/funding/{symbol}` instead.\n\nGet historical funding rates. Funding is settled every 8 hours on Hyperliquid.",
        "operationId": "getFundingHistory",
        "deprecated": true,
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "description": "Trading pair symbol (e.g., BTC, ETH, SOL)",
            "example": "BTC"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp in Unix milliseconds. Defaults to 24h ago.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp in Unix milliseconds. Defaults to now.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination (timestamp from previous response's `next_cursor`). If not provided, starts from the beginning of the range.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 100, max: 1000)",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 1000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Funding rate history",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseFundingRateArray"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/funding/{symbol}/current": {
      "get": {
        "tags": [
          "Legacy"
        ],
        "summary": "Get current funding rate (Deprecated)",
        "description": "**Deprecated:** Use `/v1/hyperliquid/funding/{symbol}/current` or `/v1/lighter/funding/{symbol}/current` instead.\n\nGet the latest funding rate for a coin.",
        "operationId": "getCurrentFunding",
        "deprecated": true,
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "description": "Trading pair symbol (e.g., BTC, ETH, SOL)",
            "example": "BTC"
          }
        ],
        "responses": {
          "200": {
            "description": "Current funding rate",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseFundingRate"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/instruments": {
      "get": {
        "tags": [
          "Hyperliquid - Instruments"
        ],
        "summary": "List Hyperliquid instruments",
        "description": "Get all available Hyperliquid trading instruments with their specifications.",
        "operationId": "listHyperliquidInstruments",
        "responses": {
          "200": {
            "description": "List of instruments",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseInstrumentArray"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/instruments/{symbol}": {
      "get": {
        "tags": [
          "Hyperliquid - Instruments"
        ],
        "summary": "Get Hyperliquid instrument",
        "description": "Get details for a specific Hyperliquid trading instrument.",
        "operationId": "getHyperliquidInstrument",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "description": "Trading pair symbol (e.g., BTC, ETH, SOL)",
            "example": "BTC"
          }
        ],
        "responses": {
          "200": {
            "description": "Instrument details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseInstrument"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/orderbook/{symbol}": {
      "get": {
        "tags": [
          "Hyperliquid - Order Book"
        ],
        "summary": "Get Hyperliquid order book",
        "description": "Get the latest order book snapshot for a coin, or at a specific timestamp. Returns L2 depth with price, size, and order count at each level. Snapshot spacing varies by market activity and query window.",
        "operationId": "getHyperliquidOrderbook",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "Trading pair symbol (e.g., BTC, ETH, SOL)",
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "example": "BTC"
          },
          {
            "name": "timestamp",
            "in": "query",
            "description": "Unix timestamp in milliseconds. If not provided, returns latest snapshot.",
            "schema": {
              "type": "integer",
              "format": "int64",
              "example": 1704067200000
            }
          },
          {
            "name": "depth",
            "in": "query",
            "description": "Number of price levels per side. Tier limits: Free=20, Build=200, Pro=Full Depth, Enterprise=Full Depth",
            "schema": {
              "type": "integer",
              "example": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Order book snapshot",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseOrderBook"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/orderbook/{symbol}/history": {
      "get": {
        "tags": [
          "Hyperliquid - Order Book"
        ],
        "summary": "Get Hyperliquid order book history",
        "description": "Get historical order book snapshots within a time range. Snapshot spacing varies by market activity and query window. Data available from April 2023.",
        "operationId": "getHyperliquidOrderbookHistory",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "description": "Trading pair symbol (e.g., BTC, ETH, SOL)",
            "example": "BTC"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp in Unix milliseconds. Defaults to 24h ago.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp in Unix milliseconds. Defaults to now.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination (timestamp from previous response's `next_cursor`)",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 100, max: 1000)",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 1000
            }
          },
          {
            "name": "depth",
            "in": "query",
            "description": "Number of price levels per side. Tier limits: Free=20, Build=200, Pro=Full Depth, Enterprise=Full Depth",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of order book snapshots",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseOrderBookArray"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/trades/{symbol}": {
      "get": {
        "tags": [
          "Hyperliquid - Trades"
        ],
        "summary": "Get Hyperliquid trades",
        "description": "Get historical trades (fills) for a coin within a time range. Includes full execution details like fees, PnL, and position direction. Data available from April 2023 (pre-March 2025 fills are taker-only).\n\n**Pagination:** Use the `cursor` parameter with the value from the previous response's `next_cursor` for efficient pagination.",
        "operationId": "getHyperliquidTrades",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "description": "Trading pair symbol (e.g., BTC, ETH, SOL)",
            "example": "BTC"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp in Unix milliseconds. Defaults to 24h ago.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp in Unix milliseconds. Defaults to now.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination (use the value from previous response's `next_cursor`)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 100, max: 1000)",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 1000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of trades with cursor for next page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseTradeArray"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/candles/{symbol}": {
      "get": {
        "tags": [
          "Hyperliquid - Candles"
        ],
        "summary": "Get Hyperliquid OHLCV candles",
        "description": "Get historical OHLCV candle data. Data available from March 2025.\n\n**Available Intervals:** 1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w\n\n**Pagination:** Use the `cursor` parameter with the value from the previous response's `next_cursor` for efficient pagination.",
        "operationId": "getHyperliquidCandles",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "description": "Trading pair symbol (e.g., BTC, ETH, SOL)",
            "example": "BTC"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp in Unix milliseconds. Defaults to 24h ago.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp in Unix milliseconds. Defaults to now.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "interval",
            "in": "query",
            "description": "Candle interval (default: 1h)",
            "schema": {
              "type": "string",
              "enum": [
                "1m",
                "5m",
                "15m",
                "30m",
                "1h",
                "4h",
                "1d",
                "1w"
              ],
              "default": "1h"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination (use the value from previous response's `next_cursor`)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 100, max: 10000)",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 10000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of OHLCV candles with cursor for next page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseCandleArray"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/openinterest/{symbol}": {
      "get": {
        "tags": [
          "Hyperliquid - Open Interest"
        ],
        "summary": "Get Hyperliquid open interest history",
        "description": "Get historical open interest data with associated market context (mark price, oracle price, volume, etc.). Data available from May 2023.",
        "operationId": "getHyperliquidOpenInterest",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "description": "Trading pair symbol (e.g., BTC, ETH, SOL)",
            "example": "BTC"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp in Unix milliseconds. Defaults to 24h ago.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp in Unix milliseconds. Defaults to now.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 100, max: 1000)",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 1000
            }
          },
          {
            "name": "interval",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "5m",
                "15m",
                "30m",
                "1h",
                "4h",
                "1d"
              ]
            },
            "description": "Aggregation interval. When omitted, returns raw ~1 min resolution data."
          }
        ],
        "responses": {
          "200": {
            "description": "Open interest data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseOpenInterestArray"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/openinterest/{symbol}/current": {
      "get": {
        "tags": [
          "Hyperliquid - Open Interest"
        ],
        "summary": "Get current Hyperliquid open interest",
        "description": "Get the latest open interest value and market context.",
        "operationId": "getCurrentHyperliquidOpenInterest",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "description": "Trading pair symbol (e.g., BTC, ETH, SOL)",
            "example": "BTC"
          }
        ],
        "responses": {
          "200": {
            "description": "Current open interest",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseOpenInterest"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/funding/{symbol}": {
      "get": {
        "tags": [
          "Hyperliquid - Funding"
        ],
        "summary": "Get Hyperliquid funding rate history",
        "description": "Get historical funding rates. Funding is settled every 8 hours on Hyperliquid. Data available from May 2023.",
        "operationId": "getHyperliquidFundingHistory",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "description": "Trading pair symbol (e.g., BTC, ETH, SOL)",
            "example": "BTC"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp in Unix milliseconds. Defaults to 24h ago.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp in Unix milliseconds. Defaults to now.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 100, max: 1000)",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 1000
            }
          },
          {
            "name": "interval",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "5m",
                "15m",
                "30m",
                "1h",
                "4h",
                "1d"
              ]
            },
            "description": "Aggregation interval. When omitted, returns raw ~1 min resolution data."
          }
        ],
        "responses": {
          "200": {
            "description": "Funding rate history",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseFundingRateArray"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/funding/{symbol}/current": {
      "get": {
        "tags": [
          "Hyperliquid - Funding"
        ],
        "summary": "Get current Hyperliquid funding rate",
        "description": "Get the latest funding rate for a coin.",
        "operationId": "getCurrentHyperliquidFunding",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "description": "Trading pair symbol (e.g., BTC, ETH, SOL)",
            "example": "BTC"
          }
        ],
        "responses": {
          "200": {
            "description": "Current funding rate",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseFundingRate"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/liquidations/{symbol}": {
      "get": {
        "tags": [
          "Hyperliquid - Liquidations"
        ],
        "summary": "Get Hyperliquid liquidation events",
        "description": "Get historical liquidation events for a coin. Data available from December 2025.",
        "operationId": "getHyperliquidLiquidations",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "Trading pair symbol (e.g., BTC, ETH)",
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "example": "BTC"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp in Unix milliseconds. Defaults to 24h ago.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp in Unix milliseconds. Defaults to now.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination (format: timestamp_tradeId)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 100, max: 1000)",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 1000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Liquidation events",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseLiquidationArray"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/liquidations/user/{user}": {
      "get": {
        "tags": [
          "Hyperliquid - Liquidations"
        ],
        "summary": "Get liquidations by user address",
        "description": "Get historical liquidation events for a specific user address. Returns liquidations where the user was the liquidated party. Data available from December 2025.",
        "operationId": "getHyperliquidLiquidationsByUser",
        "parameters": [
          {
            "name": "user",
            "in": "path",
            "required": true,
            "description": "User wallet address (e.g., 0x...)",
            "schema": {
              "type": "string",
              "example": "0x84eec0068b37919cc8f13d7454073ac167374cc0"
            }
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp in Unix milliseconds. Defaults to 24h ago.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp in Unix milliseconds. Defaults to now.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "symbol",
            "in": "query",
            "description": "Optional symbol filter (e.g., BTC, ETH)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination (timestamp in milliseconds)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 100, max: 1000)",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 1000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "User liquidation events",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseLiquidationArray"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/liquidations/{symbol}/volume": {
      "get": {
        "tags": [
          "Hyperliquid - Convenience"
        ],
        "summary": "Get aggregated liquidation volume",
        "description": "Get pre-aggregated liquidation volumes in time-bucketed intervals. Returns total, long, and short USD volumes with counts.",
        "operationId": "getHyperliquidLiquidationVolume",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "Coin symbol (e.g., BTC, ETH, SOL)",
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "example": "BTC"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp in milliseconds",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp in milliseconds",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "interval",
            "in": "query",
            "description": "Aggregation interval",
            "schema": {
              "type": "string",
              "enum": [
                "5m",
                "15m",
                "30m",
                "1h",
                "4h",
                "1d"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 100, max: 1000)",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 1000
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Aggregated liquidation volume data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseLiquidationVolumeArray"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/freshness/{symbol}": {
      "get": {
        "tags": [
          "Hyperliquid - Convenience"
        ],
        "summary": "Get data freshness",
        "description": "Check when data was last updated for each data type for a specific coin.",
        "operationId": "getHyperliquidFreshness",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "Coin symbol (e.g., BTC, ETH, SOL)",
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "example": "BTC"
          }
        ],
        "responses": {
          "200": {
            "description": "Data freshness for the coin",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseCoinFreshness"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/summary/{symbol}": {
      "get": {
        "tags": [
          "Hyperliquid - Convenience"
        ],
        "summary": "Get market summary",
        "description": "Get a combined market summary including price, funding, OI, volume, and liquidation data in a single call.",
        "operationId": "getHyperliquidSummary",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "Coin symbol (e.g., BTC, ETH, SOL)",
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "example": "BTC"
          }
        ],
        "responses": {
          "200": {
            "description": "Market summary for the coin",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseCoinSummary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/prices/{symbol}": {
      "get": {
        "tags": [
          "Hyperliquid - Convenience"
        ],
        "summary": "Get price history",
        "description": "Get mark/oracle price history. Lightweight projection of open interest data returning only price fields.",
        "operationId": "getHyperliquidPriceHistory",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "Coin symbol (e.g., BTC, ETH, SOL)",
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "example": "BTC"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp in milliseconds",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp in milliseconds",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "interval",
            "in": "query",
            "description": "Aggregation interval",
            "schema": {
              "type": "string",
              "enum": [
                "5m",
                "15m",
                "30m",
                "1h",
                "4h",
                "1d"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 100, max: 1000)",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 1000
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Price history data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponsePriceSnapshotArray"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/lighter/instruments": {
      "get": {
        "tags": [
          "Lighter - Instruments"
        ],
        "summary": "List Lighter instruments",
        "description": "Get all available Lighter.xyz trading instruments with their specifications. Returns `LighterInstrument` objects which include fees, market IDs, and minimum order amounts.",
        "operationId": "listLighterInstruments",
        "responses": {
          "200": {
            "description": "List of Lighter instruments",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseLighterInstrumentArray"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/lighter/instruments/{symbol}": {
      "get": {
        "tags": [
          "Lighter - Instruments"
        ],
        "summary": "Get Lighter instrument",
        "description": "Get details for a specific Lighter.xyz trading instrument. Returns a `LighterInstrument` object which includes fees, market ID, and minimum order amounts.",
        "operationId": "getLighterInstrument",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "ETH"
            },
            "description": "Trading pair symbol (e.g., ETH, BTC)",
            "example": "ETH"
          }
        ],
        "responses": {
          "200": {
            "description": "Lighter instrument details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseLighterInstrument"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/lighter/orderbook/{symbol}": {
      "get": {
        "tags": [
          "Lighter - Order Book"
        ],
        "summary": "Get Lighter order book",
        "description": "Get the latest order book snapshot for a coin, or at a specific timestamp. Returns L2 depth with price, size, and order count at each level. Tick-level resolution.",
        "operationId": "getLighterOrderbook",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "Trading pair symbol (e.g., BTC, ETH)",
            "schema": {
              "type": "string",
              "example": "ETH"
            },
            "example": "ETH"
          },
          {
            "name": "timestamp",
            "in": "query",
            "description": "Unix timestamp in milliseconds. If not provided, returns latest snapshot.",
            "schema": {
              "type": "integer",
              "format": "int64",
              "example": 1704067200000
            }
          },
          {
            "name": "depth",
            "in": "query",
            "description": "Number of price levels per side. Tier limits: Free=20, Build=200, Pro=Full Depth, Enterprise=Full Depth",
            "schema": {
              "type": "integer",
              "example": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Order book snapshot",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseOrderBook"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/lighter/orderbook/{symbol}/history": {
      "get": {
        "tags": [
          "Lighter - Order Book"
        ],
        "summary": "Get Lighter order book history",
        "description": "Get historical order book snapshots within a time range with configurable resolution. Checkpoint history starts January 29, 2026; 30s/10s/1s start January 30, 2026. Use 'granularity' parameter to control data resolution (tier restrictions apply).\n\n**Tick-Level Data (Enterprise tier only):**\nWhen `granularity=tick`, the response format changes. Instead of returning snapshots in the `data` array, it returns:\n- `checkpoint`: Full orderbook state at the start of the time range\n- `deltas`: Array of incremental changes to apply to the checkpoint\n\nThis is the most efficient format for reconstructing high-frequency orderbook states. Use the SDK's `OrderBookReconstructor` class for client-side reconstruction.",
        "operationId": "getLighterOrderbookHistory",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "ETH"
            },
            "description": "Trading pair symbol (e.g., ETH, BTC)",
            "example": "ETH"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp in Unix milliseconds. Defaults to 24h ago.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp in Unix milliseconds. Defaults to now.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 100, max: 1000)",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 1000
            }
          },
          {
            "name": "depth",
            "in": "query",
            "description": "Number of price levels per side. Tier limits: Free=20, Build=200, Pro=Full Depth, Enterprise=Full Depth",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "granularity",
            "in": "query",
            "description": "Data resolution: checkpoint (1min, default), 30s, 10s, 1s, tick. Checkpoint history starts January 29, 2026; 30s/10s/1s start January 30, 2026. Higher resolutions require higher tier plans. Credit multiplier: checkpoint=1x, 30s=2x, 10s=3x, 1s=10x, tick=20x. **Note:** When granularity=tick (Enterprise tier only), the response format changes to return `checkpoint` and `deltas` instead of a `data` array.",
            "schema": {
              "type": "string",
              "enum": [
                "checkpoint",
                "30s",
                "10s",
                "1s",
                "tick"
              ],
              "default": "checkpoint"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of order book snapshots",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseOrderBookArray"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/lighter/trades/{symbol}": {
      "get": {
        "tags": [
          "Lighter - Trades"
        ],
        "summary": "Get Lighter trades",
        "description": "Get historical trades (fills) for a coin within a time range. Data available from August 2025.\n\n**Pagination:** Use the `cursor` parameter with the value from the previous response's `next_cursor` for efficient pagination.",
        "operationId": "getLighterTrades",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "ETH"
            },
            "description": "Trading pair symbol (e.g., ETH, BTC)",
            "example": "ETH"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp in Unix milliseconds. Defaults to 24h ago.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp in Unix milliseconds. Defaults to now.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 100, max: 1000)",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 1000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of trades with cursor for next page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseTradeArray"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/lighter/trades/{symbol}/recent": {
      "get": {
        "tags": [
          "Lighter - Trades"
        ],
        "summary": "Get recent Lighter trades",
        "description": "Get the most recent trades for a coin, ordered by timestamp descending.",
        "operationId": "getLighterRecentTrades",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "ETH"
            },
            "description": "Trading pair symbol (e.g., ETH, BTC)",
            "example": "ETH"
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Number of trades to return (default: 100, max: 1000)",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 1000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of recent trades",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseTradeArray"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/lighter/candles/{symbol}": {
      "get": {
        "tags": [
          "Lighter - Candles"
        ],
        "summary": "Get Lighter OHLCV candles",
        "description": "Get historical OHLCV candle data. Supports multiple intervals from 1 minute to 1 week. Data available from August 2025.\n\n**Available Intervals:** 1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w\n\n**Pagination:** Use the `cursor` parameter with the value from the previous response's `next_cursor` for efficient pagination.",
        "operationId": "getLighterCandles",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "ETH"
            },
            "description": "Trading pair symbol (e.g., ETH, BTC)",
            "example": "ETH"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp in Unix milliseconds. Defaults to 24h ago.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp in Unix milliseconds. Defaults to now.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "interval",
            "in": "query",
            "description": "Candle interval (default: 1h)",
            "schema": {
              "type": "string",
              "enum": [
                "1m",
                "5m",
                "15m",
                "30m",
                "1h",
                "4h",
                "1d",
                "1w"
              ],
              "default": "1h"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination (use the value from previous response's `next_cursor`)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 100, max: 10000)",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 10000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of OHLCV candles with cursor for next page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseCandleArray"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/lighter/openinterest/{symbol}": {
      "get": {
        "tags": [
          "Lighter - Open Interest"
        ],
        "summary": "Get Lighter open interest history",
        "description": "Get historical open interest data. Data available from August 2025.",
        "operationId": "getLighterOpenInterest",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "ETH"
            },
            "description": "Trading pair symbol (e.g., ETH, BTC)",
            "example": "ETH"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp in Unix milliseconds. Defaults to 24h ago.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp in Unix milliseconds. Defaults to now.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 100, max: 1000)",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 1000
            }
          },
          {
            "name": "interval",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "5m",
                "15m",
                "30m",
                "1h",
                "4h",
                "1d"
              ]
            },
            "description": "Aggregation interval. When omitted, returns raw ~1 min resolution data."
          }
        ],
        "responses": {
          "200": {
            "description": "Open interest data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseOpenInterestArray"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/lighter/openinterest/{symbol}/current": {
      "get": {
        "tags": [
          "Lighter - Open Interest"
        ],
        "summary": "Get current Lighter open interest",
        "description": "Get the latest open interest value.",
        "operationId": "getCurrentLighterOpenInterest",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "ETH"
            },
            "description": "Trading pair symbol (e.g., ETH, BTC)",
            "example": "ETH"
          }
        ],
        "responses": {
          "200": {
            "description": "Current open interest",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseOpenInterest"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/lighter/funding/{symbol}": {
      "get": {
        "tags": [
          "Lighter - Funding"
        ],
        "summary": "Get Lighter funding rate history",
        "description": "Get historical funding rates. Data available from August 2025.",
        "operationId": "getLighterFundingHistory",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "ETH"
            },
            "description": "Trading pair symbol (e.g., ETH, BTC)",
            "example": "ETH"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp in Unix milliseconds. Defaults to 24h ago.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp in Unix milliseconds. Defaults to now.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 100, max: 1000)",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 1000
            }
          },
          {
            "name": "interval",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "5m",
                "15m",
                "30m",
                "1h",
                "4h",
                "1d"
              ]
            },
            "description": "Aggregation interval. When omitted, returns raw ~1 min resolution data."
          }
        ],
        "responses": {
          "200": {
            "description": "Funding rate history",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseFundingRateArray"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/lighter/funding/{symbol}/current": {
      "get": {
        "tags": [
          "Lighter - Funding"
        ],
        "summary": "Get current Lighter funding rate",
        "description": "Get the latest funding rate for a coin.",
        "operationId": "getCurrentLighterFunding",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "ETH"
            },
            "description": "Trading pair symbol (e.g., ETH, BTC)",
            "example": "ETH"
          }
        ],
        "responses": {
          "200": {
            "description": "Current funding rate",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseFundingRate"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/lighter/freshness/{symbol}": {
      "get": {
        "tags": [
          "Lighter - Convenience"
        ],
        "summary": "Get Lighter data freshness",
        "description": "Check when data was last updated for each data type for a specific Lighter.xyz coin.",
        "operationId": "getLighterFreshness",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "Coin symbol (e.g., BTC, ETH)",
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "example": "ETH"
          }
        ],
        "responses": {
          "200": {
            "description": "Data freshness for the coin",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseCoinFreshness"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/lighter/summary/{symbol}": {
      "get": {
        "tags": [
          "Lighter - Convenience"
        ],
        "summary": "Get Lighter market summary",
        "description": "Get a combined market summary including price, funding, and open interest in a single call.",
        "operationId": "getLighterSummary",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "Coin symbol (e.g., BTC, ETH)",
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "example": "ETH"
          }
        ],
        "responses": {
          "200": {
            "description": "Market summary for the coin",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseCoinSummary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/lighter/prices/{symbol}": {
      "get": {
        "tags": [
          "Lighter - Convenience"
        ],
        "summary": "Get Lighter price history",
        "description": "Get mark/oracle price history. Lightweight projection of open interest data returning only price fields.",
        "operationId": "getLighterPriceHistory",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "Coin symbol (e.g., BTC, ETH)",
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "example": "ETH"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp in milliseconds",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp in milliseconds",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "interval",
            "in": "query",
            "description": "Aggregation interval",
            "schema": {
              "type": "string",
              "enum": [
                "5m",
                "15m",
                "30m",
                "1h",
                "4h",
                "1d"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 100, max: 1000)",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 1000
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Price history data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponsePriceSnapshotArray"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip3/instruments": {
      "get": {
        "tags": [
          "HIP-3 Builder Perps - Instruments"
        ],
        "summary": "List HIP-3 instruments",
        "description": "List all available HIP-3 builder-deployed perpetuals with latest market data (mark price, open interest, mid price). No tier restriction — useful for discovery.",
        "operationId": "listHip3Instruments",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "List of HIP-3 instruments",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseHip3InstrumentArray"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip3/instruments/{symbol}": {
      "get": {
        "tags": [
          "HIP-3 Builder Perps - Instruments"
        ],
        "summary": "Get HIP-3 instrument",
        "description": "Get a specific HIP-3 instrument by coin name with latest market data. Coin names are case-sensitive (e.g., km:US500, xyz:XYZ100).",
        "operationId": "getHip3Instrument",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "HIP-3 symbol name (e.g., km:US500, xyz:XYZ100). Case-sensitive.",
            "example": "km:US500"
          }
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "HIP-3 instrument details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseHip3Instrument"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip3/orderbook/{symbol}": {
      "get": {
        "tags": [
          "HIP-3 Builder Perps - Order Book"
        ],
        "summary": "Get HIP-3 order book",
        "description": "Get the latest order book snapshot for a HIP-3 Builder Perps coin, or at a specific timestamp. Returns L2 depth with price, size, and order count at each level. Data available from February 2026. Free tier: km:US500 only. Build+: all symbols.",
        "operationId": "getHip3Orderbook",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "HIP-3 symbol name (e.g., xyz:XYZ100)",
            "schema": {
              "type": "string",
              "example": "xyz:XYZ100"
            },
            "example": "km:US500"
          },
          {
            "name": "timestamp",
            "in": "query",
            "description": "Unix timestamp in milliseconds. If not provided, returns latest snapshot.",
            "schema": {
              "type": "integer",
              "format": "int64",
              "example": 1739750400000
            }
          },
          {
            "name": "depth",
            "in": "query",
            "description": "Number of price levels per side. Tier limits: Free=20, Build=200, Pro=Full Depth, Enterprise=Full Depth",
            "schema": {
              "type": "integer",
              "example": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Order book snapshot",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseOrderBook"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip3/orderbook/{symbol}/history": {
      "get": {
        "tags": [
          "HIP-3 Builder Perps - Order Book"
        ],
        "summary": "Get HIP-3 order book history",
        "description": "Get historical order book snapshots within a time range with cursor pagination. Data available from February 2026. Free tier: km:US500 only. Build+: all symbols.",
        "operationId": "getHip3OrderbookHistory",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "xyz:XYZ100"
            },
            "description": "Trading pair symbol (e.g., km:US500, xyz:XYZ100). HIP-3 symbols are case-sensitive.",
            "example": "km:US500"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp in Unix milliseconds. Defaults to 24h ago.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp in Unix milliseconds. Defaults to now.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 100, max: 1000)",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 1000
            }
          },
          {
            "name": "depth",
            "in": "query",
            "description": "Number of price levels per side. Tier limits: Free=20, Build=200, Pro=Full Depth, Enterprise=Full Depth",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of order book snapshots",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseOrderBookArray"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip3/trades/{symbol}": {
      "get": {
        "tags": [
          "HIP-3 Builder Perps - Trades"
        ],
        "summary": "Get HIP-3 trades",
        "description": "Get historical trades (fills) for a HIP-3 Builder Perps coin within a time range. Data available from February 2026. Free tier: km:US500 only. Build+: all coins.\n\n**Pagination:** Use the `cursor` parameter with the value from the previous response's `next_cursor` for efficient pagination.",
        "operationId": "getHip3Trades",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "xyz:XYZ100"
            },
            "description": "Trading pair symbol (e.g., km:US500, xyz:XYZ100). HIP-3 symbols are case-sensitive.",
            "example": "km:US500"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp in Unix milliseconds. Defaults to 24h ago.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp in Unix milliseconds. Defaults to now.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 100, max: 1000)",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 1000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of trades with cursor for next page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseTradeArray"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip3/trades/{symbol}/recent": {
      "get": {
        "tags": [
          "HIP-3 Builder Perps - Trades"
        ],
        "summary": "Get recent HIP-3 trades",
        "description": "Get the most recent trades for a HIP-3 Builder Perps coin, ordered by timestamp descending. Data available from February 2026. No tier restriction.",
        "operationId": "getHip3RecentTrades",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "xyz:XYZ100"
            },
            "description": "Trading pair symbol (e.g., km:US500, xyz:XYZ100). HIP-3 symbols are case-sensitive.",
            "example": "km:US500"
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Number of trades to return (default: 100, max: 1000)",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 1000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of recent trades",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseTradeArray"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip3/candles/{symbol}": {
      "get": {
        "tags": [
          "HIP-3 Builder Perps - Candles"
        ],
        "summary": "Get HIP-3 OHLCV candles",
        "description": "Get historical OHLCV candle data aggregated from HIP-3 trades. Data available from February 2026. Free tier: km:US500 only. Build+: all coins.\n\n**Available Intervals:** 1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w\n\n**Pagination:** Use the `cursor` parameter with the value from the previous response's `next_cursor` for efficient pagination.",
        "operationId": "getHip3Candles",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "km:US500"
            },
            "description": "Trading pair symbol (e.g., km:US500, xyz:XYZ100). HIP-3 symbols are case-sensitive.",
            "example": "km:US500"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp in Unix milliseconds. Defaults to 24h ago.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp in Unix milliseconds. Defaults to now.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "interval",
            "in": "query",
            "description": "Candle interval (default: 1h)",
            "schema": {
              "type": "string",
              "enum": [
                "1m",
                "5m",
                "15m",
                "30m",
                "1h",
                "4h",
                "1d",
                "1w"
              ],
              "default": "1h"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination (use the value from previous response's `next_cursor`)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 100, max: 1000)",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 1000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of OHLCV candles with cursor for next page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseCandleArray"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip3/openinterest/{symbol}": {
      "get": {
        "tags": [
          "HIP-3 Builder Perps - Open Interest"
        ],
        "summary": "Get HIP-3 open interest history",
        "description": "Get historical open interest data for a HIP-3 Builder Perps coin. Data available from February 2026. Free tier: km:US500 only. Build+: all coins.",
        "operationId": "getHip3OpenInterest",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "xyz:XYZ100"
            },
            "description": "Trading pair symbol (e.g., km:US500, xyz:XYZ100). HIP-3 symbols are case-sensitive.",
            "example": "km:US500"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp in Unix milliseconds. Defaults to 24h ago.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp in Unix milliseconds. Defaults to now.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 100, max: 1000)",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 1000
            }
          },
          {
            "name": "interval",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "5m",
                "15m",
                "30m",
                "1h",
                "4h",
                "1d"
              ]
            },
            "description": "Aggregation interval. When omitted, returns raw ~1 min resolution data."
          }
        ],
        "responses": {
          "200": {
            "description": "Open interest data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseOpenInterestArray"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip3/openinterest/{symbol}/current": {
      "get": {
        "tags": [
          "HIP-3 Builder Perps - Open Interest"
        ],
        "summary": "Get current HIP-3 open interest",
        "description": "Get the latest open interest value for a HIP-3 Builder Perps coin. Data available from February 2026. No tier restriction.",
        "operationId": "getCurrentHip3OpenInterest",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "xyz:XYZ100"
            },
            "description": "Trading pair symbol (e.g., km:US500, xyz:XYZ100). HIP-3 symbols are case-sensitive.",
            "example": "km:US500"
          }
        ],
        "responses": {
          "200": {
            "description": "Current open interest",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseOpenInterest"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip3/funding/{symbol}": {
      "get": {
        "tags": [
          "HIP-3 Builder Perps - Funding"
        ],
        "summary": "Get HIP-3 funding rate history",
        "description": "Get historical funding rates for a HIP-3 Builder Perps coin. Data available from February 2026. Free tier: km:US500 only. Build+: all coins.",
        "operationId": "getHip3FundingHistory",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "xyz:XYZ100"
            },
            "description": "Trading pair symbol (e.g., km:US500, xyz:XYZ100). HIP-3 symbols are case-sensitive.",
            "example": "km:US500"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp in Unix milliseconds. Defaults to 24h ago.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp in Unix milliseconds. Defaults to now.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 100, max: 1000)",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 1000
            }
          },
          {
            "name": "interval",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "5m",
                "15m",
                "30m",
                "1h",
                "4h",
                "1d"
              ]
            },
            "description": "Aggregation interval. When omitted, returns raw ~1 min resolution data."
          }
        ],
        "responses": {
          "200": {
            "description": "Funding rate history",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseFundingRateArray"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip3/funding/{symbol}/current": {
      "get": {
        "tags": [
          "HIP-3 Builder Perps - Funding"
        ],
        "summary": "Get current HIP-3 funding rate",
        "description": "Get the latest funding rate for a HIP-3 Builder Perps coin. Data available from February 2026. No tier restriction.",
        "operationId": "getCurrentHip3Funding",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "xyz:XYZ100"
            },
            "description": "Trading pair symbol (e.g., km:US500, xyz:XYZ100). HIP-3 symbols are case-sensitive.",
            "example": "km:US500"
          }
        ],
        "responses": {
          "200": {
            "description": "Current funding rate",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseFundingRate"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip3/liquidations/{symbol}": {
      "get": {
        "tags": [
          "HIP-3 Builder Perps - Liquidations"
        ],
        "summary": "Get HIP-3 liquidation events",
        "description": "Get liquidation-related fills for a HIP-3 symbol. Data derived from hip3_fills where is_liquidation=true and can include liquidated-user rows plus counterparty/open-side rows. Data available from February 2026. Free tier: km:US500 only. Build+: all symbols.",
        "operationId": "getHip3Liquidations",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "HIP-3 trading pair symbol (e.g., hyna:BTC, km:US500). Case-sensitive.",
            "schema": {
              "type": "string",
              "example": "hyna:BTC"
            },
            "example": "hyna:BTC"
          },
          {
            "name": "start",
            "in": "query",
            "required": true,
            "description": "Start timestamp (Unix milliseconds)",
            "schema": {
              "type": "integer",
              "format": "int64",
              "example": 1769922000000
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp (Unix milliseconds). Defaults to now.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Pagination cursor (format: {timestamp_ms}_{trade_id})",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum records to return (1-1000)",
            "schema": {
              "type": "integer",
              "default": 1000,
              "maximum": 1000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Liquidation events",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseLiquidationArray"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip3/liquidations/{symbol}/volume": {
      "get": {
        "tags": [
          "HIP-3 Builder Perps - Liquidations"
        ],
        "summary": "Get HIP-3 aggregated liquidation volume",
        "description": "Get aggregated liquidation-related volume in time-bucketed intervals for a HIP-3 symbol. total_* covers all liquidation rows; long_* and short_* are directional-family subtotals and may not sum to total when upstream emits unclassified directions. Data available from February 2026. Free tier: km:US500 only. Build+: all symbols.",
        "operationId": "getHip3LiquidationVolume",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "HIP-3 trading pair symbol (e.g., hyna:BTC, km:US500). Case-sensitive.",
            "schema": {
              "type": "string",
              "example": "hyna:BTC"
            },
            "example": "hyna:BTC"
          },
          {
            "name": "start",
            "in": "query",
            "required": true,
            "description": "Start timestamp (Unix milliseconds)",
            "schema": {
              "type": "integer",
              "format": "int64",
              "example": 1769922000000
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp (Unix milliseconds). Defaults to now.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Pagination cursor (timestamp in milliseconds)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum buckets to return (1-1000)",
            "schema": {
              "type": "integer",
              "default": 1000,
              "maximum": 1000
            }
          },
          {
            "name": "interval",
            "in": "query",
            "description": "Aggregation interval",
            "schema": {
              "type": "string",
              "enum": [
                "5m",
                "15m",
                "30m",
                "1h",
                "4h",
                "1d"
              ],
              "default": "1h"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Aggregated liquidation volume data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseLiquidationVolumeArray"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip3/freshness/{symbol}": {
      "get": {
        "tags": [
          "HIP-3 Builder Perps - Convenience"
        ],
        "summary": "Get HIP-3 data freshness",
        "description": "Check when data was last updated for each data type for a specific HIP-3 coin. Coin names are case-sensitive.",
        "operationId": "getHip3Freshness",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "HIP-3 symbol (case-sensitive, e.g., km:US500)",
            "schema": {
              "type": "string",
              "example": "km:US500"
            },
            "example": "km:US500"
          }
        ],
        "responses": {
          "200": {
            "description": "Data freshness for the coin",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseCoinFreshness"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip3/summary/{symbol}": {
      "get": {
        "tags": [
          "HIP-3 Builder Perps - Convenience"
        ],
        "summary": "Get HIP-3 market summary",
        "description": "Get a combined market summary including price, mid price, funding, and open interest in a single call.",
        "operationId": "getHip3Summary",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "HIP-3 symbol (case-sensitive, e.g., km:US500)",
            "schema": {
              "type": "string",
              "example": "km:US500"
            },
            "example": "km:US500"
          }
        ],
        "responses": {
          "200": {
            "description": "Market summary for the coin",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseCoinSummary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip3/prices/{symbol}": {
      "get": {
        "tags": [
          "HIP-3 Builder Perps - Convenience"
        ],
        "summary": "Get HIP-3 price history",
        "description": "Get mark/oracle/mid price history. Lightweight projection of open interest data. Coin names are case-sensitive.",
        "operationId": "getHip3PriceHistory",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "HIP-3 symbol (case-sensitive, e.g., km:US500)",
            "schema": {
              "type": "string",
              "example": "km:US500"
            },
            "example": "km:US500"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp in milliseconds",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp in milliseconds",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "interval",
            "in": "query",
            "description": "Aggregation interval",
            "schema": {
              "type": "string",
              "enum": [
                "5m",
                "15m",
                "30m",
                "1h",
                "4h",
                "1d"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 100, max: 1000)",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 1000
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Price history data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponsePriceSnapshotArray"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/data-quality/status": {
      "get": {
        "tags": [
          "Data Quality"
        ],
        "summary": "Get system status",
        "description": "Get overall system health status including per-exchange and per-data-type status.",
        "operationId": "getDataQualityStatus",
        "responses": {
          "200": {
            "description": "System status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatusResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/data-quality/coverage": {
      "get": {
        "tags": [
          "Data Quality"
        ],
        "summary": "Get coverage summary",
        "description": "Get data coverage summary for all exchanges including earliest/latest data, record counts, and completeness. Note: May take 30-60 seconds on first request (results are cached server-side for 5 minutes).",
        "operationId": "getDataQualityCoverage",
        "responses": {
          "200": {
            "description": "Coverage summary",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CoverageResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/data-quality/coverage/{exchange}": {
      "get": {
        "tags": [
          "Data Quality"
        ],
        "summary": "Get exchange coverage",
        "description": "Get data coverage for a specific exchange. Note: May take 30-60 seconds on first request (results are cached server-side for 5 minutes).",
        "operationId": "getExchangeCoverage",
        "parameters": [
          {
            "name": "exchange",
            "in": "path",
            "required": true,
            "description": "Exchange name",
            "schema": {
              "type": "string",
              "enum": [
                "hyperliquid",
                "lighter",
                "hip3"
              ],
              "example": "hyperliquid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Exchange coverage",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExchangeCoverageResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/data-quality/coverage/{exchange}/{symbol}": {
      "get": {
        "tags": [
          "Data Quality"
        ],
        "summary": "Get symbol coverage with gaps",
        "description": "Get data coverage for a specific symbol on an exchange, including gap detection showing periods where data may be missing. Supports optional `from`/`to` query params (Unix ms) to bound the gap detection window (default: last 30 days). Returns empirical data cadence when sufficient data is available. Historical coverage uses hour-level granularity. Note: May take 30-60 seconds on first request (gap detection results are cached server-side for 1 hour).",
        "operationId": "getSymbolCoverage",
        "parameters": [
          {
            "name": "exchange",
            "in": "path",
            "required": true,
            "description": "Exchange name",
            "schema": {
              "type": "string",
              "enum": [
                "hyperliquid",
                "lighter",
                "hip3"
              ],
              "example": "hyperliquid"
            }
          },
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "Symbol name (e.g., BTC, ETH)",
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "example": "BTC"
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Start of gap detection window (Unix milliseconds). Default: now - 30 days.",
            "schema": {
              "type": "integer",
              "format": "int64",
              "example": 1704067200000
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "End of gap detection window (Unix milliseconds). Default: now.",
            "schema": {
              "type": "integer",
              "format": "int64",
              "example": 1706745600000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Symbol coverage with gaps",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SymbolCoverageResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/data-quality/incidents": {
      "get": {
        "tags": [
          "Data Quality"
        ],
        "summary": "List incidents",
        "description": "List data quality incidents with filtering and pagination.",
        "operationId": "listIncidents",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "description": "Filter by incident status",
            "schema": {
              "type": "string",
              "enum": [
                "open",
                "investigating",
                "identified",
                "monitoring",
                "resolved"
              ]
            }
          },
          {
            "name": "exchange",
            "in": "query",
            "description": "Filter by exchange",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "since",
            "in": "query",
            "description": "Only show incidents starting after this timestamp (Unix ms)",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum results per page (default: 20, max: 100)",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Pagination offset",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of incidents",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IncidentsResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/data-quality/incidents/{id}": {
      "get": {
        "tags": [
          "Data Quality"
        ],
        "summary": "Get incident",
        "description": "Get a specific incident by ID.",
        "operationId": "getIncident",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Incident ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Incident details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Incident"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/data-quality/latency": {
      "get": {
        "tags": [
          "Data Quality"
        ],
        "summary": "Get latency metrics",
        "description": "Get current latency metrics for all exchanges including WebSocket, REST API, and data freshness.",
        "operationId": "getLatencyMetrics",
        "responses": {
          "200": {
            "description": "Latency metrics",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LatencyResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/data-quality/sla": {
      "get": {
        "tags": [
          "Data Quality"
        ],
        "summary": "Get SLA metrics",
        "description": "Get SLA compliance metrics for a specific month including uptime, completeness, and latency targets vs actuals.",
        "operationId": "getSlaMetrics",
        "parameters": [
          {
            "name": "year",
            "in": "query",
            "description": "Year (defaults to current year)",
            "schema": {
              "type": "integer",
              "example": 2026
            }
          },
          {
            "name": "month",
            "in": "query",
            "description": "Month 1-12 (defaults to current month)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 12,
              "example": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "SLA metrics",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SlaResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/auth/web3/challenge": {
      "post": {
        "tags": [
          "Web3 Authentication"
        ],
        "summary": "Get SIWE challenge message",
        "description": "Get a SIWE (Sign-In with Ethereum) challenge message to sign. This is the first step for all web3 authentication operations. The nonce is single-use and expires after 10 minutes.",
        "operationId": "web3Challenge",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Web3ChallengeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SIWE challenge message",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Web3ChallengeResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/web3/signup": {
      "post": {
        "tags": [
          "Web3 Authentication"
        ],
        "summary": "Create free-tier account and API key",
        "description": "Create a free-tier account and get an API key using a signed SIWE message. If the wallet already has an account, returns a new key (subject to tier limits). Requires a fresh challenge from `/v1/auth/web3/challenge` signed with `personal_sign` (EIP-191).",
        "operationId": "web3Signup",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Web3SignupRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Account created and API key returned",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Web3SignupResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/web3/keys": {
      "post": {
        "tags": [
          "Web3 Authentication"
        ],
        "summary": "List API keys for wallet",
        "description": "List all API keys belonging to the authenticated wallet. Requires a fresh SIWE challenge signed with `personal_sign` (EIP-191).",
        "operationId": "web3ListKeys",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Web3KeysRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "List of API keys",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Web3KeysResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/web3/keys/revoke": {
      "post": {
        "tags": [
          "Web3 Authentication"
        ],
        "summary": "Revoke an API key",
        "description": "Revoke a specific API key by its ID. Requires a fresh SIWE challenge signed with `personal_sign` (EIP-191).",
        "operationId": "web3RevokeKey",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Web3RevokeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Key revoked successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Web3RevokeResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/web3/subscribe": {
      "post": {
        "tags": [
          "Web3 Authentication"
        ],
        "summary": "Subscribe to a paid tier via x402 USDC payment",
        "description": "x402-protected endpoint for purchasing Build or Pro subscriptions with USDC on Base.\n\n**Flow:**\n1. POST with `{ \"tier\": \"build\" }` (no payment header) → Server returns 402 with payment details (amount, pay_to address, network)\n2. Sign an EIP-712 `TransferWithAuthorization` (EIP-3009) on USDC Base for the specified amount\n3. Build x402 v2 payment payload, base64-encode it, and retry with `payment-signature` header\n4. Server verifies payment via facilitator → creates subscription → returns API key\n\nNo API key required. Payment IS the authentication.",
        "operationId": "web3Subscribe",
        "security": [],
        "parameters": [
          {
            "name": "payment-signature",
            "in": "header",
            "description": "Base64-encoded x402 v2 payment payload containing the EIP-3009 signed USDC transfer authorization. Omit on first request to receive payment details.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Web3SubscribeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Subscription created successfully (returned when valid payment-signature header is provided)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Web3SubscribeResponse"
                }
              }
            }
          },
          "402": {
            "description": "Payment required. Response includes payment details: amount (micro-USDC), pay_to address, and network. Sign and retry with payment-signature header.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "payment": {
                      "type": "object",
                      "properties": {
                        "amount": {
                          "type": "string",
                          "description": "Amount in micro-USDC (6 decimals)",
                          "example": "49000000"
                        },
                        "pay_to": {
                          "type": "string",
                          "description": "Treasury address to send USDC to",
                          "example": "0x..."
                        },
                        "network": {
                          "type": "string",
                          "description": "Blockchain network",
                          "example": "base"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/orders/{symbol}/history": {
      "get": {
        "tags": [
          "Hyperliquid - Orders"
        ],
        "summary": "Get Hyperliquid order history",
        "description": "Get order lifecycle events for a symbol. Includes order placements, modifications, fills, cancellations, and triggers. Requires Pro tier or higher.",
        "operationId": "getHyperliquidOrderHistory",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "Trading pair symbol (e.g., BTC, ETH, SOL)",
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "example": "BTC"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp (ISO 8601 format, e.g., 2026-01-01T00:00:00Z)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp (ISO 8601 format, e.g., 2026-01-02T00:00:00Z)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination (use the value from previous response's `next_cursor`)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 1000, max: 10000)",
            "schema": {
              "type": "integer",
              "default": 1000,
              "maximum": 10000
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Filter by order status",
            "schema": {
              "type": "string",
              "enum": [
                "open",
                "filled",
                "canceled",
                "triggered",
                "force_canceled"
              ]
            }
          },
          {
            "name": "order_type",
            "in": "query",
            "description": "Filter by order type",
            "schema": {
              "type": "string",
              "enum": [
                "limit",
                "trigger",
                "tpsl"
              ]
            }
          },
          {
            "name": "triggered",
            "in": "query",
            "description": "Filter by whether order was triggered",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "user_address",
            "in": "query",
            "description": "Filter by user wallet address",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Order lifecycle events",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer"
                        },
                        "next_cursor": {
                          "type": "string"
                        },
                        "request_id": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/orders/{symbol}/flow": {
      "get": {
        "tags": [
          "Hyperliquid - Orders"
        ],
        "summary": "Get Hyperliquid order flow",
        "description": "Get per-minute order flow aggregation for a symbol. Shows order placement and cancellation rates over time. Requires Pro tier or higher.",
        "operationId": "getHyperliquidOrderFlow",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "Trading pair symbol (e.g., BTC, ETH, SOL)",
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "example": "BTC"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp (ISO 8601 format, e.g., 2026-01-01T00:00:00Z)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp (ISO 8601 format, e.g., 2026-01-02T00:00:00Z)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination (use the value from previous response's `next_cursor`)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 1000, max: 10000)",
            "schema": {
              "type": "integer",
              "default": 1000,
              "maximum": 10000
            }
          },
          {
            "name": "granularity",
            "in": "query",
            "description": "Aggregation granularity",
            "schema": {
              "type": "string",
              "enum": [
                "1m",
                "5m",
                "15m",
                "1h"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Order flow aggregation data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer"
                        },
                        "next_cursor": {
                          "type": "string"
                        },
                        "request_id": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/orders/{symbol}/tpsl": {
      "get": {
        "tags": [
          "Hyperliquid - Orders"
        ],
        "summary": "Get Hyperliquid TP/SL orders",
        "description": "Get take-profit and stop-loss order events for a symbol. Shows TP/SL placements, triggers, and cancellations. Requires Pro tier or higher.",
        "operationId": "getHyperliquidTpsl",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "Trading pair symbol (e.g., BTC, ETH, SOL)",
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "example": "BTC"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp (ISO 8601 format, e.g., 2026-01-01T00:00:00Z)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp (ISO 8601 format, e.g., 2026-01-02T00:00:00Z)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination (use the value from previous response's `next_cursor`)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 1000, max: 10000)",
            "schema": {
              "type": "integer",
              "default": 1000,
              "maximum": 10000
            }
          },
          {
            "name": "user_address",
            "in": "query",
            "description": "Filter by user wallet address",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "TP/SL order events",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer"
                        },
                        "next_cursor": {
                          "type": "string"
                        },
                        "request_id": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/orderbook/{symbol}/l4": {
      "get": {
        "tags": [
          "Hyperliquid - L4 Order Book"
        ],
        "summary": "Get Hyperliquid L4 orderbook",
        "description": "Get the full L4 (individual order-level) orderbook reconstruction for a symbol. Shows every resting order with its price, size, and order ID. Returns the latest snapshot if no timestamp is provided. Requires Pro tier or higher.",
        "operationId": "getHyperliquidL4Orderbook",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "Trading pair symbol (e.g., BTC, ETH, SOL)",
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "example": "BTC"
          },
          {
            "name": "timestamp",
            "in": "query",
            "description": "ISO 8601 timestamp. If not provided, returns latest snapshot.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "L4 orderbook snapshot",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer"
                        },
                        "next_cursor": {
                          "type": "string"
                        },
                        "request_id": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/orderbook/{symbol}/l4/diffs": {
      "get": {
        "tags": [
          "Hyperliquid - L4 Order Book"
        ],
        "summary": "Get Hyperliquid L4 orderbook diffs",
        "description": "Get per-order diff events for the L4 orderbook. Each diff represents an individual order placement, modification, fill, or cancellation. Requires Pro tier or higher.",
        "operationId": "getHyperliquidL4Diffs",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "Trading pair symbol (e.g., BTC, ETH, SOL)",
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "example": "BTC"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp (ISO 8601 format, e.g., 2026-01-01T00:00:00Z)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp (ISO 8601 format, e.g., 2026-01-02T00:00:00Z)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination (use the value from previous response's `next_cursor`)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 1000, max: 10000)",
            "schema": {
              "type": "integer",
              "default": 1000,
              "maximum": 10000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "L4 orderbook diff events",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer"
                        },
                        "next_cursor": {
                          "type": "string"
                        },
                        "request_id": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/orderbook/{symbol}/l4/history": {
      "get": {
        "tags": [
          "Hyperliquid - L4 Order Book"
        ],
        "summary": "Get Hyperliquid L4 orderbook history",
        "description": "Get historical L4 orderbook checkpoint list. Each checkpoint is a full L4 snapshot that can be used as a starting point for replay. Requires Build tier or higher.",
        "operationId": "getHyperliquidL4History",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "Trading pair symbol (e.g., BTC, ETH, SOL)",
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "example": "BTC"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp (ISO 8601 format, e.g., 2026-01-01T00:00:00Z)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp (ISO 8601 format, e.g., 2026-01-02T00:00:00Z)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination (use the value from previous response's `next_cursor`)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 1000, max: 10000)",
            "schema": {
              "type": "integer",
              "default": 1000,
              "maximum": 10000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "L4 orderbook checkpoints",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer"
                        },
                        "next_cursor": {
                          "type": "string"
                        },
                        "request_id": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip3/orders/{symbol}/history": {
      "get": {
        "tags": [
          "HIP-3 Builder Perps - Orders"
        ],
        "summary": "Get HIP-3 order history",
        "description": "Get order lifecycle events for a HIP-3 symbol. Includes order placements, modifications, fills, cancellations, and triggers. Requires Pro tier or higher.",
        "operationId": "getHip3OrderHistory",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "HIP-3 symbol (case-sensitive, e.g., hyna:BTC, km:US500)",
            "schema": {
              "type": "string",
              "example": "hyna:BTC"
            },
            "example": "km:US500"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp (ISO 8601 format, e.g., 2026-01-01T00:00:00Z)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp (ISO 8601 format, e.g., 2026-01-02T00:00:00Z)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination (use the value from previous response's `next_cursor`)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 1000, max: 10000)",
            "schema": {
              "type": "integer",
              "default": 1000,
              "maximum": 10000
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Filter by order status",
            "schema": {
              "type": "string",
              "enum": [
                "open",
                "filled",
                "canceled",
                "triggered",
                "force_canceled"
              ]
            }
          },
          {
            "name": "order_type",
            "in": "query",
            "description": "Filter by order type",
            "schema": {
              "type": "string",
              "enum": [
                "limit",
                "trigger",
                "tpsl"
              ]
            }
          },
          {
            "name": "triggered",
            "in": "query",
            "description": "Filter by whether order was triggered",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "user_address",
            "in": "query",
            "description": "Filter by user wallet address",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Order lifecycle events",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer"
                        },
                        "next_cursor": {
                          "type": "string"
                        },
                        "request_id": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip3/orders/{symbol}/flow": {
      "get": {
        "tags": [
          "HIP-3 Builder Perps - Orders"
        ],
        "summary": "Get HIP-3 order flow",
        "description": "Get per-minute order flow aggregation for a HIP-3 symbol. Shows order placement and cancellation rates over time. Requires Pro tier or higher.",
        "operationId": "getHip3OrderFlow",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "HIP-3 symbol (case-sensitive, e.g., hyna:BTC, km:US500)",
            "schema": {
              "type": "string",
              "example": "hyna:BTC"
            },
            "example": "km:US500"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp (ISO 8601 format, e.g., 2026-01-01T00:00:00Z)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp (ISO 8601 format, e.g., 2026-01-02T00:00:00Z)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination (use the value from previous response's `next_cursor`)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 1000, max: 10000)",
            "schema": {
              "type": "integer",
              "default": 1000,
              "maximum": 10000
            }
          },
          {
            "name": "granularity",
            "in": "query",
            "description": "Aggregation granularity",
            "schema": {
              "type": "string",
              "enum": [
                "1m",
                "5m",
                "15m",
                "1h"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Order flow aggregation data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer"
                        },
                        "next_cursor": {
                          "type": "string"
                        },
                        "request_id": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip3/orders/{symbol}/tpsl": {
      "get": {
        "tags": [
          "HIP-3 Builder Perps - Orders"
        ],
        "summary": "Get HIP-3 TP/SL orders",
        "description": "Get take-profit and stop-loss order events for a HIP-3 symbol. Shows TP/SL placements, triggers, and cancellations. Requires Pro tier or higher.",
        "operationId": "getHip3Tpsl",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "HIP-3 symbol (case-sensitive, e.g., hyna:BTC, km:US500)",
            "schema": {
              "type": "string",
              "example": "hyna:BTC"
            },
            "example": "km:US500"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp (ISO 8601 format, e.g., 2026-01-01T00:00:00Z)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp (ISO 8601 format, e.g., 2026-01-02T00:00:00Z)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination (use the value from previous response's `next_cursor`)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 1000, max: 10000)",
            "schema": {
              "type": "integer",
              "default": 1000,
              "maximum": 10000
            }
          },
          {
            "name": "user_address",
            "in": "query",
            "description": "Filter by user wallet address",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "TP/SL order events",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer"
                        },
                        "next_cursor": {
                          "type": "string"
                        },
                        "request_id": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip3/orderbook/{symbol}/l4": {
      "get": {
        "tags": [
          "HIP-3 Builder Perps - L4 Order Book"
        ],
        "summary": "Get HIP-3 L4 orderbook",
        "description": "Get the full L4 (individual order-level) orderbook reconstruction for a HIP-3 symbol. Shows every resting order with its price, size, and order ID. Returns the latest snapshot if no timestamp is provided. Requires Pro tier or higher.",
        "operationId": "getHip3L4Orderbook",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "HIP-3 symbol (case-sensitive, e.g., hyna:BTC, km:US500)",
            "schema": {
              "type": "string",
              "example": "hyna:BTC"
            },
            "example": "km:US500"
          },
          {
            "name": "timestamp",
            "in": "query",
            "description": "ISO 8601 timestamp. If not provided, returns latest snapshot.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "L4 orderbook snapshot",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer"
                        },
                        "next_cursor": {
                          "type": "string"
                        },
                        "request_id": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip3/orderbook/{symbol}/l4/diffs": {
      "get": {
        "tags": [
          "HIP-3 Builder Perps - L4 Order Book"
        ],
        "summary": "Get HIP-3 L4 orderbook diffs",
        "description": "Get per-order diff events for the HIP-3 L4 orderbook. Each diff represents an individual order placement, modification, fill, or cancellation. Requires Pro tier or higher.",
        "operationId": "getHip3L4Diffs",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "HIP-3 symbol (case-sensitive, e.g., hyna:BTC, km:US500)",
            "schema": {
              "type": "string",
              "example": "hyna:BTC"
            },
            "example": "km:US500"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp (ISO 8601 format, e.g., 2026-01-01T00:00:00Z)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp (ISO 8601 format, e.g., 2026-01-02T00:00:00Z)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination (use the value from previous response's `next_cursor`)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 1000, max: 10000)",
            "schema": {
              "type": "integer",
              "default": 1000,
              "maximum": 10000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "L4 orderbook diff events",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer"
                        },
                        "next_cursor": {
                          "type": "string"
                        },
                        "request_id": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip3/orderbook/{symbol}/l4/history": {
      "get": {
        "tags": [
          "HIP-3 Builder Perps - L4 Order Book"
        ],
        "summary": "Get HIP-3 L4 orderbook history",
        "description": "Get historical L4 orderbook checkpoint list for a HIP-3 symbol. Each checkpoint is a full L4 snapshot that can be used as a starting point for replay. Requires Build tier or higher.",
        "operationId": "getHip3L4History",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "HIP-3 symbol (case-sensitive, e.g., hyna:BTC, km:US500)",
            "schema": {
              "type": "string",
              "example": "hyna:BTC"
            },
            "example": "km:US500"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp (ISO 8601 format, e.g., 2026-01-01T00:00:00Z)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp (ISO 8601 format, e.g., 2026-01-02T00:00:00Z)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination (use the value from previous response's `next_cursor`)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 1000, max: 10000)",
            "schema": {
              "type": "integer",
              "default": 1000,
              "maximum": 10000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "L4 orderbook checkpoints",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer"
                        },
                        "next_cursor": {
                          "type": "string"
                        },
                        "request_id": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip4/outcomes": {
      "get": {
        "tags": [
          "HIP-4 Outcomes - Outcomes"
        ],
        "summary": "List HIP-4 outcomes",
        "description": "List HIP-4 outcome markets (one row per outcome, both sides combined). Optional `is_settled` filter. Cursor pagination. Response uses `Hip4OutcomeAggregate` and OMITS the `aggregated_oi` field. Use `/outcomes/{outcome_id}` to fetch a single outcome with `aggregated_oi` populated. Requires Build tier or higher. Data available from May 2026.",
        "operationId": "listHip4Outcomes",
        "parameters": [
          {
            "name": "is_settled",
            "in": "query",
            "description": "Filter by settlement status. Omit to return both live and settled outcomes.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination (use the value from previous response's `next_cursor`)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 100, max: 1000)",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 1000
            }
          }
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "List of HIP-4 outcomes (without `aggregated_oi`)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseHip4OutcomeAggregateArray"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip4/outcomes/{outcome_id}": {
      "get": {
        "tags": [
          "HIP-4 Outcomes - Outcomes"
        ],
        "summary": "Get HIP-4 outcome detail",
        "description": "Get a single HIP-4 outcome by `outcome_id`. Response uses `Hip4OutcomeAggregate` WITH `aggregated_oi` populated: latest both-sides OI snapshot including `outcome_display_open_interest_contracts` (sum of side0 + side1), `paired_set_supply_contracts` (paired-set notional), and `side_supply_parity` (whether side0 == side1 within tolerance). Currency is always `USDH`. Requires Build tier or higher. Data available from May 2026.",
        "operationId": "getHip4Outcome",
        "parameters": [
          {
            "name": "outcome_id",
            "in": "path",
            "required": true,
            "description": "Numeric outcome ID (integer >= 0). Each outcome has two sides: side 0 (Yes) and side 1 (No).",
            "schema": {
              "type": "integer",
              "format": "int64",
              "example": 0
            },
            "example": 0
          }
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "HIP-4 outcome detail (with `aggregated_oi`)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseHip4OutcomeAggregate"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip4/instruments": {
      "get": {
        "tags": [
          "HIP-4 Outcomes - Instruments"
        ],
        "summary": "List HIP-4 instruments",
        "description": "List all HIP-4 outcome-market per-side instruments (one row per `#N` coin). Each outcome has two sides: side 0 (Yes) and side 1 (No). Coins are `#`-prefixed. Requires Build tier or higher.",
        "operationId": "listHip4Instruments",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "List of HIP-4 per-side instruments",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseHip4OutcomeArray"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip4/instruments/{symbol}": {
      "get": {
        "tags": [
          "HIP-4 Outcomes - Instruments"
        ],
        "summary": "Get HIP-4 instrument",
        "description": "Get a single HIP-4 per-side instrument by coin id (e.g., `0`, `1`). The `#`-prefixed form (`#0`, `#1`) is also accepted. Requires Build tier or higher.",
        "operationId": "getHip4Instrument",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "HIP-4 coin id (e.g., `0` for outcome 0 Yes side, `1` for No side). The `#`-prefixed form (`#0`, `#1`) is also accepted.",
            "schema": {
              "type": "string",
              "example": "0"
            },
            "example": "0"
          }
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "HIP-4 instrument detail",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseHip4Outcome"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip4/orderbook/{symbol}": {
      "get": {
        "tags": [
          "HIP-4 Outcomes - Order Book"
        ],
        "summary": "Get HIP-4 order book",
        "description": "Get the latest L2 order book snapshot for a HIP-4 outcome side, or at a specific timestamp. Returns L2 depth with price, size, and order count at each level. Requires Pro tier or higher. Data available from May 2026.",
        "operationId": "getHip4Orderbook",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "HIP-4 coin id (e.g., `0` for outcome 0 Yes side, `1` for No side). The `#`-prefixed form (`#0`, `#1`) is also accepted.",
            "schema": {
              "type": "string",
              "example": "0"
            },
            "example": "0"
          },
          {
            "name": "timestamp",
            "in": "query",
            "description": "Unix timestamp in milliseconds. If not provided, returns latest snapshot.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "depth",
            "in": "query",
            "description": "Number of price levels per side. Tier limits: Free=20, Build=200, Pro=Full Depth, Enterprise=Full Depth",
            "schema": {
              "type": "integer",
              "example": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Order book snapshot",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseOrderBook"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip4/orderbook/{symbol}/history": {
      "get": {
        "tags": [
          "HIP-4 Outcomes - Order Book"
        ],
        "summary": "Get HIP-4 order book history",
        "description": "Get historical L2 order book snapshots within a time range with cursor pagination. Requires Pro tier or higher. Data available from May 2026.",
        "operationId": "getHip4OrderbookHistory",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "HIP-4 coin id (e.g., `0` for outcome 0 Yes side, `1` for No side). The `#`-prefixed form (`#0`, `#1`) is also accepted.",
            "schema": {
              "type": "string",
              "example": "0"
            },
            "example": "0"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp in Unix milliseconds. Defaults to 24h ago.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp in Unix milliseconds. Defaults to now.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 100, max: 1000)",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 1000
            }
          },
          {
            "name": "depth",
            "in": "query",
            "description": "Number of price levels per side. Tier limits: Free=20, Build=200, Pro=Full Depth, Enterprise=Full Depth",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of order book snapshots",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseOrderBookArray"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip4/orderbook/{symbol}/l4": {
      "get": {
        "tags": [
          "HIP-4 Outcomes - Order Book"
        ],
        "summary": "Get HIP-4 L4 orderbook",
        "description": "Get the full L4 (individual order-level) orderbook reconstruction for a HIP-4 outcome side. Returns the latest snapshot if no timestamp is provided. Requires Pro tier or higher.",
        "operationId": "getHip4L4Orderbook",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "HIP-4 coin id (e.g., `0` for outcome 0 Yes side, `1` for No side). The `#`-prefixed form (`#0`, `#1`) is also accepted.",
            "schema": {
              "type": "string",
              "example": "0"
            },
            "example": "0"
          },
          {
            "name": "timestamp",
            "in": "query",
            "description": "ISO 8601 timestamp. If not provided, returns latest snapshot.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "L4 orderbook snapshot",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer"
                        },
                        "next_cursor": {
                          "type": "string"
                        },
                        "request_id": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip4/orderbook/{symbol}/l4/diffs": {
      "get": {
        "tags": [
          "HIP-4 Outcomes - Order Book"
        ],
        "summary": "Get HIP-4 L4 orderbook diffs",
        "description": "Get per-order diff events for the HIP-4 L4 orderbook. Each diff represents an individual order placement, modification, fill, or cancellation. Requires Pro tier or higher.",
        "operationId": "getHip4L4Diffs",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "HIP-4 coin id (e.g., `0` for outcome 0 Yes side, `1` for No side). The `#`-prefixed form (`#0`, `#1`) is also accepted.",
            "schema": {
              "type": "string",
              "example": "0"
            },
            "example": "0"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp (ISO 8601 format, e.g., 2026-05-02T00:00:00Z)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp (ISO 8601 format, e.g., 2026-05-03T00:00:00Z)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination (use the value from previous response's `next_cursor`)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 1000, max: 10000)",
            "schema": {
              "type": "integer",
              "default": 1000,
              "maximum": 10000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "L4 orderbook diff events",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer"
                        },
                        "next_cursor": {
                          "type": "string"
                        },
                        "request_id": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip4/orderbook/{symbol}/l4/history": {
      "get": {
        "tags": [
          "HIP-4 Outcomes - Order Book"
        ],
        "summary": "Get HIP-4 L4 orderbook history",
        "description": "Get historical L4 orderbook checkpoint list for a HIP-4 outcome side. Each checkpoint is a full L4 snapshot that can be used as a starting point for replay. Hard cap `limit=10`. Requires Build tier or higher.",
        "operationId": "getHip4L4History",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "HIP-4 coin id (e.g., `0` for outcome 0 Yes side, `1` for No side). The `#`-prefixed form (`#0`, `#1`) is also accepted.",
            "schema": {
              "type": "string",
              "example": "0"
            },
            "example": "0"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp (ISO 8601 format, e.g., 2026-05-02T00:00:00Z)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp (ISO 8601 format, e.g., 2026-05-03T00:00:00Z)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination (use the value from previous response's `next_cursor`)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 10, hard cap: 10)",
            "schema": {
              "type": "integer",
              "default": 10,
              "maximum": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "L4 orderbook checkpoints",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer"
                        },
                        "next_cursor": {
                          "type": "string"
                        },
                        "request_id": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip4/trades/{symbol}": {
      "get": {
        "tags": [
          "HIP-4 Outcomes - Trades"
        ],
        "summary": "Get HIP-4 trades",
        "description": "Get historical trades (fills) for a HIP-4 outcome side within a time range. Requires Build tier or higher. Data available from May 2026.\n\n**Pagination:** Use the `cursor` parameter with the value from the previous response's `next_cursor` for efficient pagination.",
        "operationId": "getHip4Trades",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "HIP-4 coin id (e.g., `0` for outcome 0 Yes side, `1` for No side). The `#`-prefixed form (`#0`, `#1`) is also accepted.",
            "schema": {
              "type": "string",
              "example": "0"
            },
            "example": "0"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp in Unix milliseconds. Defaults to 24h ago.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp in Unix milliseconds. Defaults to now.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 100, max: 1000)",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 1000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of trades with cursor for next page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseTradeArray"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip4/trades/{symbol}/recent": {
      "get": {
        "tags": [
          "HIP-4 Outcomes - Trades"
        ],
        "summary": "Get recent HIP-4 trades",
        "description": "Get the most recent trades for a HIP-4 outcome side, ordered by timestamp descending. Requires Build tier or higher. Data available from May 2026.",
        "operationId": "getHip4RecentTrades",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "HIP-4 coin id (e.g., `0` for outcome 0 Yes side, `1` for No side). The `#`-prefixed form (`#0`, `#1`) is also accepted.",
            "schema": {
              "type": "string",
              "example": "0"
            },
            "example": "0"
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Number of trades to return (default: 100, max: 1000)",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 1000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of recent trades",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseTradeArray"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip4/openinterest/{symbol}": {
      "get": {
        "tags": [
          "HIP-4 Outcomes - Open Interest"
        ],
        "summary": "Get HIP-4 open interest history",
        "description": "Get historical per-side open interest data for a HIP-4 outcome side. Mirrors HIP-3 OI shape plus `outcome_id` and `side` fields. Display/paired/parity aggregates (sum across both sides, paired-set supply, side-supply parity check) live on `/outcomes/{outcome_id}.aggregated_oi`, NOT on this endpoint. Note: `mark_price` for HIP-4 outcomes is an implied probability in [0,1], not a USD price; same field name as perps because Hyperliquid upstream uses `markPx` for both. Requires Build tier or higher. Data available from May 2026.",
        "operationId": "getHip4OpenInterest",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "HIP-4 coin id (e.g., `0` for outcome 0 Yes side, `1` for No side). The `#`-prefixed form (`#0`, `#1`) is also accepted.",
            "schema": {
              "type": "string",
              "example": "0"
            },
            "example": "0"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp in Unix milliseconds. Defaults to 24h ago.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp in Unix milliseconds. Defaults to now.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 100, max: 1000)",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 1000
            }
          },
          {
            "name": "interval",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "5m",
                "15m",
                "30m",
                "1h",
                "4h",
                "1d"
              ]
            },
            "description": "Aggregation interval. When omitted, returns raw ~1 min resolution data."
          }
        ],
        "responses": {
          "200": {
            "description": "Open interest data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseHip4OpenInterestArray"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip4/openinterest/{symbol}/current": {
      "get": {
        "tags": [
          "HIP-4 Outcomes - Open Interest"
        ],
        "summary": "Get current HIP-4 open interest",
        "description": "Get the latest per-side open interest value for a HIP-4 outcome side. Mirrors HIP-3 OI shape plus `outcome_id` and `side` fields. Note: `mark_price` for HIP-4 outcomes is an implied probability in [0,1], not a USD price; same field name as perps because Hyperliquid upstream uses `markPx` for both. Requires Build tier or higher.",
        "operationId": "getCurrentHip4OpenInterest",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "HIP-4 coin id (e.g., `0` for outcome 0 Yes side, `1` for No side). The `#`-prefixed form (`#0`, `#1`) is also accepted.",
            "schema": {
              "type": "string",
              "example": "0"
            },
            "example": "0"
          }
        ],
        "responses": {
          "200": {
            "description": "Current open interest",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseHip4OpenInterest"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip4/freshness/{symbol}": {
      "get": {
        "tags": [
          "HIP-4 Outcomes - Convenience"
        ],
        "summary": "Get HIP-4 data freshness",
        "description": "Check when data was last updated for each data type for a HIP-4 outcome side. Requires Build tier or higher.",
        "operationId": "getHip4Freshness",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "HIP-4 coin id (e.g., `0` for outcome 0 Yes side, `1` for No side). The `#`-prefixed form (`#0`, `#1`) is also accepted.",
            "schema": {
              "type": "string",
              "example": "0"
            },
            "example": "0"
          }
        ],
        "responses": {
          "200": {
            "description": "Data freshness for the coin",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseCoinFreshness"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip4/summary/{symbol}": {
      "get": {
        "tags": [
          "HIP-4 Outcomes - Convenience"
        ],
        "summary": "Get HIP-4 market summary",
        "description": "Get a combined market summary for a HIP-4 outcome side: latest mark price (implied probability in [0,1] for HIP-4, NOT USD), mid price, open interest, and 24h aggregates. Note: `mark_price` for HIP-4 outcomes is an implied probability in [0,1], not a USD price; same field name as perps because Hyperliquid upstream uses `markPx` for both. Requires Build tier or higher.",
        "operationId": "getHip4Summary",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "HIP-4 coin id (e.g., `0` for outcome 0 Yes side, `1` for No side). The `#`-prefixed form (`#0`, `#1`) is also accepted.",
            "schema": {
              "type": "string",
              "example": "0"
            },
            "example": "0"
          }
        ],
        "responses": {
          "200": {
            "description": "Market summary for the coin",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseCoinSummary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip4/prices/{symbol}": {
      "get": {
        "tags": [
          "HIP-4 Outcomes - Convenience"
        ],
        "summary": "Get HIP-4 price history",
        "description": "Get mark/mid price history for a HIP-4 outcome side. Lightweight projection of open interest data. Note: `mark_price` for HIP-4 outcomes is an implied probability in [0,1], not a USD price; same field name as perps because Hyperliquid upstream uses `markPx` for both. `oracle_price` is omitted for HIP-4 (outcomes have no oracle feed). Requires Build tier or higher.",
        "operationId": "getHip4PriceHistory",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "HIP-4 coin id (e.g., `0` for outcome 0 Yes side, `1` for No side). The `#`-prefixed form (`#0`, `#1`) is also accepted.",
            "schema": {
              "type": "string",
              "example": "0"
            },
            "example": "0"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp in milliseconds",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp in milliseconds",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "interval",
            "in": "query",
            "description": "Aggregation interval",
            "schema": {
              "type": "string",
              "enum": [
                "5m",
                "15m",
                "30m",
                "1h",
                "4h",
                "1d"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 100, max: 1000)",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 1000
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Price history data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponsePriceSnapshotArray"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip4/orders/{symbol}/history": {
      "get": {
        "tags": [
          "HIP-4 Outcomes - Orders"
        ],
        "summary": "Get HIP-4 order history",
        "description": "Get order lifecycle events for a HIP-4 outcome side. Includes order placements, modifications, fills, cancellations, and triggers. Requires Pro tier or higher.",
        "operationId": "getHip4OrderHistory",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "HIP-4 coin id (e.g., `0` for outcome 0 Yes side, `1` for No side). The `#`-prefixed form (`#0`, `#1`) is also accepted.",
            "schema": {
              "type": "string",
              "example": "0"
            },
            "example": "0"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp (ISO 8601 format, e.g., 2026-05-02T00:00:00Z)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp (ISO 8601 format, e.g., 2026-05-03T00:00:00Z)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination (use the value from previous response's `next_cursor`)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 1000, max: 10000)",
            "schema": {
              "type": "integer",
              "default": 1000,
              "maximum": 10000
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Filter by order status",
            "schema": {
              "type": "string",
              "enum": [
                "open",
                "filled",
                "canceled",
                "triggered",
                "force_canceled"
              ]
            }
          },
          {
            "name": "order_type",
            "in": "query",
            "description": "Filter by order type",
            "schema": {
              "type": "string",
              "enum": [
                "limit",
                "trigger",
                "tpsl"
              ]
            }
          },
          {
            "name": "triggered",
            "in": "query",
            "description": "Filter by whether order was triggered",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "user_address",
            "in": "query",
            "description": "Filter by user wallet address",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Order lifecycle events",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer"
                        },
                        "next_cursor": {
                          "type": "string"
                        },
                        "request_id": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip4/orders/{symbol}/flow": {
      "get": {
        "tags": [
          "HIP-4 Outcomes - Orders"
        ],
        "summary": "Get HIP-4 order flow",
        "description": "Get per-minute order flow aggregation for a HIP-4 outcome side. Shows order placement and cancellation rates over time. Requires Pro tier or higher.",
        "operationId": "getHip4OrderFlow",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "HIP-4 coin id (e.g., `0` for outcome 0 Yes side, `1` for No side). The `#`-prefixed form (`#0`, `#1`) is also accepted.",
            "schema": {
              "type": "string",
              "example": "0"
            },
            "example": "0"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp (ISO 8601 format, e.g., 2026-05-02T00:00:00Z)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp (ISO 8601 format, e.g., 2026-05-03T00:00:00Z)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination (use the value from previous response's `next_cursor`)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 1000, max: 10000)",
            "schema": {
              "type": "integer",
              "default": 1000,
              "maximum": 10000
            }
          },
          {
            "name": "granularity",
            "in": "query",
            "description": "Aggregation granularity",
            "schema": {
              "type": "string",
              "enum": [
                "1m",
                "5m",
                "15m",
                "1h"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Order flow aggregation data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer"
                        },
                        "next_cursor": {
                          "type": "string"
                        },
                        "request_id": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hyperliquid/hip4/orders/{symbol}/tpsl": {
      "get": {
        "tags": [
          "HIP-4 Outcomes - Orders"
        ],
        "summary": "Get HIP-4 TP/SL orders",
        "description": "Get take-profit and stop-loss order events for a HIP-4 outcome side. Shows TP/SL placements, triggers, and cancellations. Requires Pro tier or higher.",
        "operationId": "getHip4Tpsl",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "HIP-4 coin id (e.g., `0` for outcome 0 Yes side, `1` for No side). The `#`-prefixed form (`#0`, `#1`) is also accepted.",
            "schema": {
              "type": "string",
              "example": "0"
            },
            "example": "0"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp (ISO 8601 format, e.g., 2026-05-02T00:00:00Z)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp (ISO 8601 format, e.g., 2026-05-03T00:00:00Z)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination (use the value from previous response's `next_cursor`)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 1000, max: 10000)",
            "schema": {
              "type": "integer",
              "default": 1000,
              "maximum": 10000
            }
          },
          {
            "name": "user_address",
            "in": "query",
            "description": "Filter by user wallet address",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "TP/SL order events",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer"
                        },
                        "next_cursor": {
                          "type": "string"
                        },
                        "request_id": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/lighter/l3orderbook/{symbol}": {
      "get": {
        "tags": [
          "Lighter - L3 Order Book"
        ],
        "summary": "Get Lighter L3 orderbook",
        "description": "Get the full L3 orderbook with individual orders for a Lighter.xyz symbol. Shows every resting order with its price, size, order ID, and owner address. Requires Pro tier or higher.",
        "operationId": "getLighterL3Orderbook",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "Trading pair symbol (e.g., BTC, ETH, SOL)",
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "example": "ETH"
          }
        ],
        "responses": {
          "200": {
            "description": "L3 orderbook snapshot",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer"
                        },
                        "next_cursor": {
                          "type": "string"
                        },
                        "request_id": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/lighter/l3orderbook/{symbol}/history": {
      "get": {
        "tags": [
          "Lighter - L3 Order Book"
        ],
        "summary": "Get Lighter L3 orderbook history",
        "description": "Get historical L3 orderbook snapshots for a Lighter.xyz symbol. Each snapshot contains the full order-level book state at that point in time. Data available from March 2026. Requires Pro tier or higher.",
        "operationId": "getLighterL3OrderbookHistory",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "Trading pair symbol (e.g., BTC, ETH, SOL)",
            "schema": {
              "type": "string",
              "example": "BTC"
            },
            "example": "ETH"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start timestamp (ISO 8601 format, e.g., 2026-01-01T00:00:00Z)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "End timestamp (ISO 8601 format, e.g., 2026-01-02T00:00:00Z)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination (use the value from previous response's `next_cursor`)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (default: 1000, max: 10000)",
            "schema": {
              "type": "integer",
              "default": 1000,
              "maximum": 10000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Historical L3 orderbook snapshots",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer"
                        },
                        "next_cursor": {
                          "type": "string"
                        },
                        "request_id": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "API key for authentication. Get yours at https://www.0xarchive.io/dashboard/"
      }
    },
    "schemas": {
      "ApiMeta": {
        "type": "object",
        "description": "Response metadata",
        "properties": {
          "count": {
            "type": "integer",
            "description": "Number of records returned"
          },
          "next_cursor": {
            "type": "string",
            "nullable": true,
            "description": "Cursor for pagination (timestamp). Use this value as the `cursor` parameter to fetch the next page of results."
          },
          "request_id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique request ID for support"
          }
        }
      },
      "ApiResponseOrderBook": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "$ref": "#/components/schemas/OrderBook"
          },
          "meta": {
            "$ref": "#/components/schemas/ApiMeta"
          }
        }
      },
      "ApiResponseOrderBookArray": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrderBook"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ApiMeta"
          }
        }
      },
      "ApiResponseTradeArray": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Trade"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ApiMeta"
          }
        }
      },
      "ApiResponseInstrument": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "$ref": "#/components/schemas/Instrument"
          },
          "meta": {
            "$ref": "#/components/schemas/ApiMeta"
          }
        }
      },
      "ApiResponseInstrumentArray": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Instrument"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ApiMeta"
          }
        }
      },
      "ApiResponseLighterInstrument": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "$ref": "#/components/schemas/LighterInstrument"
          },
          "meta": {
            "$ref": "#/components/schemas/ApiMeta"
          }
        }
      },
      "ApiResponseLighterInstrumentArray": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LighterInstrument"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ApiMeta"
          }
        }
      },
      "ApiResponseOpenInterest": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "$ref": "#/components/schemas/OpenInterest"
          },
          "meta": {
            "$ref": "#/components/schemas/ApiMeta"
          }
        }
      },
      "ApiResponseOpenInterestArray": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OpenInterest"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ApiMeta"
          }
        }
      },
      "ApiResponseFundingRate": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "$ref": "#/components/schemas/FundingRate"
          },
          "meta": {
            "$ref": "#/components/schemas/ApiMeta"
          }
        }
      },
      "ApiResponseFundingRateArray": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FundingRate"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ApiMeta"
          }
        }
      },
      "OrderBook": {
        "type": "object",
        "description": "L2 order book snapshot",
        "required": [
          "symbol",
          "coin",
          "timestamp",
          "bids",
          "asks"
        ],
        "properties": {
          "symbol": {
            "type": "string",
            "description": "Trading pair symbol",
            "example": "BTC"
          },
          "coin": {
            "type": "string",
            "description": "Trading pair symbol (deprecated, use symbol instead)",
            "example": "BTC",
            "deprecated": true
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "Snapshot timestamp (UTC)",
            "example": "2025-01-21T10:30:45.123Z"
          },
          "bids": {
            "type": "array",
            "description": "Bid price levels (best bid first)",
            "items": {
              "$ref": "#/components/schemas/PriceLevel"
            }
          },
          "asks": {
            "type": "array",
            "description": "Ask price levels (best ask first)",
            "items": {
              "$ref": "#/components/schemas/PriceLevel"
            }
          },
          "mid_price": {
            "type": "string",
            "description": "Mid price (best bid + best ask) / 2",
            "example": "42150.50"
          },
          "spread": {
            "type": "string",
            "description": "Spread in absolute terms (best ask - best bid)",
            "example": "1.00"
          },
          "spread_bps": {
            "type": "string",
            "description": "Spread in basis points",
            "example": "2.37"
          }
        }
      },
      "PriceLevel": {
        "type": "object",
        "description": "Single price level in the order book",
        "required": [
          "px",
          "sz",
          "n"
        ],
        "properties": {
          "px": {
            "type": "string",
            "description": "Price",
            "example": "42150.00"
          },
          "sz": {
            "type": "string",
            "description": "Total size at this price level",
            "example": "1.5"
          },
          "n": {
            "type": "integer",
            "description": "Number of orders at this level",
            "example": 15
          }
        }
      },
      "OrderbookDelta": {
        "type": "object",
        "description": "Incremental orderbook change (used with tick-level data)",
        "required": [
          "timestamp",
          "side",
          "price",
          "size",
          "sequence"
        ],
        "properties": {
          "timestamp": {
            "type": "integer",
            "format": "int64",
            "description": "Timestamp in milliseconds",
            "example": 1704067201000
          },
          "side": {
            "type": "string",
            "enum": [
              "bid",
              "ask"
            ],
            "description": "Side of the orderbook (bid or ask)",
            "example": "bid"
          },
          "price": {
            "type": "number",
            "description": "Price level",
            "example": 50000
          },
          "size": {
            "type": "number",
            "description": "New size at this price level (0 = level removed)",
            "example": 1.5
          },
          "sequence": {
            "type": "integer",
            "description": "Sequence number for ordering deltas",
            "example": 12345
          }
        }
      },
      "Trade": {
        "type": "object",
        "description": "Trade/fill record with full execution details",
        "required": [
          "symbol",
          "coin",
          "side",
          "price",
          "size",
          "timestamp"
        ],
        "properties": {
          "symbol": {
            "type": "string",
            "description": "Trading pair symbol",
            "example": "BTC"
          },
          "coin": {
            "type": "string",
            "description": "Trading pair symbol (deprecated, use symbol instead)",
            "example": "BTC",
            "deprecated": true
          },
          "side": {
            "type": "string",
            "description": "Trade side: 'B' (buy) or 'A' (sell/ask)",
            "enum": [
              "A",
              "B"
            ],
            "example": "B"
          },
          "price": {
            "type": "string",
            "description": "Execution price",
            "example": "42150.50"
          },
          "size": {
            "type": "string",
            "description": "Trade size",
            "example": "0.5"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "Execution timestamp (UTC)",
            "example": "2025-01-21T10:30:45.123Z"
          },
          "tx_hash": {
            "type": "string",
            "nullable": true,
            "description": "Blockchain transaction hash"
          },
          "trade_id": {
            "type": "integer",
            "format": "int64",
            "nullable": true,
            "description": "Unique trade ID"
          },
          "order_id": {
            "type": "integer",
            "format": "int64",
            "nullable": true,
            "description": "Associated order ID"
          },
          "crossed": {
            "type": "boolean",
            "nullable": true,
            "description": "True if taker (crossed the spread), false if maker"
          },
          "fee": {
            "type": "string",
            "nullable": true,
            "description": "Trading fee amount"
          },
          "fee_token": {
            "type": "string",
            "nullable": true,
            "description": "Fee denomination (e.g., USDC)"
          },
          "closed_pnl": {
            "type": "string",
            "nullable": true,
            "description": "Realized PnL if closing a position"
          },
          "direction": {
            "type": "string",
            "nullable": true,
            "description": "Position direction (e.g., 'Open Long', 'Close Short', 'Long > Short')"
          },
          "start_position": {
            "type": "string",
            "nullable": true,
            "description": "Position size before this trade"
          },
          "user_address": {
            "type": "string",
            "nullable": true,
            "description": "User's wallet address"
          },
          "maker_address": {
            "type": "string",
            "nullable": true,
            "description": "Maker's wallet address (the resting order)"
          },
          "taker_address": {
            "type": "string",
            "nullable": true,
            "description": "Taker's wallet address (crossed the spread)"
          },
          "builder_address": {
            "type": "string",
            "nullable": true,
            "description": "Builder address that routed this order. Present only when the order was placed through a builder."
          },
          "builder_fee": {
            "type": "string",
            "nullable": true,
            "description": "Builder fee charged on this fill, paid to the builder (in quote currency, typically USDC). Present only when builder_address is set."
          },
          "deployer_fee": {
            "type": "string",
            "nullable": true,
            "description": "HIP-3 deployer fee share on this fill (in quote currency). Negative for the maker side (rebate), positive for the taker side. Present only on HIP-3 fills."
          },
          "priority_gas": {
            "type": "number",
            "nullable": true,
            "description": "Priority fee burned in HYPE (not USDC) for write priority on the Hyperliquid validator queue. Independent of builder_fee and deployer_fee — paid to the network, not to a builder or deployer. Present only when the order paid for priority."
          },
          "cloid": {
            "type": "string",
            "nullable": true,
            "description": "Client order ID"
          },
          "twap_id": {
            "type": "integer",
            "nullable": true,
            "description": "TWAP execution ID"
          }
        }
      },
      "Instrument": {
        "type": "object",
        "description": "Trading instrument specification (Hyperliquid)",
        "required": [
          "name",
          "sz_decimals",
          "is_active"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Instrument symbol",
            "example": "BTC"
          },
          "sz_decimals": {
            "type": "integer",
            "description": "Size decimal precision",
            "example": 4
          },
          "max_leverage": {
            "type": "integer",
            "nullable": true,
            "description": "Maximum leverage allowed",
            "example": 50
          },
          "only_isolated": {
            "type": "boolean",
            "nullable": true,
            "description": "If true, only isolated margin mode is allowed"
          },
          "instrument_type": {
            "type": "string",
            "nullable": true,
            "description": "Type of instrument",
            "enum": [
              "perp",
              "spot"
            ],
            "example": "perp"
          },
          "is_active": {
            "type": "boolean",
            "description": "Whether the instrument is currently tradeable",
            "example": true
          }
        }
      },
      "LighterInstrument": {
        "type": "object",
        "description": "Trading instrument specification (Lighter.xyz). Different schema from Hyperliquid Instrument.",
        "required": [
          "symbol",
          "market_id",
          "market_type",
          "status",
          "taker_fee",
          "maker_fee",
          "liquidation_fee",
          "min_base_amount",
          "min_quote_amount",
          "size_decimals",
          "price_decimals",
          "quote_decimals",
          "is_active"
        ],
        "properties": {
          "symbol": {
            "type": "string",
            "description": "Instrument symbol",
            "example": "ETH"
          },
          "market_id": {
            "type": "integer",
            "description": "Unique market identifier",
            "example": 0
          },
          "market_type": {
            "type": "string",
            "description": "Type of market",
            "enum": [
              "perp",
              "spot"
            ],
            "example": "perp"
          },
          "status": {
            "type": "string",
            "description": "Market status",
            "enum": [
              "active",
              "inactive",
              "delisted"
            ],
            "example": "active"
          },
          "taker_fee": {
            "type": "number",
            "description": "Taker fee rate (e.g., 0.0004 = 0.04%)",
            "example": 0.0004
          },
          "maker_fee": {
            "type": "number",
            "description": "Maker fee rate (can be negative for rebates)",
            "example": 0.0001
          },
          "liquidation_fee": {
            "type": "number",
            "description": "Liquidation fee rate",
            "example": 0.005
          },
          "min_base_amount": {
            "type": "number",
            "description": "Minimum order size in base currency",
            "example": 0.001
          },
          "min_quote_amount": {
            "type": "number",
            "description": "Minimum order value in quote currency",
            "example": 1
          },
          "size_decimals": {
            "type": "integer",
            "description": "Size decimal precision",
            "example": 4
          },
          "price_decimals": {
            "type": "integer",
            "description": "Price decimal precision",
            "example": 2
          },
          "quote_decimals": {
            "type": "integer",
            "description": "Quote currency decimal precision",
            "example": 6
          },
          "is_active": {
            "type": "boolean",
            "description": "Whether the instrument is currently tradeable",
            "example": true
          }
        }
      },
      "Hip3Instrument": {
        "type": "object",
        "description": "HIP-3 Builder Perps instrument with latest market data. Derived from live open interest data.",
        "required": [
          "symbol",
          "coin",
          "namespace",
          "ticker"
        ],
        "properties": {
          "symbol": {
            "type": "string",
            "description": "Trading pair symbol",
            "example": "km:US500"
          },
          "coin": {
            "type": "string",
            "description": "Full coin name (e.g., km:US500, xyz:XYZ100) (deprecated, use symbol instead)",
            "example": "km:US500",
            "deprecated": true
          },
          "namespace": {
            "type": "string",
            "description": "Builder namespace (e.g., km, xyz)",
            "example": "km"
          },
          "ticker": {
            "type": "string",
            "description": "Ticker within the namespace (e.g., US500, XYZ100)",
            "example": "US500"
          },
          "mark_price": {
            "type": "number",
            "nullable": true,
            "description": "Latest mark price",
            "example": 5432.1
          },
          "open_interest": {
            "type": "number",
            "nullable": true,
            "description": "Latest open interest",
            "example": 1234567.89
          },
          "mid_price": {
            "type": "number",
            "nullable": true,
            "description": "Latest mid price",
            "example": 5432.05
          },
          "latest_timestamp": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Timestamp of latest data point",
            "example": "2026-02-18T12:00:00.000Z"
          }
        }
      },
      "ApiResponseHip3Instrument": {
        "type": "object",
        "description": "API response wrapping a single HIP-3 instrument",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "$ref": "#/components/schemas/Hip3Instrument"
          },
          "meta": {
            "$ref": "#/components/schemas/ApiMeta"
          }
        }
      },
      "ApiResponseHip3InstrumentArray": {
        "type": "object",
        "description": "API response wrapping an array of HIP-3 instruments",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Hip3Instrument"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ApiMeta"
          }
        }
      },
      "Hip4Outcome": {
        "type": "object",
        "description": "HIP-4 per-side instrument metadata. One row per `#N` coin. Each outcome has two sides: side 0 (Yes) and side 1 (No). Public asset_id formula: `100_000_000 + 10*outcome_id + side`. Coin format: `#<10*outcome_id + side>`.",
        "required": [
          "outcome_id",
          "side",
          "asset_id",
          "coin",
          "symbol"
        ],
        "properties": {
          "outcome_id": {
            "type": "integer",
            "format": "int64",
            "description": "Numeric outcome identifier",
            "example": 0
          },
          "side": {
            "type": "integer",
            "description": "Side index: 0 = Yes, 1 = No",
            "enum": [
              0,
              1
            ],
            "example": 0
          },
          "asset_id": {
            "type": "integer",
            "format": "int64",
            "description": "Public asset ID. Formula: `100_000_000 + 10*outcome_id + side`.",
            "example": 100000000
          },
          "coin": {
            "type": "string",
            "description": "Coin identifier. Returned in `#`-prefixed form. REST paths accept either the bare numeric id (e.g. `0`) or the `#`-prefixed form (e.g. `#0`). Format: `10*outcome_id + side`.",
            "example": "#0"
          },
          "symbol": {
            "type": "string",
            "description": "Same value as `coin`. Provided for consistency with other venues.",
            "example": "#0"
          },
          "name": {
            "type": "string",
            "nullable": true,
            "description": "Human-readable per-side market name",
            "example": "BTC ≥ 78213 by 2026-05-03 06:00 UTC — Yes"
          },
          "description": {
            "type": "string",
            "nullable": true,
            "description": "Pipe-delimited recurring-market metadata",
            "example": "class:priceBinary|underlying:BTC|expiry:20260503-0600|targetPrice:78213|period:1d"
          },
          "side_name": {
            "type": "string",
            "nullable": true,
            "description": "Human label for this side (typically `Yes` or `No`)",
            "example": "Yes"
          },
          "recurring_class": {
            "type": "string",
            "nullable": true,
            "description": "Recurring market class (e.g., `priceBinary`)",
            "example": "priceBinary"
          },
          "recurring_underlying": {
            "type": "string",
            "nullable": true,
            "description": "Underlying asset for recurring price-binary outcomes",
            "example": "BTC"
          },
          "recurring_expiry": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Settlement timestamp (UTC)",
            "example": "2026-05-03T06:00:00Z"
          },
          "recurring_target_px": {
            "type": "number",
            "nullable": true,
            "description": "Target price for the binary outcome",
            "example": 78213
          },
          "recurring_period": {
            "type": "string",
            "nullable": true,
            "description": "Cadence of the recurring market (e.g., `1d`, `1h`)",
            "example": "1d"
          },
          "builder_address": {
            "type": "string",
            "nullable": true,
            "description": "Builder wallet address that deployed the outcome",
            "example": "0x0000000000000000000000000000000000000000"
          },
          "is_settled": {
            "type": "boolean",
            "description": "Whether the outcome has settled. Once settled, the market is no longer subscribed by the ingester but historical data remains queryable.",
            "example": false
          },
          "first_seen_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Timestamp when the side was first ingested",
            "example": "2026-05-02T07:47:00Z"
          },
          "last_updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Timestamp when the side metadata was last updated",
            "example": "2026-05-02T20:25:00Z"
          }
        }
      },
      "Hip4SideSpec": {
        "type": "object",
        "description": "Per-side spec nested in `Hip4OutcomeAggregate.side_specs`. One element per side (typically two: side 0 = Yes, side 1 = No).",
        "required": [
          "side",
          "name",
          "coin",
          "asset_id"
        ],
        "properties": {
          "side": {
            "type": "integer",
            "description": "Side index: 0 = Yes, 1 = No",
            "enum": [
              0,
              1
            ],
            "example": 0
          },
          "name": {
            "type": "string",
            "description": "Human label for this side",
            "example": "Yes"
          },
          "coin": {
            "type": "string",
            "description": "Coin identifier for this side. Returned in `#`-prefixed form. REST paths accept either the bare numeric id (e.g. `0`) or the `#`-prefixed form (e.g. `#0`).",
            "example": "#0"
          },
          "asset_id": {
            "type": "integer",
            "format": "int64",
            "description": "Public asset ID for this side",
            "example": 100000000
          }
        }
      },
      "Hip4AggregatedOi": {
        "type": "object",
        "description": "Derived OI display fields combining both sides of a HIP-4 outcome. Currency is always `USDH` (Hyperliquid's stablecoin). Only populated on `/outcomes/{outcome_id}` (detail), NOT on `/outcomes` (list).",
        "required": [
          "currency"
        ],
        "properties": {
          "side0_open_interest_contracts": {
            "type": "number",
            "nullable": true,
            "description": "Latest open-interest contracts for side 0 (Yes)",
            "example": 568048.0
          },
          "side1_open_interest_contracts": {
            "type": "number",
            "nullable": true,
            "description": "Latest open-interest contracts for side 1 (No)",
            "example": 568048.0
          },
          "outcome_display_open_interest_contracts": {
            "type": "number",
            "nullable": true,
            "description": "Display total: sum of side0 + side1 OI contracts. Use this for outcome-level OI dashboards.",
            "example": 1136096.0
          },
          "paired_set_supply_contracts": {
            "type": "number",
            "nullable": true,
            "description": "Paired-set supply: minimum of side0 and side1 OI contracts. Represents the count of fully collateralized Yes+No pairs in circulation.",
            "example": 568048.0
          },
          "side_supply_parity": {
            "type": "boolean",
            "nullable": true,
            "description": "True when side0 OI equals side1 OI within tolerance. Parity should hold for binary outcomes; a sustained false value indicates ingestion drift.",
            "example": true
          },
          "currency": {
            "type": "string",
            "description": "Notional currency. Always `USDH` for HIP-4.",
            "enum": [
              "USDH"
            ],
            "example": "USDH"
          },
          "as_of": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Latest timestamp across both sides",
            "example": "2026-05-02T20:27:21Z"
          },
          "side0_as_of": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Timestamp of the side 0 OI sample",
            "example": "2026-05-02T20:27:21Z"
          },
          "side1_as_of": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Timestamp of the side 1 OI sample",
            "example": "2026-05-02T20:27:21Z"
          }
        }
      },
      "Hip4OutcomeAggregate": {
        "type": "object",
        "description": "Per-outcome aggregate (both sides combined). Returned by `/outcomes` (list, without `aggregated_oi`) and `/outcomes/{outcome_id}` (detail, with `aggregated_oi` populated).",
        "required": [
          "outcome_id",
          "side_specs",
          "is_settled"
        ],
        "properties": {
          "outcome_id": {
            "type": "integer",
            "format": "int64",
            "description": "Numeric outcome identifier",
            "example": 0
          },
          "name": {
            "type": "string",
            "nullable": true,
            "description": "Human-readable outcome name (without per-side suffix)",
            "example": "BTC ≥ 78213 by 2026-05-03 06:00 UTC"
          },
          "description_raw": {
            "type": "string",
            "nullable": true,
            "description": "Pipe-delimited recurring-market metadata as emitted upstream",
            "example": "class:priceBinary|underlying:BTC|expiry:20260503-0600|targetPrice:78213|period:1d"
          },
          "class": {
            "type": "string",
            "nullable": true,
            "description": "Outcome class (e.g., `priceBinary`)",
            "example": "priceBinary"
          },
          "underlying": {
            "type": "string",
            "nullable": true,
            "description": "Underlying asset for recurring price-binary outcomes",
            "example": "BTC"
          },
          "expiry": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Settlement timestamp (UTC)",
            "example": "2026-05-03T06:00:00Z"
          },
          "target_price": {
            "type": "number",
            "nullable": true,
            "description": "Target price for the binary outcome",
            "example": 78213
          },
          "period": {
            "type": "string",
            "nullable": true,
            "description": "Cadence of the recurring market (e.g., `1d`, `1h`)",
            "example": "1d"
          },
          "side_specs": {
            "type": "array",
            "description": "Per-side specs. Typically two elements: side 0 (Yes) and side 1 (No).",
            "items": {
              "$ref": "#/components/schemas/Hip4SideSpec"
            }
          },
          "is_settled": {
            "type": "boolean",
            "description": "Whether the outcome has settled",
            "example": false
          },
          "status": {
            "type": "string",
            "nullable": true,
            "description": "Lifecycle status (`live`, `settled`, ...)",
            "example": "live"
          },
          "source_seen_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Last time the outcome was seen upstream",
            "example": "2026-05-02T20:25:00Z"
          },
          "aggregated_oi": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Hip4AggregatedOi"
              }
            ],
            "nullable": true,
            "description": "Display/paired/parity OI aggregates. Populated ONLY on the `/outcomes/{outcome_id}` detail response. Omitted (or null) on the `/outcomes` list response."
          }
        }
      },
      "Hip4OpenInterestRecord": {
        "type": "object",
        "description": "HIP-4 per-side open-interest record. Mirrors the HIP-3 OI shape and adds `outcome_id` and `side`. `oracle_price` is omitted for HIP-4 (outcomes have no oracle feed). Note: `mark_price` is an implied probability in [0,1], not a USD price; same field name as perps because Hyperliquid upstream uses `markPx` for both.",
        "required": [
          "coin",
          "symbol",
          "outcome_id",
          "side",
          "timestamp",
          "open_interest"
        ],
        "properties": {
          "coin": {
            "type": "string",
            "description": "`#`-prefixed per-side coin identifier",
            "example": "#0"
          },
          "symbol": {
            "type": "string",
            "description": "Same value as `coin`. Provided for consistency with other venues.",
            "example": "#0"
          },
          "outcome_id": {
            "type": "integer",
            "format": "int64",
            "description": "Numeric outcome identifier",
            "example": 0
          },
          "side": {
            "type": "integer",
            "description": "Side index: 0 = Yes, 1 = No",
            "enum": [
              0,
              1
            ],
            "example": 0
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "Snapshot timestamp (UTC)",
            "example": "2026-05-02T20:27:21Z"
          },
          "open_interest": {
            "type": "string",
            "description": "Open interest in contracts (notional currency: USDH)",
            "example": "568048"
          },
          "mark_price": {
            "type": "string",
            "nullable": true,
            "description": "Implied probability in [0,1], NOT a USD price. Same field name as perps because Hyperliquid upstream uses `markPx` for both.",
            "example": "0.6502"
          },
          "mid_price": {
            "type": "string",
            "nullable": true,
            "description": "Mid price (probability in [0,1])",
            "example": "0.65038"
          }
        }
      },
      "ApiResponseHip4Outcome": {
        "type": "object",
        "description": "API response wrapping a single HIP-4 per-side instrument",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "$ref": "#/components/schemas/Hip4Outcome"
          },
          "meta": {
            "$ref": "#/components/schemas/ApiMeta"
          }
        }
      },
      "ApiResponseHip4OutcomeArray": {
        "type": "object",
        "description": "API response wrapping an array of HIP-4 per-side instruments",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Hip4Outcome"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ApiMeta"
          }
        }
      },
      "ApiResponseHip4OutcomeAggregate": {
        "type": "object",
        "description": "API response wrapping a single HIP-4 outcome aggregate (with `aggregated_oi` populated on the detail endpoint)",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "$ref": "#/components/schemas/Hip4OutcomeAggregate"
          },
          "meta": {
            "$ref": "#/components/schemas/ApiMeta"
          }
        }
      },
      "ApiResponseHip4OutcomeAggregateArray": {
        "type": "object",
        "description": "API response wrapping an array of HIP-4 outcome aggregates (without `aggregated_oi`; use `/outcomes/{outcome_id}` for the detail variant)",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Hip4OutcomeAggregate"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ApiMeta"
          }
        }
      },
      "ApiResponseHip4OpenInterest": {
        "type": "object",
        "description": "API response wrapping a single HIP-4 per-side open-interest record",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "$ref": "#/components/schemas/Hip4OpenInterestRecord"
          },
          "meta": {
            "$ref": "#/components/schemas/ApiMeta"
          }
        }
      },
      "ApiResponseHip4OpenInterestArray": {
        "type": "object",
        "description": "API response wrapping an array of HIP-4 per-side open-interest records",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Hip4OpenInterestRecord"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ApiMeta"
          }
        }
      },
      "OpenInterest": {
        "type": "object",
        "description": "Open interest snapshot with market context",
        "required": [
          "symbol",
          "coin",
          "timestamp",
          "open_interest"
        ],
        "properties": {
          "symbol": {
            "type": "string",
            "description": "Trading pair symbol",
            "example": "BTC"
          },
          "coin": {
            "type": "string",
            "description": "Trading pair symbol (deprecated, use symbol instead)",
            "example": "BTC",
            "deprecated": true
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "Snapshot timestamp (UTC)",
            "example": "2025-01-21T10:30:00.000Z"
          },
          "open_interest": {
            "type": "string",
            "description": "Total open interest in contracts",
            "example": "500000.00"
          },
          "mark_price": {
            "type": "string",
            "nullable": true,
            "description": "Mark price used for liquidations",
            "example": "42500.50"
          },
          "oracle_price": {
            "type": "string",
            "nullable": true,
            "description": "Oracle price from external feed",
            "example": "42498.25"
          },
          "day_ntl_volume": {
            "type": "string",
            "nullable": true,
            "description": "24-hour notional volume",
            "example": "10000000.00"
          },
          "prev_day_price": {
            "type": "string",
            "nullable": true,
            "description": "Price 24 hours ago",
            "example": "42000.00"
          },
          "mid_price": {
            "type": "string",
            "nullable": true,
            "description": "Current mid price",
            "example": "42500.75"
          },
          "impact_bid_price": {
            "type": "string",
            "nullable": true,
            "description": "Impact bid price for liquidations"
          },
          "impact_ask_price": {
            "type": "string",
            "nullable": true,
            "description": "Impact ask price for liquidations"
          }
        }
      },
      "FundingRate": {
        "type": "object",
        "description": "Funding rate record",
        "required": [
          "symbol",
          "coin",
          "timestamp",
          "funding_rate"
        ],
        "properties": {
          "symbol": {
            "type": "string",
            "description": "Trading pair symbol",
            "example": "BTC"
          },
          "coin": {
            "type": "string",
            "description": "Trading pair symbol (deprecated, use symbol instead)",
            "example": "BTC",
            "deprecated": true
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "Funding timestamp (UTC)",
            "example": "2025-01-21T08:00:00.000Z"
          },
          "funding_rate": {
            "type": "string",
            "description": "Funding rate as decimal (e.g., 0.0001 = 0.01%)",
            "example": "0.00025"
          },
          "premium": {
            "type": "string",
            "nullable": true,
            "description": "Premium component of funding rate",
            "example": "0.0005"
          }
        }
      },
      "Candle": {
        "type": "object",
        "description": "OHLCV candle data",
        "required": [
          "timestamp",
          "open",
          "high",
          "low",
          "close",
          "volume"
        ],
        "properties": {
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "Candle start timestamp (ISO 8601 UTC)",
            "example": "2026-01-01T12:00:00Z"
          },
          "open": {
            "type": "number",
            "format": "double",
            "description": "Opening price",
            "example": 42500.5
          },
          "high": {
            "type": "number",
            "format": "double",
            "description": "Highest price during interval",
            "example": 42750
          },
          "low": {
            "type": "number",
            "format": "double",
            "description": "Lowest price during interval",
            "example": 42300.25
          },
          "close": {
            "type": "number",
            "format": "double",
            "description": "Closing price",
            "example": 42650.75
          },
          "volume": {
            "type": "number",
            "format": "double",
            "description": "Trading volume in base asset",
            "example": 1250.5
          },
          "quote_volume": {
            "type": "number",
            "format": "double",
            "description": "Trading volume in quote asset (USD)",
            "example": 53187500
          },
          "trade_count": {
            "type": "integer",
            "description": "Number of trades in interval",
            "example": 4520
          }
        }
      },
      "ApiResponseCandleArray": {
        "type": "object",
        "description": "API response containing an array of candle data",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Candle"
            }
          },
          "meta": {
            "type": "object",
            "properties": {
              "count": {
                "type": "integer",
                "description": "Number of records returned"
              },
              "next_cursor": {
                "type": "string",
                "nullable": true,
                "description": "Cursor for pagination"
              }
            }
          }
        }
      },
      "Liquidation": {
        "type": "object",
        "description": "Liquidation event",
        "required": [
          "symbol",
          "coin",
          "timestamp",
          "liquidated_user",
          "liquidator_user",
          "price",
          "size",
          "side"
        ],
        "properties": {
          "symbol": {
            "type": "string",
            "description": "Trading pair symbol",
            "example": "BTC"
          },
          "coin": {
            "type": "string",
            "description": "Trading pair symbol (deprecated, use symbol instead)",
            "example": "BTC",
            "deprecated": true
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "Liquidation timestamp (UTC)",
            "example": "2025-05-21T10:30:00.000Z"
          },
          "liquidated_user": {
            "type": "string",
            "description": "Address of the user who was liquidated",
            "example": "0x84eec0068b37919cc8f13d7454073ac167374cc0"
          },
          "liquidator_user": {
            "type": "string",
            "description": "Address of the liquidator (counterparty)",
            "example": "0x4d969e59b312970cc07af266938a4433ccae0b4c"
          },
          "price": {
            "type": "string",
            "description": "Price at which the liquidation was executed",
            "example": "42500.50"
          },
          "size": {
            "type": "string",
            "description": "Size of the liquidated position",
            "example": "1.5"
          },
          "side": {
            "type": "string",
            "description": "Exchange side code for the liquidation-related fill (`A`/`B`). Use `direction` for close/open interpretation, especially on HIP-3.",
            "example": "B"
          },
          "mark_price": {
            "type": "string",
            "nullable": true,
            "description": "Mark price at time of liquidation",
            "example": "42480.25"
          },
          "closed_pnl": {
            "type": "string",
            "nullable": true,
            "description": "Realized PnL from the liquidation (usually negative)",
            "example": "-1250.50"
          },
          "direction": {
            "type": "string",
            "nullable": true,
            "description": "Upstream direction label (for example `Close Long`, `Close Short`; HIP-3 can also emit `Open Long`, `Open Short`, or rare unclassified values such as `Long > Short`)",
            "example": "Close Long"
          },
          "trade_id": {
            "type": "integer",
            "format": "int64",
            "nullable": true,
            "description": "Trade ID for this liquidation",
            "example": 1234567890
          },
          "tx_hash": {
            "type": "string",
            "nullable": true,
            "description": "Blockchain transaction hash",
            "example": "0xe266d353038e679c5d7e042433054f0000e1d8e52f7860ecda84573b9b5a02ca"
          }
        }
      },
      "ApiResponseLiquidationArray": {
        "type": "object",
        "description": "API response containing an array of liquidation events",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Liquidation"
            }
          },
          "meta": {
            "type": "object",
            "properties": {
              "count": {
                "type": "integer",
                "description": "Number of records returned"
              },
              "next_cursor": {
                "type": "string",
                "nullable": true,
                "description": "Cursor for pagination (format: timestamp_tradeId)"
              }
            }
          }
        }
      },
      "LiquidationVolume": {
        "type": "object",
        "description": "Aggregated liquidation volume for a time bucket",
        "required": [
          "symbol",
          "coin",
          "timestamp",
          "total_usd",
          "long_usd",
          "short_usd",
          "count",
          "long_count",
          "short_count"
        ],
        "properties": {
          "symbol": {
            "type": "string",
            "description": "Trading pair symbol",
            "example": "BTC"
          },
          "coin": {
            "type": "string",
            "description": "Trading pair symbol (deprecated, use symbol instead)",
            "example": "BTC",
            "deprecated": true
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "Bucket start timestamp (UTC)",
            "example": "2025-05-21T10:00:00.000Z"
          },
          "total_usd": {
            "type": "number",
            "description": "Total liquidation volume in USD",
            "example": 1250000.5
          },
          "long_usd": {
            "type": "number",
            "description": "Long liquidation volume in USD",
            "example": 750000.25
          },
          "short_usd": {
            "type": "number",
            "description": "Short liquidation volume in USD",
            "example": 500000.25
          },
          "count": {
            "type": "integer",
            "description": "Total number of liquidations",
            "example": 42
          },
          "long_count": {
            "type": "integer",
            "description": "Number of long liquidations",
            "example": 25
          },
          "short_count": {
            "type": "integer",
            "description": "Number of short liquidations",
            "example": 17
          }
        }
      },
      "ApiResponseLiquidationVolumeArray": {
        "type": "object",
        "description": "API response containing an array of aggregated liquidation volumes",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LiquidationVolume"
            }
          },
          "meta": {
            "type": "object",
            "properties": {
              "count": {
                "type": "integer",
                "description": "Number of records returned"
              },
              "next_cursor": {
                "type": "string",
                "nullable": true,
                "description": "Cursor for pagination"
              }
            }
          }
        }
      },
      "DataTypeFreshness": {
        "type": "object",
        "description": "Freshness information for a single data type",
        "properties": {
          "last_updated": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When this data type was last updated for the coin",
            "example": "2026-02-23T12:00:00.000Z"
          },
          "lag_ms": {
            "type": "integer",
            "nullable": true,
            "description": "Current lag in milliseconds between now and last update",
            "example": 1200
          }
        }
      },
      "CoinFreshness": {
        "type": "object",
        "description": "Data freshness for all data types for a specific coin",
        "required": [
          "symbol",
          "coin",
          "exchange",
          "measured_at"
        ],
        "properties": {
          "symbol": {
            "type": "string",
            "description": "Trading pair symbol",
            "example": "BTC"
          },
          "coin": {
            "type": "string",
            "description": "Trading pair symbol (deprecated, use symbol instead)",
            "example": "BTC",
            "deprecated": true
          },
          "exchange": {
            "type": "string",
            "description": "Exchange name",
            "example": "hyperliquid"
          },
          "measured_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the freshness was measured",
            "example": "2026-02-23T12:00:00.000Z"
          },
          "orderbook": {
            "$ref": "#/components/schemas/DataTypeFreshness"
          },
          "trades": {
            "$ref": "#/components/schemas/DataTypeFreshness"
          },
          "funding": {
            "$ref": "#/components/schemas/DataTypeFreshness"
          },
          "open_interest": {
            "$ref": "#/components/schemas/DataTypeFreshness"
          },
          "liquidations": {
            "$ref": "#/components/schemas/DataTypeFreshness"
          }
        }
      },
      "ApiResponseCoinFreshness": {
        "type": "object",
        "description": "API response wrapping coin freshness data",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "$ref": "#/components/schemas/CoinFreshness"
          },
          "meta": {
            "$ref": "#/components/schemas/ApiMeta"
          }
        }
      },
      "CoinSummary": {
        "type": "object",
        "description": "Combined market summary including price, funding, OI, volume, and liquidation data",
        "required": [
          "symbol",
          "coin",
          "timestamp"
        ],
        "properties": {
          "symbol": {
            "type": "string",
            "description": "Trading pair symbol",
            "example": "BTC"
          },
          "coin": {
            "type": "string",
            "description": "Trading pair symbol (deprecated, use symbol instead)",
            "example": "BTC",
            "deprecated": true
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "Summary timestamp (UTC)",
            "example": "2026-02-23T12:00:00.000Z"
          },
          "mark_price": {
            "type": "string",
            "nullable": true,
            "description": "Current mark price",
            "example": "95000.50"
          },
          "oracle_price": {
            "type": "string",
            "nullable": true,
            "description": "Current oracle price",
            "example": "94998.25"
          },
          "mid_price": {
            "type": "string",
            "nullable": true,
            "description": "Current mid price",
            "example": "95000.00"
          },
          "funding_rate": {
            "type": "string",
            "nullable": true,
            "description": "Current funding rate",
            "example": "0.00025"
          },
          "premium": {
            "type": "string",
            "nullable": true,
            "description": "Current premium",
            "example": "0.0005"
          },
          "open_interest": {
            "type": "string",
            "nullable": true,
            "description": "Current open interest",
            "example": "500000.00"
          },
          "volume_24h": {
            "type": "string",
            "nullable": true,
            "description": "24-hour notional volume",
            "example": "10000000.00"
          },
          "liquidation_volume_24h": {
            "type": "number",
            "nullable": true,
            "description": "Total 24h liquidation volume in USD",
            "example": 2500000
          },
          "long_liquidation_volume_24h": {
            "type": "number",
            "nullable": true,
            "description": "Long 24h liquidation volume in USD",
            "example": 1500000
          },
          "short_liquidation_volume_24h": {
            "type": "number",
            "nullable": true,
            "description": "Short 24h liquidation volume in USD",
            "example": 1000000
          }
        }
      },
      "ApiResponseCoinSummary": {
        "type": "object",
        "description": "API response wrapping a market summary",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "$ref": "#/components/schemas/CoinSummary"
          },
          "meta": {
            "$ref": "#/components/schemas/ApiMeta"
          }
        }
      },
      "PriceSnapshot": {
        "type": "object",
        "description": "Price snapshot with mark, oracle, and mid prices",
        "required": [
          "timestamp"
        ],
        "properties": {
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "Snapshot timestamp (UTC)",
            "example": "2026-02-23T12:00:00.000Z"
          },
          "mark_price": {
            "type": "string",
            "nullable": true,
            "description": "Mark price",
            "example": "95000.50"
          },
          "oracle_price": {
            "type": "string",
            "nullable": true,
            "description": "Oracle price",
            "example": "94998.25"
          },
          "mid_price": {
            "type": "string",
            "nullable": true,
            "description": "Mid price",
            "example": "95000.00"
          }
        }
      },
      "ApiResponsePriceSnapshotArray": {
        "type": "object",
        "description": "API response containing an array of price snapshots",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PriceSnapshot"
            }
          },
          "meta": {
            "type": "object",
            "properties": {
              "count": {
                "type": "integer",
                "description": "Number of records returned"
              },
              "next_cursor": {
                "type": "string",
                "nullable": true,
                "description": "Cursor for pagination"
              }
            }
          }
        }
      },
      "StatusResponse": {
        "type": "object",
        "description": "Overall system status",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "operational",
              "degraded",
              "outage",
              "maintenance"
            ],
            "description": "Overall system status"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When this status was computed"
          },
          "exchanges": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/ExchangeStatus"
            },
            "description": "Per-exchange status"
          },
          "data_types": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/DataTypeStatus"
            },
            "description": "Per-data-type status"
          },
          "active_incidents": {
            "type": "integer",
            "description": "Number of active incidents"
          }
        }
      },
      "ExchangeStatus": {
        "type": "object",
        "description": "Status of a single exchange",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "operational",
              "degraded",
              "outage",
              "maintenance"
            ]
          },
          "last_data_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Timestamp of last received data"
          },
          "latency_ms": {
            "type": "integer",
            "nullable": true,
            "description": "Current latency in milliseconds"
          }
        }
      },
      "DataTypeStatus": {
        "type": "object",
        "description": "Status of a data type",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "operational",
              "degraded",
              "outage",
              "maintenance"
            ]
          },
          "completeness_24h": {
            "type": "number",
            "description": "Data completeness over last 24 hours (0-100)"
          }
        }
      },
      "CoverageResponse": {
        "type": "object",
        "description": "Overall coverage response",
        "properties": {
          "exchanges": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExchangeCoverageResponse"
            }
          }
        }
      },
      "ExchangeCoverageResponse": {
        "type": "object",
        "description": "Coverage for a single exchange",
        "properties": {
          "exchange": {
            "type": "string",
            "description": "Exchange name"
          },
          "data_types": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/DataTypeCoverage"
            }
          }
        }
      },
      "DataTypeCoverage": {
        "type": "object",
        "description": "Coverage for a data type",
        "properties": {
          "earliest": {
            "type": "string",
            "format": "date-time",
            "description": "Earliest available data timestamp"
          },
          "latest": {
            "type": "string",
            "format": "date-time",
            "description": "Latest available data timestamp"
          },
          "total_records": {
            "type": "integer",
            "format": "int64",
            "description": "Total number of records"
          },
          "symbols": {
            "type": "integer",
            "description": "Number of symbols with data"
          },
          "resolution": {
            "type": "string",
            "nullable": true,
            "description": "Data resolution (e.g., '1.2s', '1m')"
          },
          "lag": {
            "type": "string",
            "nullable": true,
            "description": "Current data lag"
          },
          "completeness": {
            "type": "number",
            "description": "Completeness percentage (0-100)"
          }
        }
      },
      "SymbolCoverageResponse": {
        "type": "object",
        "description": "Per-symbol coverage response with gap detection",
        "required": [
          "exchange",
          "symbol",
          "data_types"
        ],
        "properties": {
          "exchange": {
            "type": "string",
            "description": "Exchange name"
          },
          "symbol": {
            "type": "string",
            "description": "Symbol name"
          },
          "data_types": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/SymbolDataTypeCoverage"
            }
          }
        }
      },
      "SymbolDataTypeCoverage": {
        "type": "object",
        "description": "Coverage for a symbol and data type",
        "required": [
          "earliest",
          "latest",
          "total_records",
          "completeness",
          "gaps"
        ],
        "properties": {
          "earliest": {
            "type": "string",
            "format": "date-time"
          },
          "latest": {
            "type": "string",
            "format": "date-time"
          },
          "total_records": {
            "type": "integer",
            "format": "int64"
          },
          "completeness": {
            "type": "number",
            "description": "24-hour completeness percentage (0-100)"
          },
          "historical_coverage": {
            "type": "number",
            "description": "Historical coverage percentage (0-100) based on hours with data / total hours in range",
            "nullable": true
          },
          "gaps": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CoverageGap"
            },
            "description": "Detected data gaps within the requested time window"
          },
          "cadence": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DataCadence"
              }
            ],
            "nullable": true,
            "description": "Empirical data cadence measurement (present when sufficient data exists)"
          }
        }
      },
      "DataCadence": {
        "type": "object",
        "description": "Empirical data cadence measurement based on last 7 days of data",
        "required": [
          "median_interval_seconds",
          "p95_interval_seconds",
          "sample_count"
        ],
        "properties": {
          "median_interval_seconds": {
            "type": "number",
            "description": "Median interval between consecutive records in seconds"
          },
          "p95_interval_seconds": {
            "type": "number",
            "description": "95th percentile interval between consecutive records in seconds"
          },
          "sample_count": {
            "type": "integer",
            "format": "int64",
            "description": "Number of intervals sampled for this measurement"
          }
        }
      },
      "CoverageGap": {
        "type": "object",
        "description": "A gap in data coverage",
        "required": [
          "start",
          "end",
          "duration_minutes"
        ],
        "properties": {
          "start": {
            "type": "string",
            "format": "date-time",
            "description": "Start of gap (last data before gap)"
          },
          "end": {
            "type": "string",
            "format": "date-time",
            "description": "End of gap (first data after gap)"
          },
          "duration_minutes": {
            "type": "integer",
            "description": "Gap duration in minutes"
          }
        }
      },
      "IncidentsResponse": {
        "type": "object",
        "description": "Incidents list response",
        "properties": {
          "incidents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Incident"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      },
      "Incident": {
        "type": "object",
        "description": "Data quality incident",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique incident ID"
          },
          "status": {
            "type": "string",
            "enum": [
              "open",
              "investigating",
              "identified",
              "monitoring",
              "resolved"
            ]
          },
          "severity": {
            "type": "string",
            "enum": [
              "minor",
              "major",
              "critical"
            ]
          },
          "exchange": {
            "type": "string",
            "nullable": true,
            "description": "Affected exchange"
          },
          "data_types": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Affected data types"
          },
          "symbols_affected": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Affected symbols"
          },
          "started_at": {
            "type": "string",
            "format": "date-time"
          },
          "resolved_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "duration_minutes": {
            "type": "integer",
            "nullable": true
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "root_cause": {
            "type": "string",
            "nullable": true
          },
          "resolution": {
            "type": "string",
            "nullable": true
          },
          "records_affected": {
            "type": "integer",
            "format": "int64",
            "nullable": true
          },
          "records_recovered": {
            "type": "integer",
            "format": "int64",
            "nullable": true
          }
        }
      },
      "Pagination": {
        "type": "object",
        "description": "Pagination info",
        "properties": {
          "total": {
            "type": "integer",
            "description": "Total number of items"
          },
          "limit": {
            "type": "integer",
            "description": "Page size limit"
          },
          "offset": {
            "type": "integer",
            "description": "Current offset"
          }
        }
      },
      "LatencyResponse": {
        "type": "object",
        "description": "Latency metrics response",
        "properties": {
          "measured_at": {
            "type": "string",
            "format": "date-time"
          },
          "exchanges": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/ExchangeLatency"
            }
          }
        }
      },
      "ExchangeLatency": {
        "type": "object",
        "description": "Latency metrics for an exchange",
        "properties": {
          "websocket": {
            "allOf": [
              {
                "$ref": "#/components/schemas/WebSocketLatency"
              }
            ],
            "nullable": true
          },
          "rest_api": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ApiLatency"
              }
            ],
            "nullable": true
          },
          "data_freshness": {
            "$ref": "#/components/schemas/DataFreshness"
          }
        }
      },
      "WebSocketLatency": {
        "type": "object",
        "properties": {
          "current_ms": {
            "type": "integer"
          },
          "avg_1h_ms": {
            "type": "integer"
          },
          "avg_24h_ms": {
            "type": "integer"
          },
          "p99_24h_ms": {
            "type": "integer",
            "nullable": true
          }
        }
      },
      "ApiLatency": {
        "type": "object",
        "properties": {
          "current_ms": {
            "type": "integer"
          },
          "avg_1h_ms": {
            "type": "integer"
          },
          "avg_24h_ms": {
            "type": "integer"
          }
        }
      },
      "DataFreshness": {
        "type": "object",
        "description": "Data freshness metrics",
        "properties": {
          "orderbook_lag_ms": {
            "type": "integer",
            "nullable": true
          },
          "fills_lag_ms": {
            "type": "integer",
            "nullable": true
          },
          "funding_lag_ms": {
            "type": "integer",
            "nullable": true
          },
          "oi_lag_ms": {
            "type": "integer",
            "nullable": true
          }
        }
      },
      "SlaResponse": {
        "type": "object",
        "description": "SLA compliance response",
        "properties": {
          "period": {
            "type": "string",
            "description": "Period covered (e.g., '2026-01')"
          },
          "sla_targets": {
            "$ref": "#/components/schemas/SlaTargets"
          },
          "actual": {
            "$ref": "#/components/schemas/SlaActual"
          },
          "incidents_this_period": {
            "type": "integer"
          },
          "total_downtime_minutes": {
            "type": "integer"
          }
        }
      },
      "SlaTargets": {
        "type": "object",
        "properties": {
          "uptime": {
            "type": "number",
            "description": "Uptime target percentage"
          },
          "data_completeness": {
            "type": "number",
            "description": "Data completeness target percentage"
          },
          "api_latency_p99_ms": {
            "type": "integer",
            "description": "API P99 latency target in ms"
          }
        }
      },
      "SlaActual": {
        "type": "object",
        "properties": {
          "uptime": {
            "type": "number"
          },
          "uptime_status": {
            "type": "string",
            "enum": [
              "met",
              "missed"
            ]
          },
          "data_completeness": {
            "$ref": "#/components/schemas/CompletenessMetrics"
          },
          "completeness_status": {
            "type": "string",
            "enum": [
              "met",
              "missed"
            ]
          },
          "api_latency_p99_ms": {
            "type": "integer"
          },
          "latency_status": {
            "type": "string",
            "enum": [
              "met",
              "missed"
            ]
          }
        }
      },
      "CompletenessMetrics": {
        "type": "object",
        "properties": {
          "orderbook": {
            "type": "number"
          },
          "fills": {
            "type": "number"
          },
          "funding": {
            "type": "number"
          },
          "overall": {
            "type": "number"
          }
        }
      },
      "Web3ChallengeRequest": {
        "type": "object",
        "required": [
          "address"
        ],
        "properties": {
          "address": {
            "type": "string",
            "description": "Ethereum wallet address",
            "example": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18"
          }
        }
      },
      "Web3ChallengeResponse": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "description": "SIWE message to sign with personal_sign (EIP-191)"
          },
          "nonce": {
            "type": "string",
            "description": "Single-use nonce (expires after 10 minutes)"
          }
        }
      },
      "Web3SignupRequest": {
        "type": "object",
        "required": [
          "message",
          "signature"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "The SIWE message from the challenge endpoint"
          },
          "signature": {
            "type": "string",
            "description": "Hex-encoded signature from personal_sign (0x-prefixed)",
            "example": "0x..."
          }
        }
      },
      "Web3SignupResponse": {
        "type": "object",
        "properties": {
          "api_key": {
            "type": "string",
            "description": "The generated API key",
            "example": "0xa_live_abc123..."
          },
          "tier": {
            "type": "string",
            "description": "Account tier",
            "example": "free"
          },
          "wallet_address": {
            "type": "string",
            "description": "The wallet address that owns this key"
          }
        }
      },
      "Web3KeysRequest": {
        "type": "object",
        "required": [
          "message",
          "signature"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "The SIWE message from the challenge endpoint"
          },
          "signature": {
            "type": "string",
            "description": "Hex-encoded signature from personal_sign (0x-prefixed)"
          }
        }
      },
      "Web3KeysResponse": {
        "type": "object",
        "properties": {
          "keys": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Web3ApiKey"
            }
          },
          "wallet_address": {
            "type": "string",
            "description": "The wallet address"
          }
        }
      },
      "Web3ApiKey": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique key ID"
          },
          "name": {
            "type": "string",
            "description": "Key name"
          },
          "key_prefix": {
            "type": "string",
            "description": "First characters of the key for identification",
            "example": "0xa_live_abc1"
          },
          "is_active": {
            "type": "boolean",
            "description": "Whether the key is currently active"
          },
          "last_used_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Last usage timestamp"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Creation timestamp"
          }
        }
      },
      "Web3RevokeRequest": {
        "type": "object",
        "required": [
          "message",
          "signature",
          "key_id"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "The SIWE message from the challenge endpoint"
          },
          "signature": {
            "type": "string",
            "description": "Hex-encoded signature from personal_sign (0x-prefixed)"
          },
          "key_id": {
            "type": "string",
            "format": "uuid",
            "description": "UUID of the key to revoke"
          }
        }
      },
      "Web3RevokeResponse": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "description": "Confirmation message",
            "example": "API key revoked successfully"
          },
          "wallet_address": {
            "type": "string",
            "description": "The wallet address that owned the key"
          }
        }
      },
      "Web3SubscribeRequest": {
        "type": "object",
        "required": [
          "tier"
        ],
        "properties": {
          "tier": {
            "type": "string",
            "enum": [
              "build",
              "pro"
            ],
            "description": "Subscription tier to purchase",
            "example": "build"
          }
        }
      },
      "Web3SubscribeResponse": {
        "type": "object",
        "properties": {
          "api_key": {
            "type": "string",
            "description": "The generated API key for the new subscription",
            "example": "0xa_..."
          },
          "tier": {
            "type": "string",
            "description": "The subscription tier activated",
            "example": "build"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Subscription expiration date (30 days from purchase)"
          },
          "wallet_address": {
            "type": "string",
            "description": "The wallet address associated with the subscription"
          },
          "tx_hash": {
            "type": "string",
            "description": "On-chain transaction hash for the USDC transfer (if settled)",
            "nullable": true
          }
        }
      },
      "Error": {
        "type": "object",
        "description": "Error response",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code"
          },
          "error": {
            "type": "string",
            "description": "Error message"
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Authentication required",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "code": 401,
              "error": "Missing or invalid API key. Provide X-API-Key header."
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "code": 404,
              "error": "Resource not found"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit exceeded",
        "headers": {
          "X-RateLimit-Limit": {
            "schema": {
              "type": "integer"
            },
            "description": "Requests per second limit"
          },
          "X-RateLimit-Remaining": {
            "schema": {
              "type": "integer"
            },
            "description": "Remaining requests this second"
          },
          "X-RateLimit-Reset": {
            "schema": {
              "type": "integer"
            },
            "description": "Unix timestamp when limit resets"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "code": 429,
              "error": "Rate limit exceeded"
            }
          }
        }
      },
      "BadRequest": {
        "description": "Invalid request",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "code": 400,
              "error": "Invalid request parameters"
            }
          }
        }
      }
    }
  }
}