--- title: "Response Schemas | 0xArchive Docs" description: "Review 0xArchive response schemas, field names, nested objects, examples, error shapes, and payload conventions before integration." canonical_url: "https://www.0xarchive.io/docs/schemas/" markdown_url: "https://www.0xarchive.io/docs/schemas.md" route: "/docs/schemas" robots: "index, follow" generated_from: "prerendered_html" --- # Response Schemas Field names, nested objects, and example payloads for the main response shapes. Covers Market state, history, depth, order flow Use it for Types, validation, QA Every venue route returns the same envelope: a top-level success flag, a data body, and a meta block. Cursor pagination lives on the next cursor inside meta. Schemas below show the full response shape. Expand the data field to see payload fields and meta to see pagination details. Data Quality routes return their own top-level shape and are documented separately. ## Response envelope Standard envelope for every venue route. `data` is an object for snapshots and an array for series and history. Standard envelope Every /v1/{venue}/* route returns this shape. Standard envelope JSON ``` { "success": true, "data": [ /* one item per row */ ], "meta": { "count": 1000, "next_cursor": "1761840000596_907964252522803", "request_id": "4d1fe223-53e7-498d-a54a-4fb2f9314734" } } ``` | Field | Description | | --- | --- | | `success` | Always `true` on a 2xx response. Errors return `success: false` with an `error` field. | | `data` | Payload. Object for single-snapshot routes (`/orderbook/:symbol`, `/summary/:symbol`) and an array for series and history routes. | | `meta.count` | Number of items returned in `data`. | | `meta.next_cursor` | Cursor for the next page on paginated routes. **Missing means you have reached the final page.** | | `meta.request_id` | UUID for support traceability — log it next to errors. | ## Cursor pagination Paginated routes (history, trades, candles, liquidations, order flow, etc.) return up to `limit` items per page along with `meta.next_cursor`. Pass that cursor on the next request to fetch the next page. The cursor is opaque — do not parse it. Loop pattern Keep calling until meta.next_cursor is missing. The cursor encodes both the boundary and any tie-breaking — passing it back guarantees no overlaps and no skipped rows. ``` import requests API = "https://api.0xarchive.io" HEADERS = {"X-API-Key": "YOUR_KEY"} cursor = None while True: params = {"start": 1761840000000, "end": 1761926400000, "limit": 1000} if cursor: params["cursor"] = cursor r = requests.get(f"{API}/v1/hyperliquid/trades/BTC", headers=HEADERS, params=params) body = r.json() for trade in body["data"]: process(trade) cursor = body["meta"].get("next_cursor") if not cursor: break # last page reached ``` | Concept | How it behaves | | --- | --- | | `limit` | Page size. Default 100, max 1000 on most routes. Larger pages reduce round trips. | | `cursor` | Only set this on the second request and beyond. Pass `meta.next_cursor` from the previous response verbatim. | | Stop condition | When the response omits `meta.next_cursor`, you have reached the end of the requested `start` / `end` window. | | Idempotence | Cursors are stable across retries within the same window. A 5xx that returns the same cursor is safe to retry. | | DQ incidents | Data Quality incidents use `limit` / `offset` instead of cursors — see the Data Quality schemas below. | ## Market state Single-snapshot payloads for books, current pricing, funding, and open interest. ### Order Book GET /v1/{hyperliquid|lighter|hyperliquid/hip3|hyperliquid/hip4}/orderbook/:symbol Schema success boolean required Always `true` on a 2xx response. Errors return `success: false` with an `error` field. true data object required Response payload. symbol string required Trading pair symbol (preferred) "BTC" coin string required Trading pair symbol (deprecated, use symbol) "BTC" timestamp string required Snapshot timestamp (ISO 8601) "2026-01-01T12:00:00Z" bids array required Bid price levels (best bid first) PriceLevel object px string required Price at this level "42150.50" sz string required Total size at this level "2.5" n integer required Number of orders 5 asks array required Ask price levels (best ask first) PriceLevel object px string required Price at this level "42151.00" sz string required Total size at this level "1.8" n integer required Number of orders 3 mid_price string Mid price (best bid + best ask) / 2 "42150.75" spread string Spread in absolute terms "0.50" spread_bps string Spread in basis points "1.19" meta object required Response metadata. Inspect this to drive cursor pagination and trace requests. count integer required Number of items returned. For object responses, always 1. 1 request_id string required UUID for this request. Include it when contacting support so we can find the call in our logs. "4d1fe223-53e7-498d-a54a-4fb2f9314734" Example ``` { "success": true, "data": { "coin": "BTC", "symbol": "BTC", "timestamp": "2026-01-01T12:00:00Z", "bids": [ { "px": "42150.50", "sz": "2.5", "n": 5 }, { "px": "42150.00", "sz": "5.2", "n": 8 } ], "asks": [ { "px": "42151.00", "sz": "1.8", "n": 3 }, { "px": "42151.50", "sz": "3.1", "n": 4 } ], "mid_price": "42150.75", "spread": "0.50", "spread_bps": "1.19" }, "meta": { "count": 1, "request_id": "4d1fe223-53e7-498d-a54a-4fb2f9314734" } } ``` Copy ### Symbol Summary GET /v1/{venue}/summary/:symbol Schema success boolean required Always `true` on a 2xx response. Errors return `success: false` with an `error` field. true data object required Response payload. symbol string required Trading pair symbol (preferred) "BTC" coin string required Trading pair symbol (deprecated, use symbol) "BTC" timestamp string required Summary timestamp (ISO 8601) "2026-01-01T12:00:00Z" mark_price string Current mark price "42150.75" oracle_price string Current oracle price "42148.50" mid_price string Current mid price (Hyperliquid/HIP-3/HIP-4 only; HIP-4 mid_price is implied probability in [0,1]) "42150.75" open_interest string Total open interest "12500.5" funding_rate string Current funding rate "0.0001" premium string Funding premium (Hyperliquid/HIP-3 only) "0.00005" volume_24h string 24h notional volume (Hyperliquid only) "1250000000" liquidation_volume_24h number 24h liquidation volume (Hyperliquid only) 5000000 long_liquidation_volume_24h number 24h long liquidation volume 3000000 short_liquidation_volume_24h number 24h short liquidation volume 2000000 meta object required Response metadata. Inspect this to drive cursor pagination and trace requests. count integer required Number of items returned. For object responses, always 1. 1 request_id string required UUID for this request. Include it when contacting support so we can find the call in our logs. "4d1fe223-53e7-498d-a54a-4fb2f9314734" Example ``` { "success": true, "data": { "coin": "BTC", "symbol": "BTC", "timestamp": "2026-01-01T12:00:00Z", "mark_price": "42150.75", "oracle_price": "42148.50", "mid_price": "42150.75", "open_interest": "12500.5", "funding_rate": "0.0001", "premium": "0.00005", "volume_24h": "1250000000", "liquidation_volume_24h": 5000000 }, "meta": { "count": 1, "request_id": "4d1fe223-53e7-498d-a54a-4fb2f9314734" } } ``` Copy ### Open Interest (current) GET /v1/{venue}/openinterest/:symbol/current Schema success boolean required Always `true` on a 2xx response. Errors return `success: false` with an `error` field. true data object required Response payload. symbol string required Trading pair symbol (preferred) "BTC" coin string required Trading pair symbol (deprecated, use symbol) "BTC" timestamp string required Snapshot timestamp (ISO 8601) "2026-01-01T12:00:00Z" open_interest string required Total open interest in contracts "12500.5" mark_price string Mark price for liquidations on Hyperliquid/HIP-3. On HIP-4 this is implied probability in [0,1], NOT a USD price (we mirror Hyperliquid upstream naming). "42150.75" oracle_price string Oracle price from external feed (omitted on HIP-4 — outcome markets have no oracle feed) "42148.50" day_ntl_volume string 24-hour notional volume "1250000000" prev_day_price string Price 24 hours ago "41500.00" mid_price string Current mid price (HIP-4: implied probability in [0,1]) "42150.75" impact_bid_price string Best bid price after applying impact size — used by Hyperliquid for funding calculations "42150.00" impact_ask_price string Best ask price after applying impact size — used by Hyperliquid for funding calculations "42151.50" meta object required Response metadata. Inspect this to drive cursor pagination and trace requests. count integer required Number of items returned. For object responses, always 1. 1 request_id string required UUID for this request. Include it when contacting support so we can find the call in our logs. "4d1fe223-53e7-498d-a54a-4fb2f9314734" Example ``` { "success": true, "data": { "coin": "BTC", "symbol": "BTC", "timestamp": "2026-01-01T12:00:00Z", "open_interest": "12500.5", "mark_price": "42150.75", "oracle_price": "42148.50", "day_ntl_volume": "1250000000", "mid_price": "42150.75", "impact_bid_price": "42150.00", "impact_ask_price": "42151.50" }, "meta": { "count": 1, "request_id": "4d1fe223-53e7-498d-a54a-4fb2f9314734" } } ``` Copy ### Funding Rate (current) GET /v1/{venue}/funding/:symbol/current Schema success boolean required Always `true` on a 2xx response. Errors return `success: false` with an `error` field. true data object required Response payload. symbol string required Trading pair symbol (preferred) "BTC" coin string required Trading pair symbol (deprecated, use symbol) "BTC" timestamp string required Funding timestamp (ISO 8601) "2026-01-01T00:00:00Z" funding_rate string required Funding rate as decimal (0.0001 = 0.01%) "0.0001" premium string Premium component of funding rate (Hyperliquid/HIP-3 only) "0.00005" meta object required Response metadata. Inspect this to drive cursor pagination and trace requests. count integer required Number of items returned. For object responses, always 1. 1 request_id string required UUID for this request. Include it when contacting support so we can find the call in our logs. "4d1fe223-53e7-498d-a54a-4fb2f9314734" Example ``` { "success": true, "data": { "coin": "BTC", "symbol": "BTC", "timestamp": "2026-01-01T00:00:00Z", "funding_rate": "0.0001", "premium": "0.00005" }, "meta": { "count": 1, "request_id": "4d1fe223-53e7-498d-a54a-4fb2f9314734" } } ``` Copy ### Symbol Freshness GET /v1/{venue}/freshness/:symbol Schema success boolean required Always `true` on a 2xx response. Errors return `success: false` with an `error` field. true data object required Response payload. symbol string required Trading pair symbol (preferred) "BTC" coin string required Trading pair symbol (deprecated, use symbol) "BTC" exchange string required Source venue "hyperliquid" measured_at string required Server time when this freshness was measured (ISO 8601) "2026-01-01T12:00:00.000Z" orderbook object Order book freshness last_updated string required Most recent ingestion timestamp (ISO 8601) "2026-01-01T12:00:00Z" lag_ms integer required Milliseconds between last_updated and measured_at 1929 trades object Trade-stream freshness last_updated string required Most recent ingestion timestamp (ISO 8601) "2026-01-01T12:00:00Z" lag_ms integer required Milliseconds between last_updated and measured_at 1929 funding object Funding-rate freshness last_updated string required Most recent ingestion timestamp (ISO 8601) "2026-01-01T12:00:00Z" lag_ms integer required Milliseconds between last_updated and measured_at 1929 open_interest object Open-interest freshness last_updated string required Most recent ingestion timestamp (ISO 8601) "2026-01-01T12:00:00Z" lag_ms integer required Milliseconds between last_updated and measured_at 1929 liquidations object Liquidation-stream freshness (Hyperliquid only) last_updated string required Most recent ingestion timestamp (ISO 8601) "2026-01-01T12:00:00Z" lag_ms integer required Milliseconds between last_updated and measured_at 1929 meta object required Response metadata. Inspect this to drive cursor pagination and trace requests. count integer required Number of items returned. For object responses, always 1. 1 request_id string required UUID for this request. Include it when contacting support so we can find the call in our logs. "4d1fe223-53e7-498d-a54a-4fb2f9314734" Example ``` { "success": true, "data": { "coin": "BTC", "symbol": "BTC", "exchange": "hyperliquid", "measured_at": "2026-04-30T17:09:54.286Z", "orderbook": { "last_updated": "2026-04-30T17:09:52.357Z", "lag_ms": 1929 }, "trades": { "last_updated": "2026-04-30T17:09:05.051Z", "lag_ms": 49235 }, "funding": { "last_updated": "2026-04-30T17:09:39.281Z", "lag_ms": 15005 }, "open_interest": { "last_updated": "2026-04-30T17:09:39.281Z", "lag_ms": 15005 }, "liquidations": { "last_updated": "2026-04-30T15:32:15.597Z", "lag_ms": 5858689 } }, "meta": { "count": 1, "request_id": "4d1fe223-53e7-498d-a54a-4fb2f9314734" } } ``` Copy ## Instruments Discovery routes. Use these to enumerate tradable symbols before pulling other data. ### Instruments (Hyperliquid / Lighter) GET /v1/{hyperliquid|lighter}/instruments and /v1/{hyperliquid|lighter}/instruments/:symbol Schema success boolean required Always `true` on a 2xx response. Errors return `success: false` with an `error` field. true data array required Array of result items. Item object name string required Instrument symbol "BTC" sz_decimals integer required Decimal precision for size fields 5 max_leverage integer required Maximum leverage allowed 40 instrument_type string required Always "perp" today "perp" is_active boolean required Whether the instrument is currently tradable true meta object required Response metadata. Inspect this to drive cursor pagination and trace requests. count integer required Number of items returned. For object responses, always 1. 1 request_id string required UUID for this request. Include it when contacting support so we can find the call in our logs. "4d1fe223-53e7-498d-a54a-4fb2f9314734" Example ``` { "success": true, "data": [ { "name": "BTC", "sz_decimals": 5, "max_leverage": 40, "instrument_type": "perp", "is_active": true } ], "meta": { "count": 230, "request_id": "4d1fe223-53e7-498d-a54a-4fb2f9314734" } } ``` Copy ### HIP-3 Instruments GET /v1/hyperliquid/hip3/instruments and /v1/hyperliquid/hip3/instruments/:symbol Schema success boolean required Always `true` on a 2xx response. Errors return `success: false` with an `error` field. true data array required Array of result items. Item object coin string required HIP-3 symbol (namespace:ticker) "km:US500" namespace string required Builder namespace (e.g., km, xyz, cash) "km" ticker string required Ticker within namespace "US500" mark_price number Latest mark price 715.36 open_interest number Latest open interest 4490.7 mid_price number Latest mid price 715.355 latest_timestamp string Last data point ISO timestamp "2026-04-30T17:10:19.439Z" meta object required Response metadata. Inspect this to drive cursor pagination and trace requests. count integer required Number of items returned. For object responses, always 1. 1 request_id string required UUID for this request. Include it when contacting support so we can find the call in our logs. "4d1fe223-53e7-498d-a54a-4fb2f9314734" Example ``` { "success": true, "data": [ { "coin": "km:US500", "namespace": "km", "ticker": "US500", "mark_price": 715.36, "open_interest": 4490.7, "mid_price": 715.355, "latest_timestamp": "2026-04-30T17:10:19.439Z" } ], "meta": { "count": 132, "request_id": "4d1fe223-53e7-498d-a54a-4fb2f9314734" } } ``` Copy ### HIP-4 Instruments (per side) GET /v1/hyperliquid/hip4/instruments and /v1/hyperliquid/hip4/instruments/:symbol — one row per coin (Yes/No sides). Coins use the numeric id (0, 1, 10, 11, ...). Schema success boolean required Always `true` on a 2xx response. Errors return `success: false` with an `error` field. true data array required Array of result items. Item object outcome_id integer required Outcome market ID 0 side integer required Side index (0 = Yes, 1 = No) 0 asset_id integer required Public asset_id (100_000_000 + 10*outcome_id + side) 100000000 coin string required HIP-4 coin id. Also accepts #-prefixed form. "0" symbol string required Same as coin "0" name string required Human-readable per-side label "BTC ≥ 78213 by 2026-05-03 06:00 UTC — Yes" description string Pipe-encoded recurring metadata "class:priceBinary|underlying:BTC|expiry:20260503-0600|targetPrice:78213|period:1d" side_name string Side label ("Yes" or "No") "Yes" recurring_class string Outcome class (e.g., priceBinary) "priceBinary" recurring_underlying string Underlying asset for the outcome "BTC" recurring_expiry string Settlement timestamp (ISO 8601) "2026-05-03T06:00:00Z" recurring_target_px number Target price for the outcome 78213 recurring_period string Recurrence period (e.g., 1d) "1d" builder_address string Builder/deployer address "0x1234...abcd" is_settled boolean Whether the outcome has settled false first_seen_at string First-seen ISO timestamp "2026-05-02T07:47:00Z" last_updated_at string Last-updated ISO timestamp "2026-05-02T20:25:00Z" meta object required Response metadata. Inspect this to drive cursor pagination and trace requests. count integer required Number of items returned. For object responses, always 1. 1 request_id string required UUID for this request. Include it when contacting support so we can find the call in our logs. "4d1fe223-53e7-498d-a54a-4fb2f9314734" Example ``` { "success": true, "data": [ { "outcome_id": 0, "side": 0, "asset_id": 100000000, "coin": "#0", "symbol": "#0", "name": "BTC ≥ 78213 by 2026-05-03 06:00 UTC — Yes", "description": "class:priceBinary|underlying:BTC|expiry:20260503-0600|targetPrice:78213|period:1d", "side_name": "Yes", "recurring_class": "priceBinary", "recurring_underlying": "BTC", "recurring_expiry": "2026-05-03T06:00:00Z", "recurring_target_px": 78213, "recurring_period": "1d", "builder_address": "0x1234567890abcdef1234567890abcdef12345678", "is_settled": false, "first_seen_at": "2026-05-02T07:47:00Z", "last_updated_at": "2026-05-02T20:25:00Z" } ], "meta": { "count": 2, "request_id": "4d1fe223-53e7-498d-a54a-4fb2f9314734" } } ``` Copy ### HIP-4 Outcomes (per outcome) GET /v1/hyperliquid/hip4/outcomes (list, no aggregated_oi) and GET /v1/hyperliquid/hip4/outcomes/:outcome_id (detail, includes aggregated_oi). Schema success boolean required Always `true` on a 2xx response. Errors return `success: false` with an `error` field. true data array required Array of result items. Item object outcome_id integer required Outcome market ID 0 name string required Human-readable outcome name "BTC ≥ 78213 by 2026-05-03 06:00 UTC" description_raw string Pipe-encoded recurring metadata "class:priceBinary|underlying:BTC|expiry:20260503-0600|targetPrice:78213|period:1d" class string Outcome class (e.g., priceBinary) "priceBinary" underlying string Underlying asset "BTC" expiry string Settlement timestamp (ISO 8601) "2026-05-03T06:00:00Z" target_price number Target price for the outcome 78213 period string Recurrence period "1d" side_specs array required Per-side coin/asset_id mapping (Yes and No sides) SideSpec object side integer required Side index (0 = Yes, 1 = No) 0 name string required Side label "Yes" coin string required HIP-4 coin id. Also accepts #-prefixed form. "0" asset_id integer required 100_000_000 + 10*outcome_id + side 100000000 is_settled boolean Whether the outcome has settled false status string Lifecycle status: "live" or "settled" "live" source_seen_at string Latest upstream observation timestamp "2026-05-02T20:25:00Z" aggregated_oi object Both-sides OI aggregate. Present on /outcomes/{outcome_id} detail; omitted on /outcomes list. side0_open_interest_contracts number Latest Yes-side OI in contracts 568048 side1_open_interest_contracts number Latest No-side OI in contracts 568048 outcome_display_open_interest_contracts number Display OI (sum of both sides) 1136096 paired_set_supply_contracts number Paired-set supply (one of the sides when parity holds) 568048 side_supply_parity boolean True when both sides have equal supply (typical for fully-collateralized outcome markets) true currency string Currency for notional values "USDH" as_of string Aggregate as-of timestamp "2026-05-02T20:27:21Z" side0_as_of string Yes-side OI as-of timestamp "2026-05-02T20:27:21Z" side1_as_of string No-side OI as-of timestamp "2026-05-02T20:27:21Z" meta object required Response metadata. Inspect this to drive cursor pagination and trace requests. count integer required Number of items returned. For object responses, always 1. 1 request_id string required UUID for this request. Include it when contacting support so we can find the call in our logs. "4d1fe223-53e7-498d-a54a-4fb2f9314734" Example ``` { "success": true, "data": [ { "outcome_id": 0, "name": "BTC ≥ 78213 by 2026-05-03 06:00 UTC", "description_raw": "class:priceBinary|underlying:BTC|expiry:20260503-0600|targetPrice:78213|period:1d", "class": "priceBinary", "underlying": "BTC", "expiry": "2026-05-03T06:00:00Z", "target_price": 78213, "period": "1d", "side_specs": [ { "side": 0, "name": "Yes", "coin": "#0", "asset_id": 100000000 }, { "side": 1, "name": "No", "coin": "#1", "asset_id": 100000001 } ], "is_settled": false, "status": "live", "source_seen_at": "2026-05-02T20:25:00Z", "aggregated_oi": { "side0_open_interest_contracts": 568048, "side1_open_interest_contracts": 568048, "outcome_display_open_interest_contracts": 1136096, "paired_set_supply_contracts": 568048, "side_supply_parity": true, "currency": "USDH", "as_of": "2026-05-02T20:27:21Z", "side0_as_of": "2026-05-02T20:27:21Z", "side1_as_of": "2026-05-02T20:27:21Z" } } ], "meta": { "count": 1, "request_id": "4d1fe223-53e7-498d-a54a-4fb2f9314734" } } ``` Copy ### Hyperliquid Spot Pairs GET /v1/hyperliquid/spot/pairs and /v1/hyperliquid/spot/pairs/:symbol. 294 spot pairs. Symbols are dashed (PURR-USDC); the wire/index forms are returned for reference but the API never accepts @ in URLs. Schema success boolean required Always `true` on a 2xx response. Errors return `success: false` with an `error` field. true data array required Array of result items. Item object symbol string required Dashed pair symbol used everywhere in the API (e.g., PURR-USDC, HYPE-USDC, HFUN-USDC). "PURR-USDC" base string required Base token of the pair "PURR" quote string required Quote token of the pair (USDC, USDT0, USDH, ...) "USDC" wire string Hyperliquid wire-format coin (slash form). Used internally; not required to call the API. "PURR/USDC" pair_index integer Numeric pair index (the @ form). 0xArchive does not accept @ in URLs; always use the dashed symbol. 107 meta object required Response metadata. Inspect this to drive cursor pagination and trace requests. count integer required Number of items returned. For object responses, always 1. 1 request_id string required UUID for this request. Include it when contacting support so we can find the call in our logs. "4d1fe223-53e7-498d-a54a-4fb2f9314734" Example ``` { "success": true, "data": [ { "symbol": "PURR-USDC", "base": "PURR", "quote": "USDC", "wire": "PURR/USDC", "pair_index": 107 } ], "meta": { "count": 294, "request_id": "4d1fe223-53e7-498d-a54a-4fb2f9314734" } } ``` Copy ## Hyperliquid Spot Spot fills carry fields that perp fills do not: open-set fee_token (USDC, PURR, HYPE, KHYPE, USOL, ...), real EVM tx_hash on roughly 69% of fills, builder_address / builder_fee for routed orders, and twap_id for slices of a parent TWAP. Spot has no funding, OI, liquidations, or candles by design (build OHLCV client-side from spot trades). ### Spot Trade GET /v1/hyperliquid/spot/trades/:symbol. Backfilled from 2025-03-22; pre-March 2025 spot history is unrecoverable from any free public archive. Schema success boolean required Always `true` on a 2xx response. Errors return `success: false` with an `error` field. true data array required Array of result items. Item object symbol string required Dashed spot symbol (preferred). The server resolves the wire format (e.g., PURR/USDC, @) internally. "PURR-USDC" coin string required Wire-format spot coin (legacy). Use `symbol` in new code. "PURR/USDC" side string required Trade side: "A" (ask/sell) or "B" (bid/buy) "B" price string required Execution price "0.32152" size string required Trade size in base token "1502.0" timestamp string required Execution timestamp (ISO 8601) "2026-05-05T17:13:24.733Z" tx_hash string Real EVM transaction hash for spot fills (~69% of spot trades carry a non-zero hash; perp fills are all-zero). Useful for L1 trade attribution. "0xf19c2a...8b4d" trade_id integer Unique trade ID 1003245567 order_id integer Associated order ID 89567103221 crossed boolean True if taker (crossed spread), false if maker true fee string Trading fee amount "0.4824" fee_token string Fee denomination. Spot fees are open-set: USDC, PURR, HYPE, KHYPE, USOL, etc. Pre-validate the value rather than assuming USDC. "USDC" user_address string User's wallet address for this fill "0x9a3c...1e2f" builder_address string Builder address that routed this order. Present only when the order was placed through a builder. "0x4950...9395" builder_fee string Builder fee charged on this fill, paid to the builder. Present only when builder_address is set. "0.024" twap_id integer Parent TWAP execution ID. Present when the fill is a slice of a TWAP order; null otherwise. 7732 direction string Spot direction label: "Buy" or "Sell". Spot has no Open/Close/Long/Short concepts. "Buy" meta object required Response metadata. Inspect this to drive cursor pagination and trace requests. count integer required Number of items returned in this page. 100 next_cursor string Opaque cursor for the next page. Omitted on the final page — when missing, you have reached the end of the range. "1761840000596_907964252522803" request_id string required UUID for this request. Include it when contacting support so we can find the call in our logs. "4d1fe223-53e7-498d-a54a-4fb2f9314734" Example ``` { "success": true, "data": [ { "symbol": "PURR-USDC", "coin": "PURR/USDC", "side": "B", "price": "0.32152", "size": "1502.0", "timestamp": "2026-05-05T17:13:24.733Z", "tx_hash": "0xf19c2a14abc7b4f60a5d2ae8c9b0f4a1d6e7c2b3a4d5e6f70819203a4b5c6d7e", "trade_id": 1003245567, "order_id": 89567103221, "crossed": true, "fee": "0.4824", "fee_token": "USDC", "user_address": "0x9a3c4d5e6f7081a2b3c4d5e6f70819203a4b5c1e", "builder_address": "0x4950abcdef1234567890abcdef12345678909395", "builder_fee": "0.024", "twap_id": null, "direction": "Buy" } ], "meta": { "count": 1, "next_cursor": "1761840000596_907964252522803", "request_id": "4d1fe223-53e7-498d-a54a-4fb2f9314734" } } ``` Copy ### Spot TWAP GET /v1/hyperliquid/spot/twap/:symbol and /v1/hyperliquid/spot/twap/user/:user. Live-only from 2026-05-05. Schema success boolean required Always `true` on a 2xx response. Errors return `success: false` with an `error` field. true data array required Array of result items. Item object symbol string required Dashed spot symbol "HYPE-USDC" coin string Wire-format spot coin "HYPE/USDC" twap_id integer required Parent TWAP execution ID. All slices of one TWAP share this id. 7732 user_address string required User's wallet address driving the TWAP "0x44ad...8b9c" side string required TWAP side: "A" (sell) or "B" (buy) "A" slice_price string Price for this slice "24.875" slice_size string Size for this slice in base token "12.3" timestamp string required Slice execution timestamp (ISO 8601) "2026-05-05T17:13:25.119Z" parent_total_size string Total intended TWAP size (base token) "120.0" completed_size string Cumulative completed size after this slice "36.9" status string Lifecycle status: progressing, completed, canceled, expired "progressing" meta object required Response metadata. Inspect this to drive cursor pagination and trace requests. count integer required Number of items returned in this page. 100 next_cursor string Opaque cursor for the next page. Omitted on the final page — when missing, you have reached the end of the range. "1761840000596_907964252522803" request_id string required UUID for this request. Include it when contacting support so we can find the call in our logs. "4d1fe223-53e7-498d-a54a-4fb2f9314734" Example ``` { "success": true, "data": [ { "symbol": "HYPE-USDC", "coin": "HYPE/USDC", "twap_id": 7732, "user_address": "0x44ad567890abcdef1234567890abcdef12348b9c", "side": "A", "slice_price": "24.875", "slice_size": "12.3", "timestamp": "2026-05-05T17:13:25.119Z", "parent_total_size": "120.0", "completed_size": "36.9", "status": "progressing" } ], "meta": { "count": 1, "next_cursor": "1761840000596_907964252522803", "request_id": "4d1fe223-53e7-498d-a54a-4fb2f9314734" } } ``` Copy ## Historical series Paginated time-series payloads. Stop when `meta.next_cursor` is missing. ### Trades GET /v1/{venue}/trades/:symbol — fill-level history with cursor pagination Schema success boolean required Always `true` on a 2xx response. Errors return `success: false` with an `error` field. true data array required Array of result items. Item object symbol string required Trading pair symbol (preferred) "ETH" coin string required Trading pair symbol (deprecated, use symbol) "ETH" side string required Trade side: "A" (ask/sell) or "B" (bid/buy) "B" price string required Execution price "2250.50" size string required Trade size "1.5" timestamp string required Execution timestamp (ISO 8601) "2026-01-01T12:00:00Z" tx_hash string Blockchain transaction hash (Hyperliquid) "0x..." trade_id integer Unique trade ID 12345678 order_id integer Associated order ID 987654321 crossed boolean True if taker (crossed spread), false if maker true fee string Trading fee amount "0.45" fee_token string Fee denomination "USDC" closed_pnl string Realized PnL if closing position "125.50" direction string Position direction (e.g., 'Open Long', 'Close Short', 'Long > Short') "Open Long" start_position string Position size before trade "10.5" user_address string User's wallet address (fill-level data) "0x..." maker_address string Maker's wallet address (market-level trades) "0x..." taker_address string Taker's wallet address (market-level trades) "0x..." account_index string Lighter account index. Lighter trades use account_index instead of user_address "59774" builder_address string Builder address that routed this order. Present only when the order was placed through a builder "0xb84c..." builder_fee string Builder fee charged on this fill, paid to the builder (in quote currency, typically USDC). Present only when builder_address is set "0.039" deployer_fee string 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 "-0.05" priority_gas number 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 3e-8 cloid string Client order ID "0x00000000000000000006..." twap_id integer TWAP execution ID 1750482 meta object required Response metadata. Inspect this to drive cursor pagination and trace requests. count integer required Number of items returned in this page. 100 next_cursor string Opaque cursor for the next page. Omitted on the final page — when missing, you have reached the end of the range. "1761840000596_907964252522803" request_id string required UUID for this request. Include it when contacting support so we can find the call in our logs. "4d1fe223-53e7-498d-a54a-4fb2f9314734" Example ``` { "success": true, "data": [ { "symbol": "ETH", "coin": "ETH", "side": "B", "price": "2250.50", "size": "1.5", "timestamp": "2026-01-01T12:00:00Z", "trade_id": 12345678, "crossed": true, "fee": "0.45", "fee_token": "USDC", "direction": "Open Long", "builder_address": "0xb84c7fb41ee7d8781e2b0d59eed2accd2ae99533", "builder_fee": "0.039", "priority_gas": 3e-8 } ], "meta": { "count": 1000, "next_cursor": "1761840000596_907964252522803", "request_id": "4d1fe223-53e7-498d-a54a-4fb2f9314734" } } ``` Copy ### Trades (recent) GET /v1/lighter/trades/:symbol/recent, /v1/hyperliquid/hip3/trades/:symbol/recent, and /v1/hyperliquid/hip4/trades/:symbol/recent — most recent fills, no pagination Schema success boolean required Always `true` on a 2xx response. Errors return `success: false` with an `error` field. true data array required Array of result items. Item object symbol string required Trading pair symbol (preferred) "ETH" coin string required Trading pair symbol (deprecated, use symbol) "ETH" side string required Trade side: "A" (ask/sell) or "B" (bid/buy) "B" price string required Execution price "2250.50" size string required Trade size "1.5" timestamp string required Execution timestamp (ISO 8601) "2026-01-01T12:00:00Z" tx_hash string Blockchain transaction hash (Hyperliquid) "0x..." trade_id integer Unique trade ID 12345678 order_id integer Associated order ID 987654321 crossed boolean True if taker (crossed spread), false if maker true fee string Trading fee amount "0.45" fee_token string Fee denomination "USDC" closed_pnl string Realized PnL if closing position "125.50" direction string Position direction (e.g., 'Open Long', 'Close Short', 'Long > Short') "Open Long" start_position string Position size before trade "10.5" user_address string User's wallet address (fill-level data) "0x..." maker_address string Maker's wallet address (market-level trades) "0x..." taker_address string Taker's wallet address (market-level trades) "0x..." account_index string Lighter account index. Lighter trades use account_index instead of user_address "59774" builder_address string Builder address that routed this order. Present only when the order was placed through a builder "0xb84c..." builder_fee string Builder fee charged on this fill, paid to the builder (in quote currency, typically USDC). Present only when builder_address is set "0.039" deployer_fee string 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 "-0.05" priority_gas number 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 3e-8 cloid string Client order ID "0x00000000000000000006..." twap_id integer TWAP execution ID 1750482 meta object required Response metadata. Inspect this to drive cursor pagination and trace requests. count integer required Number of items returned. For object responses, always 1. 1 request_id string required UUID for this request. Include it when contacting support so we can find the call in our logs. "4d1fe223-53e7-498d-a54a-4fb2f9314734" Example ``` { "success": true, "data": [ { "symbol": "ETH", "coin": "ETH", "side": "B", "price": "2250.50", "size": "1.5", "timestamp": "2026-01-01T12:00:00Z", "trade_id": 12345678, "crossed": true, "fee": "0.45", "fee_token": "USDC", "direction": "Open Long", "builder_address": "0xb84c7fb41ee7d8781e2b0d59eed2accd2ae99533", "builder_fee": "0.039", "priority_gas": 3e-8 } ], "meta": { "count": 50, "request_id": "4d1fe223-53e7-498d-a54a-4fb2f9314734" } } ``` Copy ### Order Book History GET /v1/{venue}/orderbook/:symbol/history — checkpoint-rate snapshots (or sub-second on Lighter granularity options) Schema success boolean required Always `true` on a 2xx response. Errors return `success: false` with an `error` field. true data array required Array of result items. Item object symbol string required Trading pair symbol (preferred) "BTC" coin string required Trading pair symbol (deprecated, use symbol) "BTC" timestamp string required Snapshot timestamp (ISO 8601) "2026-01-01T12:00:00Z" bids array required Bid price levels (best bid first) PriceLevel object px string required Price at this level "42150.50" sz string required Total size at this level "2.5" n integer required Number of orders 5 asks array required Ask price levels (best ask first) PriceLevel object px string required Price at this level "42151.00" sz string required Total size at this level "1.8" n integer required Number of orders 3 mid_price string Mid price (best bid + best ask) / 2 "42150.75" spread string Spread in absolute terms "0.50" spread_bps string Spread in basis points "1.19" meta object required Response metadata. Inspect this to drive cursor pagination and trace requests. count integer required Number of items returned in this page. 100 next_cursor string Opaque cursor for the next page. Omitted on the final page — when missing, you have reached the end of the range. "1761840000596_907964252522803" request_id string required UUID for this request. Include it when contacting support so we can find the call in our logs. "4d1fe223-53e7-498d-a54a-4fb2f9314734" Example ``` { "success": true, "data": [ { "coin": "BTC", "symbol": "BTC", "timestamp": "2026-01-01T12:00:00Z", "bids": [ { "px": "42150.50", "sz": "2.5", "n": 5 }, { "px": "42150.00", "sz": "5.2", "n": 8 } ], "asks": [ { "px": "42151.00", "sz": "1.8", "n": 3 }, { "px": "42151.50", "sz": "3.1", "n": 4 } ], "mid_price": "42150.75", "spread": "0.50", "spread_bps": "1.19" } ], "meta": { "count": 1, "next_cursor": "1761840000596_907964252522803", "request_id": "4d1fe223-53e7-498d-a54a-4fb2f9314734" } } ``` Copy ### Candles GET /v1/{venue}/candles/:symbol Schema success boolean required Always `true` on a 2xx response. Errors return `success: false` with an `error` field. true data array required Array of result items. Item object timestamp string required Candle open timestamp (ISO 8601) "2026-01-01T12:00:00Z" open number required Opening price 42150.5 high number required Highest price in interval 42200 low number required Lowest price in interval 42100 close number required Closing price 42180 volume number required Volume in base asset 125.5 quote_volume number Volume in quote asset (USD) 5290000 trade_count integer Number of trades in interval 1234 meta object required Response metadata. Inspect this to drive cursor pagination and trace requests. count integer required Number of items returned in this page. 100 next_cursor string Opaque cursor for the next page. Omitted on the final page — when missing, you have reached the end of the range. "1761840000596_907964252522803" request_id string required UUID for this request. Include it when contacting support so we can find the call in our logs. "4d1fe223-53e7-498d-a54a-4fb2f9314734" Example ``` { "success": true, "data": [ { "timestamp": "2026-01-01T12:00:00Z", "open": 42150.5, "high": 42200, "low": 42100, "close": 42180, "volume": 125.5, "quote_volume": 5290000, "trade_count": 1234 } ], "meta": { "count": 1, "next_cursor": "1761840000596_907964252522803", "request_id": "4d1fe223-53e7-498d-a54a-4fb2f9314734" } } ``` Copy ### Funding History GET /v1/{venue}/funding/:symbol Schema success boolean required Always `true` on a 2xx response. Errors return `success: false` with an `error` field. true data array required Array of result items. Item object symbol string required Trading pair symbol (preferred) "BTC" coin string required Trading pair symbol (deprecated, use symbol) "BTC" timestamp string required Funding timestamp (ISO 8601) "2026-01-01T00:00:00Z" funding_rate string required Funding rate as decimal (0.0001 = 0.01%) "0.0001" premium string Premium component of funding rate (Hyperliquid/HIP-3 only) "0.00005" meta object required Response metadata. Inspect this to drive cursor pagination and trace requests. count integer required Number of items returned in this page. 100 next_cursor string Opaque cursor for the next page. Omitted on the final page — when missing, you have reached the end of the range. "1761840000596_907964252522803" request_id string required UUID for this request. Include it when contacting support so we can find the call in our logs. "4d1fe223-53e7-498d-a54a-4fb2f9314734" Example ``` { "success": true, "data": [ { "coin": "BTC", "symbol": "BTC", "timestamp": "2026-01-01T00:00:00Z", "funding_rate": "0.0001", "premium": "0.00005" } ], "meta": { "count": 1, "next_cursor": "1761840000596_907964252522803", "request_id": "4d1fe223-53e7-498d-a54a-4fb2f9314734" } } ``` Copy ### Open Interest History GET /v1/{venue}/openinterest/:symbol Schema success boolean required Always `true` on a 2xx response. Errors return `success: false` with an `error` field. true data array required Array of result items. Item object symbol string required Trading pair symbol (preferred) "BTC" coin string required Trading pair symbol (deprecated, use symbol) "BTC" timestamp string required Snapshot timestamp (ISO 8601) "2026-01-01T12:00:00Z" open_interest string required Total open interest in contracts "12500.5" mark_price string Mark price for liquidations on Hyperliquid/HIP-3. On HIP-4 this is implied probability in [0,1], NOT a USD price (we mirror Hyperliquid upstream naming). "42150.75" oracle_price string Oracle price from external feed (omitted on HIP-4 — outcome markets have no oracle feed) "42148.50" day_ntl_volume string 24-hour notional volume "1250000000" prev_day_price string Price 24 hours ago "41500.00" mid_price string Current mid price (HIP-4: implied probability in [0,1]) "42150.75" impact_bid_price string Best bid price after applying impact size — used by Hyperliquid for funding calculations "42150.00" impact_ask_price string Best ask price after applying impact size — used by Hyperliquid for funding calculations "42151.50" meta object required Response metadata. Inspect this to drive cursor pagination and trace requests. count integer required Number of items returned in this page. 100 next_cursor string Opaque cursor for the next page. Omitted on the final page — when missing, you have reached the end of the range. "1761840000596_907964252522803" request_id string required UUID for this request. Include it when contacting support so we can find the call in our logs. "4d1fe223-53e7-498d-a54a-4fb2f9314734" Example ``` { "success": true, "data": [ { "coin": "BTC", "symbol": "BTC", "timestamp": "2026-01-01T12:00:00Z", "open_interest": "12500.5", "mark_price": "42150.75", "oracle_price": "42148.50", "day_ntl_volume": "1250000000", "mid_price": "42150.75", "impact_bid_price": "42150.00", "impact_ask_price": "42151.50" } ], "meta": { "count": 1, "next_cursor": "1761840000596_907964252522803", "request_id": "4d1fe223-53e7-498d-a54a-4fb2f9314734" } } ``` Copy ### Price History GET /v1/{venue}/prices/:symbol Schema success boolean required Always `true` on a 2xx response. Errors return `success: false` with an `error` field. true data array required Array of result items. Item object timestamp string required Snapshot timestamp (ISO 8601) "2026-01-01T12:00:00Z" mark_price string Mark price "42150.75" oracle_price string Oracle price "42148.50" mid_price string Mid price (Hyperliquid/HIP-3/HIP-4 only; HIP-4 mid_price is implied probability in [0,1]) "42150.75" meta object required Response metadata. Inspect this to drive cursor pagination and trace requests. count integer required Number of items returned in this page. 100 next_cursor string Opaque cursor for the next page. Omitted on the final page — when missing, you have reached the end of the range. "1761840000596_907964252522803" request_id string required UUID for this request. Include it when contacting support so we can find the call in our logs. "4d1fe223-53e7-498d-a54a-4fb2f9314734" Example ``` { "success": true, "data": [ { "timestamp": "2026-01-01T12:00:00Z", "mark_price": "42150.75", "oracle_price": "42148.50", "mid_price": "42150.75" } ], "meta": { "count": 1, "next_cursor": "1761840000596_907964252522803", "request_id": "4d1fe223-53e7-498d-a54a-4fb2f9314734" } } ``` Copy ## Liquidations Hyperliquid + HIP-3 liquidation events and bucketed volumes. ### Liquidation GET /v1/hyperliquid/liquidations/:symbol, /v1/hyperliquid/liquidations/user/:user, /v1/hyperliquid/hip3/liquidations/:symbol Schema success boolean required Always `true` on a 2xx response. Errors return `success: false` with an `error` field. true data array required Array of result items. Item object coin string required Trading pair symbol "BTC" timestamp string required Liquidation timestamp (ISO 8601) "2026-01-01T12:00:00Z" liquidated_user string required Wallet address of liquidated user "0xf0e35ea2542c070b74faba2dfbe6c16e599fdaa3" liquidator_user string required Wallet address of liquidator. Equals liquidated_user when the position closes itself "0xf0e35ea2542c070b74faba2dfbe6c16e599fdaa3" price string required Liquidation price "42150.50" size string required Position size liquidated "1.5" side string required Position side: "B" (long) or "A" (short) "A" mark_price string Mark price at liquidation "42148.00" closed_pnl string Realized PnL from liquidation "-500.25" direction string Position direction description "Close Long" trade_id integer Unique trade ID 63845468834205 tx_hash string Blockchain transaction hash "0xf89907d0bf82aa6afa120439d0b66e0207ea00b65a85c93d9c61b3237e868455" meta object required Response metadata. Inspect this to drive cursor pagination and trace requests. count integer required Number of items returned in this page. 100 next_cursor string Opaque cursor for the next page. Omitted on the final page — when missing, you have reached the end of the range. "1761840000596_907964252522803" request_id string required UUID for this request. Include it when contacting support so we can find the call in our logs. "4d1fe223-53e7-498d-a54a-4fb2f9314734" Example ``` { "success": true, "data": [ { "coin": "BTC", "timestamp": "2026-04-23T17:17:12.656Z", "liquidated_user": "0xf0e35ea2542c070b74faba2dfbe6c16e599fdaa3", "liquidator_user": "0xf0e35ea2542c070b74faba2dfbe6c16e599fdaa3", "price": "77611", "size": "0.00024", "side": "A", "mark_price": "77612", "closed_pnl": "-0.22656", "direction": "Close Long", "trade_id": 63845468834205, "tx_hash": "0xf89907d0bf82aa6afa120439d0b66e0207ea00b65a85c93d9c61b3237e868455" } ], "meta": { "count": 1, "next_cursor": "1761840000596_907964252522803", "request_id": "4d1fe223-53e7-498d-a54a-4fb2f9314734" } } ``` Copy ### Liquidation Volume GET /v1/hyperliquid/liquidations/:symbol/volume and /v1/hyperliquid/hip3/liquidations/:symbol/volume Schema success boolean required Always `true` on a 2xx response. Errors return `success: false` with an `error` field. true data array required Array of result items. Item object symbol string Trading pair symbol "BTC" coin string Trading pair symbol (legacy) "BTC" timestamp string required Bucket start timestamp (ISO 8601) "2026-01-01T12:00:00Z" total_usd number required Total liquidation notional in USD 716220.9 long_usd number required Long liquidation notional in USD 631463.06 short_usd number required Short liquidation notional in USD 84757.84 count integer Total liquidation events in bucket 258 long_count integer Long liquidation events in bucket 228 short_count integer Short liquidation events in bucket 30 meta object required Response metadata. Inspect this to drive cursor pagination and trace requests. count integer required Number of items returned in this page. 100 next_cursor string Opaque cursor for the next page. Omitted on the final page — when missing, you have reached the end of the range. "1761840000596_907964252522803" request_id string required UUID for this request. Include it when contacting support so we can find the call in our logs. "4d1fe223-53e7-498d-a54a-4fb2f9314734" Example ``` { "success": true, "data": [ { "coin": "BTC", "symbol": "BTC", "timestamp": "2026-04-24T00:00:00Z", "total_usd": 716220.9, "long_usd": 631463.06, "short_usd": 84757.84, "count": 258, "long_count": 228, "short_count": 30 } ], "meta": { "count": 1, "next_cursor": "1761840000596_907964252522803", "request_id": "4d1fe223-53e7-498d-a54a-4fb2f9314734" } } ``` Copy ## Order books and diffs (Pro+) Higher-tier depth payloads — node-level L4, derived L2 full depth, and Lighter L3. ### L4 Order Book GET /v1/hyperliquid/orderbook/:symbol/l4 and HIP-3 / HIP-4 equivalents — single reconstruction Schema success boolean required Always `true` on a 2xx response. Errors return `success: false` with an `error` field. true data object required Response payload. coin string required Trading pair symbol "BTC" timestamp string required Reconstruction timestamp (ISO 8601) "2026-03-12T12:00:00Z" checkpoint_timestamp string required Checkpoint that anchors this reconstruction "2026-03-12T12:00:00Z" diffs_applied integer required Number of diffs replayed since checkpoint 1523 last_block_number integer required Last processed block number (0 on history snapshots) 921539055 bids array required Individual bid orders Order object oid integer required Unique order ID 81250648524 user_address string required Wallet address of order owner "0x1234...abcd" price number required Limit price 68355 size number required Remaining order size 0.5 side string required "B" (bid) or "A" (ask) "B" asks array required Individual ask orders Order object oid integer required Unique order ID 81250652360 user_address string required Wallet address of order owner "0x5678...efgh" price number required Limit price 68356 size number required Remaining order size 0.8 side string required "B" (bid) or "A" (ask) "A" bid_count integer Total bid orders in book 30561 ask_count integer Total ask orders in book 22323 total_bid_size number Aggregate bid size across all levels 6551.5 total_ask_size number Aggregate ask size across all levels 5028 meta object required Response metadata. Inspect this to drive cursor pagination and trace requests. count integer required Number of items returned. For object responses, always 1. 1 request_id string required UUID for this request. Include it when contacting support so we can find the call in our logs. "4d1fe223-53e7-498d-a54a-4fb2f9314734" Example ``` { "success": true, "data": { "coin": "BTC", "timestamp": "2026-04-29T17:12:24.360Z", "checkpoint_timestamp": "2026-04-29T17:12:24.360Z", "diffs_applied": 0, "last_block_number": 977546146, "bids": [ { "oid": 403690644184, "user_address": "0xf9109ada2f73c62e9889b45453065f0d99260a2d", "side": "B", "price": 75908, "size": 0.00262 } ], "asks": [ { "oid": 403690755957, "user_address": "0x2ca4927174ba283d8a57f60ef3589844035a2930", "side": "A", "price": 75909, "size": 0.00017 } ], "bid_count": 30561, "ask_count": 22323, "total_bid_size": 6551.5, "total_ask_size": 5028 }, "meta": { "count": 1, "request_id": "4d1fe223-53e7-498d-a54a-4fb2f9314734" } } ``` Copy ### L4 Order Book (history) GET /v1/hyperliquid/orderbook/:symbol/l4/history and HIP-3 / HIP-4 equivalents — paginated checkpoints Schema success boolean required Always `true` on a 2xx response. Errors return `success: false` with an `error` field. true data array required Array of result items. Item object coin string required Trading pair symbol "BTC" timestamp string required Reconstruction timestamp (ISO 8601) "2026-03-12T12:00:00Z" checkpoint_timestamp string required Checkpoint that anchors this reconstruction "2026-03-12T12:00:00Z" diffs_applied integer required Number of diffs replayed since checkpoint 1523 last_block_number integer required Last processed block number (0 on history snapshots) 921539055 bids array required Individual bid orders Order object oid integer required Unique order ID 81250648524 user_address string required Wallet address of order owner "0x1234...abcd" price number required Limit price 68355 size number required Remaining order size 0.5 side string required "B" (bid) or "A" (ask) "B" asks array required Individual ask orders Order object oid integer required Unique order ID 81250652360 user_address string required Wallet address of order owner "0x5678...efgh" price number required Limit price 68356 size number required Remaining order size 0.8 side string required "B" (bid) or "A" (ask) "A" bid_count integer Total bid orders in book 30561 ask_count integer Total ask orders in book 22323 total_bid_size number Aggregate bid size across all levels 6551.5 total_ask_size number Aggregate ask size across all levels 5028 meta object required Response metadata. Inspect this to drive cursor pagination and trace requests. count integer required Number of items returned in this page. 100 next_cursor string Opaque cursor for the next page. Omitted on the final page — when missing, you have reached the end of the range. "1761840000596_907964252522803" request_id string required UUID for this request. Include it when contacting support so we can find the call in our logs. "4d1fe223-53e7-498d-a54a-4fb2f9314734" Example ``` { "success": true, "data": [ { "coin": "BTC", "timestamp": "2026-04-29T17:12:24.360Z", "checkpoint_timestamp": "2026-04-29T17:12:24.360Z", "diffs_applied": 0, "last_block_number": 977546146, "bids": [ { "oid": 403690644184, "user_address": "0xf9109ada2f73c62e9889b45453065f0d99260a2d", "side": "B", "price": 75908, "size": 0.00262 } ], "asks": [ { "oid": 403690755957, "user_address": "0x2ca4927174ba283d8a57f60ef3589844035a2930", "side": "A", "price": 75909, "size": 0.00017 } ], "bid_count": 30561, "ask_count": 22323, "total_bid_size": 6551.5, "total_ask_size": 5028 } ], "meta": { "count": 1, "next_cursor": "1761840000596_907964252522803", "request_id": "4d1fe223-53e7-498d-a54a-4fb2f9314734" } } ``` Copy ### L4 Diff GET /v1/hyperliquid/orderbook/:symbol/l4/diffs and HIP-3 / HIP-4 equivalents — order-level changes Schema success boolean required Always `true` on a 2xx response. Errors return `success: false` with an `error` field. true data array required Array of result items. Item object timestamp string required Diff timestamp (ISO 8601) "2026-03-12T12:00:00.100Z" block_number integer required Block number of the change 921540000 seq integer required Sequence number within the block 278 coin string required Trading pair symbol "BTC" oid integer required Unique order ID 81250700001 user_address string required Wallet address of order owner "0x1234...abcd" side string required "B" (bid) or "A" (ask) "B" price number required Order price 68360 new_size number required New size (0 for full removes) 0.5 diff_type string required Change type: "new", "remove", or "update" "new" meta object required Response metadata. Inspect this to drive cursor pagination and trace requests. count integer required Number of items returned in this page. 100 next_cursor string Opaque cursor for the next page. Omitted on the final page — when missing, you have reached the end of the range. "1761840000596_907964252522803" request_id string required UUID for this request. Include it when contacting support so we can find the call in our logs. "4d1fe223-53e7-498d-a54a-4fb2f9314734" Example ``` { "success": true, "data": [ { "timestamp": "2026-04-29T17:13:24.733Z", "block_number": 977547037, "seq": 278, "coin": "BTC", "oid": 403691709447, "user_address": "0x023a3d058020fb76cca98f01b3c48c8938a22355", "side": "B", "price": 75856, "new_size": 0.74856, "diff_type": "new" } ], "meta": { "count": 1, "next_cursor": "eyJ2IjoyLCJmIjoiNTNlMmQyNDcxZGM5NzkwNiJ9", "request_id": "4d1fe223-53e7-498d-a54a-4fb2f9314734" } } ``` Copy ### L2 Full-Depth Order Book GET /v1/hyperliquid/orderbook/:symbol/l2 and HIP-3 / HIP-4 equivalents — derived from L4 Schema success boolean required Always `true` on a 2xx response. Errors return `success: false` with an `error` field. true data object required Response payload. symbol string required Trading pair symbol "BTC" coin string required Trading pair symbol (legacy) "BTC" timestamp string required Snapshot timestamp "2026-04-30 17:13:07.908" bids array required Aggregated bid levels (best bid first) PriceLevel object px number required Price at this level 76183 sz number required Total size at this level 75.5 n integer required Number of orders at this level 405 asks array required Aggregated ask levels (best ask first) PriceLevel object px number required Price at this level 76184 sz number required Total size at this level 0.44 n integer required Number of orders at this level 5 bid_levels integer Total bid levels in the full book 12649 ask_levels integer Total ask levels in the full book 8032 total_bid_size number Aggregate bid size across all levels 5878.9 total_ask_size number Aggregate ask size across all levels 4405.5 mid_price number Mid price 76183.5 spread number Spread in absolute terms 1 spread_bps number Spread in basis points 0.13 meta object required Response metadata. Inspect this to drive cursor pagination and trace requests. count integer required Number of items returned. For object responses, always 1. 1 request_id string required UUID for this request. Include it when contacting support so we can find the call in our logs. "4d1fe223-53e7-498d-a54a-4fb2f9314734" Example ``` { "success": true, "data": { "coin": "BTC", "symbol": "BTC", "timestamp": "2026-04-30 17:13:07.908", "bids": [ { "px": 76183, "sz": 75.5, "n": 405 }, { "px": 76182, "sz": 32.2, "n": 88 } ], "asks": [ { "px": 76184, "sz": 0.44, "n": 5 }, { "px": 76185, "sz": 1.32, "n": 12 } ], "bid_levels": 12649, "ask_levels": 8032, "total_bid_size": 5878.9, "total_ask_size": 4405.5, "mid_price": 76183.5, "spread": 1, "spread_bps": 0.13 }, "meta": { "count": 1, "request_id": "4d1fe223-53e7-498d-a54a-4fb2f9314734" } } ``` Copy ### L2 Full-Depth Order Book (history) GET /v1/hyperliquid/orderbook/:symbol/l2/history and HIP-3 / HIP-4 equivalents — paginated full-depth checkpoints Schema success boolean required Always `true` on a 2xx response. Errors return `success: false` with an `error` field. true data array required Array of result items. Item object symbol string required Trading pair symbol "BTC" coin string required Trading pair symbol (legacy) "BTC" timestamp string required Snapshot timestamp "2026-04-30 17:13:07.908" bids array required Aggregated bid levels (best bid first) PriceLevel object px number required Price at this level 76183 sz number required Total size at this level 75.5 n integer required Number of orders at this level 405 asks array required Aggregated ask levels (best ask first) PriceLevel object px number required Price at this level 76184 sz number required Total size at this level 0.44 n integer required Number of orders at this level 5 bid_levels integer Total bid levels in the full book 12649 ask_levels integer Total ask levels in the full book 8032 total_bid_size number Aggregate bid size across all levels 5878.9 total_ask_size number Aggregate ask size across all levels 4405.5 mid_price number Mid price 76183.5 spread number Spread in absolute terms 1 spread_bps number Spread in basis points 0.13 meta object required Response metadata. Inspect this to drive cursor pagination and trace requests. count integer required Number of items returned in this page. 100 next_cursor string Opaque cursor for the next page. Omitted on the final page — when missing, you have reached the end of the range. "1761840000596_907964252522803" request_id string required UUID for this request. Include it when contacting support so we can find the call in our logs. "4d1fe223-53e7-498d-a54a-4fb2f9314734" Example ``` { "success": true, "data": [ { "coin": "BTC", "symbol": "BTC", "timestamp": "2026-04-30 17:13:07.908", "bids": [ { "px": 76183, "sz": 75.5, "n": 405 }, { "px": 76182, "sz": 32.2, "n": 88 } ], "asks": [ { "px": 76184, "sz": 0.44, "n": 5 }, { "px": 76185, "sz": 1.32, "n": 12 } ], "bid_levels": 12649, "ask_levels": 8032, "total_bid_size": 5878.9, "total_ask_size": 4405.5, "mid_price": 76183.5, "spread": 1, "spread_bps": 0.13 } ], "meta": { "count": 1, "next_cursor": "1761840000596_907964252522803", "request_id": "4d1fe223-53e7-498d-a54a-4fb2f9314734" } } ``` Copy ### L2 Diff GET /v1/hyperliquid/orderbook/:symbol/l2/diffs and HIP-3 / HIP-4 equivalents — tick-level price-level changes Schema success boolean required Always `true` on a 2xx response. Errors return `success: false` with an `error` field. true data array required Array of result items. Item object timestamp string required Diff timestamp (ISO 8601) "2026-04-29T17:13:54.739+00:00" block_number integer required Block number of the change 977546590 price number required Price level changed 75799 size number required New aggregate size at this level (0 if level cleared) 2.05 count integer required New order count at this level 5 side string required "B" (bid) or "A" (ask) "B" meta object required Response metadata. Inspect this to drive cursor pagination and trace requests. count integer required Number of items returned in this page. 100 next_cursor string Opaque cursor for the next page. Omitted on the final page — when missing, you have reached the end of the range. "1761840000596_907964252522803" request_id string required UUID for this request. Include it when contacting support so we can find the call in our logs. "4d1fe223-53e7-498d-a54a-4fb2f9314734" Example ``` { "success": true, "data": [ { "timestamp": "2026-04-29T17:13:54.739+00:00", "block_number": 977546590, "price": 75799, "size": 2.05, "count": 5, "side": "B" } ], "meta": { "count": 1, "next_cursor": "1761840000596_907964252522803", "request_id": "4d1fe223-53e7-498d-a54a-4fb2f9314734" } } ``` Copy ### L3 Order Book (Lighter) GET /v1/lighter/l3orderbook/:symbol — single snapshot Schema success boolean required Always `true` on a 2xx response. Errors return `success: false` with an `error` field. true data object required Response payload. coin string required Trading pair symbol "BTC" timestamp string required Snapshot timestamp (ISO 8601) "2026-04-30T17:11:01.247Z" orders array required Individual orders in the book Order object order_index integer required Unique Lighter order index 562952175455810 owner_account_index integer required Lighter account index of the order's owner 102394 side string required "bid" or "ask" "ask" price number required Limit price 76281.7 remaining_size number required Remaining size on the book 0.39322 original_size number required Size at placement 0.39322 bid_count integer required Total bid orders in book 1250 ask_count integer required Total ask orders in book 980 total_bid_size number Aggregate bid size across all orders 450.5 total_ask_size number Aggregate ask size across all orders 380.2 mid_price number Mid price 76357.95 spread number Spread in absolute terms 1 spread_bps number Spread in basis points 0.13 meta object required Response metadata. Inspect this to drive cursor pagination and trace requests. count integer required Number of items returned. For object responses, always 1. 1 request_id string required UUID for this request. Include it when contacting support so we can find the call in our logs. "4d1fe223-53e7-498d-a54a-4fb2f9314734" Example ``` { "success": true, "data": { "coin": "BTC", "timestamp": "2026-04-30T17:11:01.247Z", "orders": [ { "order_index": 562952175455810, "owner_account_index": 102394, "side": "ask", "price": 76281.7, "remaining_size": 0.39322, "original_size": 0.39322 }, { "order_index": 844422671662026, "owner_account_index": 390028, "side": "bid", "price": 76207.4, "remaining_size": 3.57799, "original_size": 3.57799 } ], "bid_count": 1250, "ask_count": 980, "total_bid_size": 450.5, "total_ask_size": 380.2, "mid_price": 76244.55, "spread": 1, "spread_bps": 0.13 }, "meta": { "count": 1, "request_id": "4d1fe223-53e7-498d-a54a-4fb2f9314734" } } ``` Copy ### L3 Order Book (history) GET /v1/lighter/l3orderbook/:symbol/history — paginated snapshots Schema success boolean required Always `true` on a 2xx response. Errors return `success: false` with an `error` field. true data array required Array of result items. Item object coin string required Trading pair symbol "BTC" timestamp string required Snapshot timestamp (ISO 8601) "2026-04-30T17:11:01.247Z" orders array required Individual orders in the book Order object order_index integer required Unique Lighter order index 562952175455810 owner_account_index integer required Lighter account index of the order's owner 102394 side string required "bid" or "ask" "ask" price number required Limit price 76281.7 remaining_size number required Remaining size on the book 0.39322 original_size number required Size at placement 0.39322 bid_count integer required Total bid orders in book 1250 ask_count integer required Total ask orders in book 980 total_bid_size number Aggregate bid size across all orders 450.5 total_ask_size number Aggregate ask size across all orders 380.2 mid_price number Mid price 76357.95 spread number Spread in absolute terms 1 spread_bps number Spread in basis points 0.13 meta object required Response metadata. Inspect this to drive cursor pagination and trace requests. count integer required Number of items returned in this page. 100 next_cursor string Opaque cursor for the next page. Omitted on the final page — when missing, you have reached the end of the range. "1761840000596_907964252522803" request_id string required UUID for this request. Include it when contacting support so we can find the call in our logs. "4d1fe223-53e7-498d-a54a-4fb2f9314734" Example ``` { "success": true, "data": [ { "coin": "BTC", "timestamp": "2026-04-30T17:11:01.247Z", "orders": [ { "order_index": 562952175455810, "owner_account_index": 102394, "side": "ask", "price": 76281.7, "remaining_size": 0.39322, "original_size": 0.39322 }, { "order_index": 844422671662026, "owner_account_index": 390028, "side": "bid", "price": 76207.4, "remaining_size": 3.57799, "original_size": 3.57799 } ], "bid_count": 1250, "ask_count": 980, "total_bid_size": 450.5, "total_ask_size": 380.2, "mid_price": 76244.55, "spread": 1, "spread_bps": 0.13 } ], "meta": { "count": 1, "next_cursor": "1761840000596_907964252522803", "request_id": "4d1fe223-53e7-498d-a54a-4fb2f9314734" } } ``` Copy ## Order lifecycle and flow (Pro+) Order placements, cancellations, fills, TP/SL events, and aggregated buy/sell flow. ### Order History GET /v1/hyperliquid/orders/:symbol/history and HIP-3 / HIP-4 equivalents Schema success boolean required Always `true` on a 2xx response. Errors return `success: false` with an `error` field. true data array required Array of result items. Item object timestamp string required Event timestamp (ISO 8601) "2026-03-12T12:00:01Z" block_time string required Block timestamp "2026-03-12T12:00:01Z" block_number integer required Block number 921540000 seq integer required Sequence number within the block 641 coin string required Trading pair symbol "BTC" user_address string required Wallet address of order owner "0x1234...abcd" status string required Order status: open, filled, canceled, triggered, force_canceled "canceled" side string required "B" (buy) or "A" (sell) "B" limit_price number required Limit price 68313 size number required Current remaining size 0.0029 orig_size number required Original order size 0.0029 oid integer required Unique order ID 403692588220 order_type string required Type: Limit, Stop Market, etc. "Limit" is_trigger boolean Whether the order is a trigger order false is_position_tpsl boolean Whether the order is a position TP/SL false reduce_only boolean Whether the order is reduce-only false tif string Time-in-force: Gtc, Ioc, Alo "Alo" cloid string Client order ID (if set) "0x00000000000000000b56a219d5668a74" meta object required Response metadata. Inspect this to drive cursor pagination and trace requests. count integer required Number of items returned in this page. 100 next_cursor string Opaque cursor for the next page. Omitted on the final page — when missing, you have reached the end of the range. "1761840000596_907964252522803" request_id string required UUID for this request. Include it when contacting support so we can find the call in our logs. "4d1fe223-53e7-498d-a54a-4fb2f9314734" Example ``` { "success": true, "data": [ { "timestamp": "2026-04-29T17:14:31.588Z", "block_time": "2026-04-29T17:14:31.588Z", "block_number": 977548020, "seq": 641, "coin": "BTC", "user_address": "0x162cc7c861ebd0c06b3d72319201150482518185", "status": "canceled", "side": "B", "limit_price": 68313, "size": 0.0029, "orig_size": 0.0029, "oid": 403692588220, "order_type": "Limit", "is_trigger": false, "is_position_tpsl": false, "reduce_only": false, "tif": "Alo", "cloid": "0x00000000000000000b56a219d5668a74" } ], "meta": { "count": 1, "next_cursor": "1761840000596_907964252522803", "request_id": "4d1fe223-53e7-498d-a54a-4fb2f9314734" } } ``` Copy ### TP / SL Order History GET /v1/hyperliquid/orders/:symbol/tpsl and HIP-3 / HIP-4 equivalents — trigger and TP/SL orders Schema success boolean required Always `true` on a 2xx response. Errors return `success: false` with an `error` field. true data array required Array of result items. Item object timestamp string required Event timestamp (ISO 8601) "2026-04-29T17:14:32.795Z" block_time string required Block timestamp "2026-04-29T17:14:32.795Z" block_number integer required Block number 977548038 seq integer required Sequence number within the block 2748 coin string required Trading pair symbol "BTC" user_address string required Wallet address of order owner "0x58a90dfa54eca4027bee2c23b931a8fd596e7261" status string required Order status (e.g., open, triggered, reduceOnlyCanceled) "reduceOnlyCanceled" side string required "B" (buy) or "A" (sell) "B" limit_price number required Trigger limit price 76503 size number required Remaining size 0.00024 orig_size number required Original order size 0.00024 oid integer required Unique order ID 403666382043 order_type string required Type: Stop Market, Stop Limit, Take Profit Market, Take Profit Limit "Stop Market" trigger_condition string required Human-readable trigger condition "Price above 76503" trigger_price number Numeric trigger price 76503 is_trigger boolean Always true for TP/SL orders true is_position_tpsl boolean Whether attached to a position false reduce_only boolean Whether the order is reduce-only true meta object required Response metadata. Inspect this to drive cursor pagination and trace requests. count integer required Number of items returned in this page. 100 next_cursor string Opaque cursor for the next page. Omitted on the final page — when missing, you have reached the end of the range. "1761840000596_907964252522803" request_id string required UUID for this request. Include it when contacting support so we can find the call in our logs. "4d1fe223-53e7-498d-a54a-4fb2f9314734" Example ``` { "success": true, "data": [ { "timestamp": "2026-04-29T17:14:32.795Z", "block_time": "2026-04-29T17:14:32.795Z", "block_number": 977548038, "seq": 2748, "coin": "BTC", "user_address": "0x58a90dfa54eca4027bee2c23b931a8fd596e7261", "status": "reduceOnlyCanceled", "side": "B", "limit_price": 76503, "size": 0.00024, "orig_size": 0.00024, "oid": 403666382043, "order_type": "Stop Market", "trigger_condition": "Price above 76503", "trigger_price": 76503, "is_trigger": true, "is_position_tpsl": false, "reduce_only": true } ], "meta": { "count": 1, "next_cursor": "1761840000596_907964252522803", "request_id": "4d1fe223-53e7-498d-a54a-4fb2f9314734" } } ``` Copy ### Order Flow GET /v1/hyperliquid/orders/:symbol/flow and HIP-3 / HIP-4 equivalents — bucketed activity counts Schema success boolean required Always `true` on a 2xx response. Errors return `success: false` with an `error` field. true data array required Array of result items. Item object timestamp string required Bucket start timestamp (ISO 8601) "2026-03-12T12:00:00Z" limit_orders_placed integer required Limit orders placed in bucket 342 orders_canceled integer required Orders canceled in bucket 128 orders_filled integer required Orders filled in bucket 89 trigger_orders_placed integer required Trigger orders placed 15 tpsl_orders_placed integer required TP/SL orders placed 7 orders_triggered integer required Orders triggered 3 orders_force_canceled integer required Orders force-canceled 0 meta object required Response metadata. Inspect this to drive cursor pagination and trace requests. count integer required Number of items returned. For object responses, always 1. 1 request_id string required UUID for this request. Include it when contacting support so we can find the call in our logs. "4d1fe223-53e7-498d-a54a-4fb2f9314734" Example ``` { "success": true, "data": [ { "timestamp": "2026-04-29T17:00:00Z", "limit_orders_placed": 947692, "orders_canceled": 935453, "orders_filled": 14197, "trigger_orders_placed": 2396, "tpsl_orders_placed": 621, "orders_triggered": 799, "orders_force_canceled": 1950 } ], "meta": { "count": 1, "request_id": "4d1fe223-53e7-498d-a54a-4fb2f9314734" } } ``` Copy ## Data Quality Data Quality routes return a custom shape — they do **not** use the standard `success` / `data` / `meta` envelope. The schemas below show the entire response body. ### System Status GET /v1/data-quality/status — overall health and per-exchange / per-data-type status Schema status string required Overall system status: operational, degraded, down "operational" updated_at string required Status timestamp (ISO 8601) "2026-04-30T17:15:00Z" exchanges object required Per-exchange status keyed by exchange id (hyperliquid, spot, lighter, hip3, hip4) object status string required operational, degraded, down "operational" last_data_at string Most recent ingestion timestamp (ISO 8601) "2026-04-30T17:14:55Z" latency_ms integer Current ingestion lag in milliseconds 1601 data_types object required Per-data-type status (orderbook, fills, funding, open_interest) object status string required operational, degraded, down "operational" completeness_24h number Percentage of expected data captured in the last 24 hours 100 active_incidents integer required Number of currently open incidents 0 Example ``` { "status": "operational", "updated_at": "2026-04-30T17:15:00Z", "exchanges": { "hyperliquid": { "status": "operational", "last_data_at": "2026-04-30T17:14:55Z", "latency_ms": 1601 }, "lighter": { "status": "operational", "last_data_at": "2026-04-30T17:14:55Z", "latency_ms": 51248 }, "hip3": { "status": "operational", "last_data_at": "2026-04-30T17:14:55Z", "latency_ms": 525 }, "hip4": { "status": "operational", "last_data_at": "2026-04-30T17:14:55Z", "latency_ms": 612 } }, "data_types": { "orderbook": { "status": "operational", "completeness_24h": 100 }, "fills": { "status": "operational", "completeness_24h": 99.9 }, "funding": { "status": "operational", "completeness_24h": 98.5 }, "open_interest": { "status": "operational", "completeness_24h": 98.5 } }, "active_incidents": 0 } ``` Copy ### Exchange Coverage GET /v1/data-quality/coverage and /v1/data-quality/coverage/:exchange Schema exchange string required Exchange identifier "hyperliquid" data_types object required Coverage keyed by data type object fills, funding, l4_checkpoints, orderbook, open_interest, orders, liquidations, etc. earliest string required Earliest datapoint (ISO 8601) "2023-04-15T00:00:07Z" latest string required Most recent datapoint (ISO 8601) "2026-04-30T17:15:16Z" total_records integer required Cumulative record count 23262965687 symbols integer Number of symbols covered (exchange-level) 190 completeness number Percentage of expected data present 100 historical_coverage number Percentage of historical range covered 100 resolution string Typical sampling resolution where applicable "~1.2 seconds" lag string Approximate ingestion lag "~1 hour" Example ``` { "exchange": "hyperliquid", "data_types": { "orderbook": { "earliest": "2023-04-15T00:00:07Z", "latest": "2026-04-30T17:15:16Z", "total_records": 23262965687, "symbols": 190, "resolution": "~1.2 seconds", "completeness": 100, "historical_coverage": 100 }, "fills": { "earliest": "2023-04-15T03:31:18Z", "latest": "2026-04-30T17:15:07Z", "total_records": 2507165257, "symbols": 200, "lag": "~1 hour", "completeness": 99.9, "historical_coverage": 100 } } } ``` Copy ### Symbol Coverage GET /v1/data-quality/coverage/:exchange/:symbol — per-symbol gap detection and cadence Schema exchange string required Exchange identifier "hyperliquid" symbol string required Trading pair symbol "BTC" data_types object required Coverage keyed by data type (orderbook, fills, funding, open_interest, etc.) object earliest string required Earliest datapoint (ISO 8601) "2023-05-20T02:50:04Z" latest string required Most recent datapoint (ISO 8601) "2026-04-30T17:09:39.281Z" total_records integer required Cumulative record count for the symbol 1525080 completeness number Percentage of expected data present 100 historical_coverage number Percentage of historical range covered 98.8 gaps array Detected gap windows in the requested range Gap object start string required "2026-04-25T07:32:53.589Z" end string required "2026-04-25T07:35:07.775Z" duration_minutes number 2.24 cadence object Empirical sampling cadence for the data type median_interval_seconds number 61 p95_interval_seconds number 61 sample_count integer 1418 Example ``` { "exchange": "hyperliquid", "symbol": "BTC", "data_types": { "orderbook": { "earliest": "2023-04-15T00:00:07.400Z", "latest": "2026-04-30T17:10:03.608Z", "total_records": 171749724, "completeness": 100, "historical_coverage": 98.2, "gaps": [ { "start": "2026-04-25T07:32:53.589Z", "end": "2026-04-25T07:35:07.775Z", "duration_minutes": 2.24 } ], "cadence": { "median_interval_seconds": 1.2, "p95_interval_seconds": 3, "sample_count": 66123 } } } } ``` Copy ### Incidents (list) GET /v1/data-quality/incidents — uses limit/offset pagination, not cursor Schema incidents array required Page of incidents matching the filters Incident object id string required Incident identifier "INC-2026-001" status string required open or resolved "resolved" severity string required critical, major, minor "major" exchange string required "lighter" data_types array string string "orderbook" symbols_affected array Affected symbols, or ["ALL"] string string "ALL" started_at string required "2026-02-12T22:02:03Z" resolved_at string Null until the incident closes "2026-02-12T22:52:00Z" duration_minutes integer 49 title string required "Lighter.xyz upstream outage" description string "Lighter.xyz experienced a service disruption..." root_cause string "Lighter.xyz upstream service disruption" resolution string "Lighter.xyz services recovered on their own." pagination object required Offset/limit pagination — incidents use offset rather than cursors total integer required 42 limit integer required 50 offset integer required 0 Example ``` { "incidents": [ { "id": "INC-2026-001", "status": "resolved", "severity": "major", "exchange": "lighter", "data_types": [ "orderbook", "fills", "funding", "open_interest" ], "symbols_affected": [ "ALL" ], "started_at": "2026-02-12T22:02:03Z", "resolved_at": "2026-02-12T22:52:00Z", "duration_minutes": 49, "title": "Lighter.xyz upstream outage", "description": "Service disruption — 50-min gap across all symbols.", "root_cause": "Upstream service disruption.", "resolution": "Recovered on their own." } ], "pagination": { "total": 1, "limit": 50, "offset": 0 } } ``` Copy ### Incident (detail) GET /v1/data-quality/incidents/:id Schema id string required Incident identifier "INC-2026-001" status string required open or resolved "resolved" severity string required critical, major, minor "major" exchange string required "lighter" data_types array string string "orderbook" symbols_affected array Affected symbols, or ["ALL"] string string "ALL" started_at string required "2026-02-12T22:02:03Z" resolved_at string Null until the incident closes "2026-02-12T22:52:00Z" duration_minutes integer 49 title string required "Lighter.xyz upstream outage" description string "Lighter.xyz experienced a service disruption..." root_cause string "Lighter.xyz upstream service disruption" resolution string "Lighter.xyz services recovered on their own." Example ``` { "id": "INC-2026-001", "status": "resolved", "severity": "major", "exchange": "lighter", "data_types": [ "orderbook", "fills", "funding", "open_interest" ], "symbols_affected": [ "ALL" ], "started_at": "2026-02-12T22:02:03Z", "resolved_at": "2026-02-12T22:52:00Z", "duration_minutes": 49, "title": "Lighter.xyz upstream outage", "description": "Service disruption — 50-min gap across all symbols.", "root_cause": "Upstream service disruption.", "resolution": "Recovered on their own." } ``` Copy ### Latency GET /v1/data-quality/latency — current WebSocket and ingestion lag Schema measured_at string required Server time when latency was sampled (ISO 8601) "2026-04-30T17:10:11.613Z" exchanges object required Latency metrics keyed by exchange object websocket object current_ms integer required 2049 avg_1h_ms integer 2049 avg_24h_ms integer 2049 data_freshness object orderbook_lag_ms integer 2049 fills_lag_ms integer 5349 funding_lag_ms integer 32332 oi_lag_ms integer 32332 Example ``` { "measured_at": "2026-04-30T17:10:11.613Z", "exchanges": { "hyperliquid": { "websocket": { "current_ms": 2049, "avg_1h_ms": 2049, "avg_24h_ms": 2049 }, "data_freshness": { "orderbook_lag_ms": 2049, "fills_lag_ms": 5349, "funding_lag_ms": 32332, "oi_lag_ms": 32332 } }, "lighter": { "websocket": { "current_ms": 32961, "avg_1h_ms": 32961, "avg_24h_ms": 32961 }, "data_freshness": { "orderbook_lag_ms": 32961, "fills_lag_ms": 45008, "funding_lag_ms": 8988, "oi_lag_ms": 8870 } } } } ``` Copy ### SLA GET /v1/data-quality/sla — monthly compliance Schema period string required YYYY-MM month identifier "2026-03" sla_targets object required Targets for the period uptime number required 99.9 data_completeness number required 99.5 api_latency_p99_ms integer required 500 actual object required Measured values for the period uptime number required 99.999 uptime_status string required met, missed "met" data_completeness object orderbook number 83.3 fills number 83.3 funding number 83.3 overall number 83.3 completeness_status string "missed" api_latency_p99_ms integer 32662 latency_status string "missed" incidents_this_period integer required 0 total_downtime_minutes integer required 0 Example ``` { "period": "2026-03", "sla_targets": { "uptime": 99.9, "data_completeness": 99.5, "api_latency_p99_ms": 500 }, "actual": { "uptime": 99.999, "uptime_status": "met", "data_completeness": { "orderbook": 83.3, "fills": 83.3, "funding": 83.3, "overall": 83.3 }, "completeness_status": "missed", "api_latency_p99_ms": 32662, "latency_status": "missed" }, "incidents_this_period": 0, "total_downtime_minutes": 0 } ``` Copy