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 envelopeJSON
{
  "success": true,
  "data": [ /* one item per row */ ],
  "meta": {
    "count": 1000,
    "next_cursor": "1761840000596_907964252522803",
    "request_id": "4d1fe223-53e7-498d-a54a-4fb2f9314734"
  }
}
FieldDescription
successAlways true on a 2xx response. Errors return success: false with an error field.
dataPayload. Object for single-snapshot routes (/orderbook/:symbol, /summary/:symbol) and an array for series and history routes.
meta.countNumber of items returned in data.
meta.next_cursorCursor for the next page on paginated routes. Missing means you have reached the final page.
meta.request_idUUID 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
ConceptHow it behaves
limitPage size. Default 100, max 1000 on most routes. Larger pages reduce round trips.
cursorOnly set this on the second request and beyond. Pass meta.next_cursor from the previous response verbatim.
Stop conditionWhen the response omits meta.next_cursor, you have reached the end of the requested start/end window.
IdempotenceCursors are stable across retries within the same window. A 5xx that returns the same cursor is safe to retry.
DQ incidentsData 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
successbooleanrequired
Always `true` on a 2xx response. Errors return `success: false` with an `error` field.true
dataobjectrequired
Response payload.
symbolstringrequired
Trading pair symbol (preferred)"BTC"
coinstringrequired
Trading pair symbol (deprecated, use symbol)"BTC"
timestampstringrequired
Snapshot timestamp (ISO 8601)"2026-01-01T12:00:00Z"
bidsarray<object>required
Bid price levels (best bid first)
PriceLevelobject
pxstringrequired
Price at this level"42150.50"
szstringrequired
Total size at this level"2.5"
nintegerrequired
Number of orders5
asksarray<object>required
Ask price levels (best ask first)
PriceLevelobject
pxstringrequired
Price at this level"42151.00"
szstringrequired
Total size at this level"1.8"
nintegerrequired
Number of orders3
mid_pricestring
Mid price (best bid + best ask) / 2"42150.75"
spreadstring
Spread in absolute terms"0.50"
spread_bpsstring
Spread in basis points"1.19"
metaobjectrequired
Response metadata. Inspect this to drive cursor pagination and trace requests.
countintegerrequired
Number of items returned. For object responses, always 1.1
request_idstringrequired
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"
  }
}

Symbol Summary

GET /v1/{venue}/summary/:symbol

Schema
successbooleanrequired
Always `true` on a 2xx response. Errors return `success: false` with an `error` field.true
dataobjectrequired
Response payload.
symbolstringrequired
Trading pair symbol (preferred)"BTC"
coinstringrequired
Trading pair symbol (deprecated, use symbol)"BTC"
timestampstringrequired
Summary timestamp (ISO 8601)"2026-01-01T12:00:00Z"
mark_pricestring
Current mark price"42150.75"
oracle_pricestring
Current oracle price"42148.50"
mid_pricestring
Current mid price (Hyperliquid/HIP-3/HIP-4 only; HIP-4 mid_price is implied probability in [0,1])"42150.75"
open_intereststring
Total open interest"12500.5"
funding_ratestring
Current funding rate"0.0001"
premiumstring
Funding premium (Hyperliquid/HIP-3 only)"0.00005"
volume_24hstring
24h notional volume (Hyperliquid only)"1250000000"
liquidation_volume_24hnumber
24h liquidation volume (Hyperliquid only)5000000
long_liquidation_volume_24hnumber
24h long liquidation volume3000000
short_liquidation_volume_24hnumber
24h short liquidation volume2000000
metaobjectrequired
Response metadata. Inspect this to drive cursor pagination and trace requests.
countintegerrequired
Number of items returned. For object responses, always 1.1
request_idstringrequired
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"
  }
}

Open Interest (current)

GET /v1/{venue}/openinterest/:symbol/current

Schema
successbooleanrequired
Always `true` on a 2xx response. Errors return `success: false` with an `error` field.true
dataobjectrequired
Response payload.
symbolstringrequired
Trading pair symbol (preferred)"BTC"
coinstringrequired
Trading pair symbol (deprecated, use symbol)"BTC"
timestampstringrequired
Snapshot timestamp (ISO 8601)"2026-01-01T12:00:00Z"
open_intereststringrequired
Total open interest in contracts"12500.5"
mark_pricestring
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_pricestring
Oracle price from external feed (omitted on HIP-4 — outcome markets have no oracle feed)"42148.50"
day_ntl_volumestring
24-hour notional volume"1250000000"
prev_day_pricestring
Price 24 hours ago"41500.00"
mid_pricestring
Current mid price (HIP-4: implied probability in [0,1])"42150.75"
impact_bid_pricestring
Best bid price after applying impact size — used by Hyperliquid for funding calculations"42150.00"
impact_ask_pricestring
Best ask price after applying impact size — used by Hyperliquid for funding calculations"42151.50"
metaobjectrequired
Response metadata. Inspect this to drive cursor pagination and trace requests.
countintegerrequired
Number of items returned. For object responses, always 1.1
request_idstringrequired
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"
  }
}

Funding Rate (current)

GET /v1/{venue}/funding/:symbol/current

Schema
successbooleanrequired
Always `true` on a 2xx response. Errors return `success: false` with an `error` field.true
dataobjectrequired
Response payload.
symbolstringrequired
Trading pair symbol (preferred)"BTC"
coinstringrequired
Trading pair symbol (deprecated, use symbol)"BTC"
timestampstringrequired
Funding timestamp (ISO 8601)"2026-01-01T00:00:00Z"
funding_ratestringrequired
Funding rate as decimal (0.0001 = 0.01%)"0.0001"
premiumstring
Premium component of funding rate (Hyperliquid/HIP-3 only)"0.00005"
metaobjectrequired
Response metadata. Inspect this to drive cursor pagination and trace requests.
countintegerrequired
Number of items returned. For object responses, always 1.1
request_idstringrequired
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"
  }
}

Symbol Freshness

GET /v1/{venue}/freshness/:symbol

Schema
successbooleanrequired
Always `true` on a 2xx response. Errors return `success: false` with an `error` field.true
dataobjectrequired
Response payload.
symbolstringrequired
Trading pair symbol (preferred)"BTC"
coinstringrequired
Trading pair symbol (deprecated, use symbol)"BTC"
exchangestringrequired
Source venue"hyperliquid"
measured_atstringrequired
Server time when this freshness was measured (ISO 8601)"2026-01-01T12:00:00.000Z"
orderbookobject
Order book freshness
last_updatedstringrequired
Most recent ingestion timestamp (ISO 8601)"2026-01-01T12:00:00Z"
lag_msintegerrequired
Milliseconds between last_updated and measured_at1929
tradesobject
Trade-stream freshness
last_updatedstringrequired
Most recent ingestion timestamp (ISO 8601)"2026-01-01T12:00:00Z"
lag_msintegerrequired
Milliseconds between last_updated and measured_at1929
fundingobject
Funding-rate freshness
last_updatedstringrequired
Most recent ingestion timestamp (ISO 8601)"2026-01-01T12:00:00Z"
lag_msintegerrequired
Milliseconds between last_updated and measured_at1929
open_interestobject
Open-interest freshness
last_updatedstringrequired
Most recent ingestion timestamp (ISO 8601)"2026-01-01T12:00:00Z"
lag_msintegerrequired
Milliseconds between last_updated and measured_at1929
liquidationsobject
Liquidation-stream freshness (Hyperliquid only)
last_updatedstringrequired
Most recent ingestion timestamp (ISO 8601)"2026-01-01T12:00:00Z"
lag_msintegerrequired
Milliseconds between last_updated and measured_at1929
metaobjectrequired
Response metadata. Inspect this to drive cursor pagination and trace requests.
countintegerrequired
Number of items returned. For object responses, always 1.1
request_idstringrequired
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"
  }
}

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
successbooleanrequired
Always `true` on a 2xx response. Errors return `success: false` with an `error` field.true
dataarray<object>required
Array of result items.
Itemobject
namestringrequired
Instrument symbol"BTC"
sz_decimalsintegerrequired
Decimal precision for size fields5
max_leverageintegerrequired
Maximum leverage allowed40
instrument_typestringrequired
Always "perp" today"perp"
is_activebooleanrequired
Whether the instrument is currently tradabletrue
metaobjectrequired
Response metadata. Inspect this to drive cursor pagination and trace requests.
countintegerrequired
Number of items returned. For object responses, always 1.1
request_idstringrequired
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"
  }
}

HIP-3 Instruments

GET /v1/hyperliquid/hip3/instruments and /v1/hyperliquid/hip3/instruments/:symbol

Schema
successbooleanrequired
Always `true` on a 2xx response. Errors return `success: false` with an `error` field.true
dataarray<object>required
Array of result items.
Itemobject
coinstringrequired
HIP-3 symbol (namespace:ticker)"km:US500"
namespacestringrequired
Builder namespace (e.g., km, xyz, cash)"km"
tickerstringrequired
Ticker within namespace"US500"
mark_pricenumber
Latest mark price715.36
open_interestnumber
Latest open interest4490.7
mid_pricenumber
Latest mid price715.355
latest_timestampstring
Last data point ISO timestamp"2026-04-30T17:10:19.439Z"
metaobjectrequired
Response metadata. Inspect this to drive cursor pagination and trace requests.
countintegerrequired
Number of items returned. For object responses, always 1.1
request_idstringrequired
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"
  }
}

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
successbooleanrequired
Always `true` on a 2xx response. Errors return `success: false` with an `error` field.true
dataarray<object>required
Array of result items.
Itemobject
outcome_idintegerrequired
Outcome market ID0
sideintegerrequired
Side index (0 = Yes, 1 = No)0
asset_idintegerrequired
Public asset_id (100_000_000 + 10*outcome_id + side)100000000
coinstringrequired
HIP-4 coin id. Also accepts #-prefixed form."0"
symbolstringrequired
Same as coin"0"
namestringrequired
Human-readable per-side label"BTC ≥ 78213 by 2026-05-03 06:00 UTC — Yes"
descriptionstring
Pipe-encoded recurring metadata"class:priceBinary|underlying:BTC|expiry:20260503-0600|targetPrice:78213|period:1d"
side_namestring
Side label ("Yes" or "No")"Yes"
recurring_classstring
Outcome class (e.g., priceBinary)"priceBinary"
recurring_underlyingstring
Underlying asset for the outcome"BTC"
recurring_expirystring
Settlement timestamp (ISO 8601)"2026-05-03T06:00:00Z"
recurring_target_pxnumber
Target price for the outcome78213
recurring_periodstring
Recurrence period (e.g., 1d)"1d"
builder_addressstring
Builder/deployer address"0x1234...abcd"
is_settledboolean
Whether the outcome has settledfalse
first_seen_atstring
First-seen ISO timestamp"2026-05-02T07:47:00Z"
last_updated_atstring
Last-updated ISO timestamp"2026-05-02T20:25:00Z"
metaobjectrequired
Response metadata. Inspect this to drive cursor pagination and trace requests.
countintegerrequired
Number of items returned. For object responses, always 1.1
request_idstringrequired
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"
  }
}

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
successbooleanrequired
Always `true` on a 2xx response. Errors return `success: false` with an `error` field.true
dataarray<object>required
Array of result items.
Itemobject
outcome_idintegerrequired
Outcome market ID0
namestringrequired
Human-readable outcome name"BTC ≥ 78213 by 2026-05-03 06:00 UTC"
description_rawstring
Pipe-encoded recurring metadata"class:priceBinary|underlying:BTC|expiry:20260503-0600|targetPrice:78213|period:1d"
classstring
Outcome class (e.g., priceBinary)"priceBinary"
underlyingstring
Underlying asset"BTC"
expirystring
Settlement timestamp (ISO 8601)"2026-05-03T06:00:00Z"
target_pricenumber
Target price for the outcome78213
periodstring
Recurrence period"1d"
side_specsarray<object>required
Per-side coin/asset_id mapping (Yes and No sides)
SideSpecobject
sideintegerrequired
Side index (0 = Yes, 1 = No)0
namestringrequired
Side label"Yes"
coinstringrequired
HIP-4 coin id. Also accepts #-prefixed form."0"
asset_idintegerrequired
100_000_000 + 10*outcome_id + side100000000
is_settledboolean
Whether the outcome has settledfalse
statusstring
Lifecycle status: "live" or "settled""live"
source_seen_atstring
Latest upstream observation timestamp"2026-05-02T20:25:00Z"
aggregated_oiobject
Both-sides OI aggregate. Present on /outcomes/{outcome_id} detail; omitted on /outcomes list.
side0_open_interest_contractsnumber
Latest Yes-side OI in contracts568048
side1_open_interest_contractsnumber
Latest No-side OI in contracts568048
outcome_display_open_interest_contractsnumber
Display OI (sum of both sides)1136096
paired_set_supply_contractsnumber
Paired-set supply (one of the sides when parity holds)568048
side_supply_parityboolean
True when both sides have equal supply (typical for fully-collateralized outcome markets)true
currencystring
Currency for notional values"USDH"
as_ofstring
Aggregate as-of timestamp"2026-05-02T20:27:21Z"
side0_as_ofstring
Yes-side OI as-of timestamp"2026-05-02T20:27:21Z"
side1_as_ofstring
No-side OI as-of timestamp"2026-05-02T20:27:21Z"
metaobjectrequired
Response metadata. Inspect this to drive cursor pagination and trace requests.
countintegerrequired
Number of items returned. For object responses, always 1.1
request_idstringrequired
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"
  }
}

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 @<n> in URLs.

Schema
successbooleanrequired
Always `true` on a 2xx response. Errors return `success: false` with an `error` field.true
dataarray<object>required
Array of result items.
Itemobject
symbolstringrequired
Dashed pair symbol used everywhere in the API (e.g., PURR-USDC, HYPE-USDC, HFUN-USDC)."PURR-USDC"
basestringrequired
Base token of the pair"PURR"
quotestringrequired
Quote token of the pair (USDC, USDT0, USDH, ...)"USDC"
wirestring
Hyperliquid wire-format coin (slash form). Used internally; not required to call the API."PURR/USDC"
pair_indexinteger
Numeric pair index (the @<n> form). 0xArchive does not accept @<n> in URLs; always use the dashed symbol.107
metaobjectrequired
Response metadata. Inspect this to drive cursor pagination and trace requests.
countintegerrequired
Number of items returned. For object responses, always 1.1
request_idstringrequired
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"
  }
}

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
successbooleanrequired
Always `true` on a 2xx response. Errors return `success: false` with an `error` field.true
dataarray<object>required
Array of result items.
Itemobject
symbolstringrequired
Dashed spot symbol (preferred). The server resolves the wire format (e.g., PURR/USDC, @<index>) internally."PURR-USDC"
coinstringrequired
Wire-format spot coin (legacy). Use `symbol` in new code."PURR/USDC"
sidestringrequired
Trade side: "A" (ask/sell) or "B" (bid/buy)"B"
pricestringrequired
Execution price"0.32152"
sizestringrequired
Trade size in base token"1502.0"
timestampstringrequired
Execution timestamp (ISO 8601)"2026-05-05T17:13:24.733Z"
tx_hashstring
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_idinteger
Unique trade ID1003245567
order_idinteger
Associated order ID89567103221
crossedboolean
True if taker (crossed spread), false if makertrue
feestring
Trading fee amount"0.4824"
fee_tokenstring
Fee denomination. Spot fees are open-set: USDC, PURR, HYPE, KHYPE, USOL, etc. Pre-validate the value rather than assuming USDC."USDC"
user_addressstring
User's wallet address for this fill"0x9a3c...1e2f"
builder_addressstring
Builder address that routed this order. Present only when the order was placed through a builder."0x4950...9395"
builder_feestring
Builder fee charged on this fill, paid to the builder. Present only when builder_address is set."0.024"
twap_idinteger
Parent TWAP execution ID. Present when the fill is a slice of a TWAP order; null otherwise.7732
directionstring
Spot direction label: "Buy" or "Sell". Spot has no Open/Close/Long/Short concepts."Buy"
metaobjectrequired
Response metadata. Inspect this to drive cursor pagination and trace requests.
countintegerrequired
Number of items returned in this page.100
next_cursorstring
Opaque cursor for the next page. Omitted on the final page — when missing, you have reached the end of the range."1761840000596_907964252522803"
request_idstringrequired
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"
  }
}

Spot TWAP

GET /v1/hyperliquid/spot/twap/:symbol and /v1/hyperliquid/spot/twap/user/:user. Live-only from 2026-05-05.

Schema
successbooleanrequired
Always `true` on a 2xx response. Errors return `success: false` with an `error` field.true
dataarray<object>required
Array of result items.
Itemobject
symbolstringrequired
Dashed spot symbol"HYPE-USDC"
coinstring
Wire-format spot coin"HYPE/USDC"
twap_idintegerrequired
Parent TWAP execution ID. All slices of one TWAP share this id.7732
user_addressstringrequired
User's wallet address driving the TWAP"0x44ad...8b9c"
sidestringrequired
TWAP side: "A" (sell) or "B" (buy)"A"
slice_pricestring
Price for this slice"24.875"
slice_sizestring
Size for this slice in base token"12.3"
timestampstringrequired
Slice execution timestamp (ISO 8601)"2026-05-05T17:13:25.119Z"
parent_total_sizestring
Total intended TWAP size (base token)"120.0"
completed_sizestring
Cumulative completed size after this slice"36.9"
statusstring
Lifecycle status: progressing, completed, canceled, expired"progressing"
metaobjectrequired
Response metadata. Inspect this to drive cursor pagination and trace requests.
countintegerrequired
Number of items returned in this page.100
next_cursorstring
Opaque cursor for the next page. Omitted on the final page — when missing, you have reached the end of the range."1761840000596_907964252522803"
request_idstringrequired
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"
  }
}

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
successbooleanrequired
Always `true` on a 2xx response. Errors return `success: false` with an `error` field.true
dataarray<object>required
Array of result items.
Itemobject
symbolstringrequired
Trading pair symbol (preferred)"ETH"
coinstringrequired
Trading pair symbol (deprecated, use symbol)"ETH"
sidestringrequired
Trade side: "A" (ask/sell) or "B" (bid/buy)"B"
pricestringrequired
Execution price"2250.50"
sizestringrequired
Trade size"1.5"
timestampstringrequired
Execution timestamp (ISO 8601)"2026-01-01T12:00:00Z"
tx_hashstring
Blockchain transaction hash (Hyperliquid)"0x..."
trade_idinteger
Unique trade ID12345678
order_idinteger
Associated order ID987654321
crossedboolean
True if taker (crossed spread), false if makertrue
feestring
Trading fee amount"0.45"
fee_tokenstring
Fee denomination"USDC"
closed_pnlstring
Realized PnL if closing position"125.50"
directionstring
Position direction (e.g., 'Open Long', 'Close Short', 'Long > Short')"Open Long"
start_positionstring
Position size before trade"10.5"
user_addressstring
User's wallet address (fill-level data)"0x..."
maker_addressstring
Maker's wallet address (market-level trades)"0x..."
taker_addressstring
Taker's wallet address (market-level trades)"0x..."
account_indexstring
Lighter account index. Lighter trades use account_index instead of user_address"59774"
builder_addressstring
Builder address that routed this order. Present only when the order was placed through a builder"0xb84c..."
builder_feestring
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_feestring
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_gasnumber
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 priority3e-8
cloidstring
Client order ID"0x00000000000000000006..."
twap_idinteger
TWAP execution ID1750482
metaobjectrequired
Response metadata. Inspect this to drive cursor pagination and trace requests.
countintegerrequired
Number of items returned in this page.100
next_cursorstring
Opaque cursor for the next page. Omitted on the final page — when missing, you have reached the end of the range."1761840000596_907964252522803"
request_idstringrequired
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"
  }
}

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
successbooleanrequired
Always `true` on a 2xx response. Errors return `success: false` with an `error` field.true
dataarray<object>required
Array of result items.
Itemobject
symbolstringrequired
Trading pair symbol (preferred)"ETH"
coinstringrequired
Trading pair symbol (deprecated, use symbol)"ETH"
sidestringrequired
Trade side: "A" (ask/sell) or "B" (bid/buy)"B"
pricestringrequired
Execution price"2250.50"
sizestringrequired
Trade size"1.5"
timestampstringrequired
Execution timestamp (ISO 8601)"2026-01-01T12:00:00Z"
tx_hashstring
Blockchain transaction hash (Hyperliquid)"0x..."
trade_idinteger
Unique trade ID12345678
order_idinteger
Associated order ID987654321
crossedboolean
True if taker (crossed spread), false if makertrue
feestring
Trading fee amount"0.45"
fee_tokenstring
Fee denomination"USDC"
closed_pnlstring
Realized PnL if closing position"125.50"
directionstring
Position direction (e.g., 'Open Long', 'Close Short', 'Long > Short')"Open Long"
start_positionstring
Position size before trade"10.5"
user_addressstring
User's wallet address (fill-level data)"0x..."
maker_addressstring
Maker's wallet address (market-level trades)"0x..."
taker_addressstring
Taker's wallet address (market-level trades)"0x..."
account_indexstring
Lighter account index. Lighter trades use account_index instead of user_address"59774"
builder_addressstring
Builder address that routed this order. Present only when the order was placed through a builder"0xb84c..."
builder_feestring
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_feestring
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_gasnumber
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 priority3e-8
cloidstring
Client order ID"0x00000000000000000006..."
twap_idinteger
TWAP execution ID1750482
metaobjectrequired
Response metadata. Inspect this to drive cursor pagination and trace requests.
countintegerrequired
Number of items returned. For object responses, always 1.1
request_idstringrequired
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"
  }
}

Order Book History

GET /v1/{venue}/orderbook/:symbol/history — checkpoint-rate snapshots (or sub-second on Lighter granularity options)

Schema
successbooleanrequired
Always `true` on a 2xx response. Errors return `success: false` with an `error` field.true
dataarray<object>required
Array of result items.
Itemobject
symbolstringrequired
Trading pair symbol (preferred)"BTC"
coinstringrequired
Trading pair symbol (deprecated, use symbol)"BTC"
timestampstringrequired
Snapshot timestamp (ISO 8601)"2026-01-01T12:00:00Z"
bidsarray<object>required
Bid price levels (best bid first)
PriceLevelobject
pxstringrequired
Price at this level"42150.50"
szstringrequired
Total size at this level"2.5"
nintegerrequired
Number of orders5
asksarray<object>required
Ask price levels (best ask first)
PriceLevelobject
pxstringrequired
Price at this level"42151.00"
szstringrequired
Total size at this level"1.8"
nintegerrequired
Number of orders3
mid_pricestring
Mid price (best bid + best ask) / 2"42150.75"
spreadstring
Spread in absolute terms"0.50"
spread_bpsstring
Spread in basis points"1.19"
metaobjectrequired
Response metadata. Inspect this to drive cursor pagination and trace requests.
countintegerrequired
Number of items returned in this page.100
next_cursorstring
Opaque cursor for the next page. Omitted on the final page — when missing, you have reached the end of the range."1761840000596_907964252522803"
request_idstringrequired
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"
  }
}

Candles

GET /v1/{venue}/candles/:symbol

Schema
successbooleanrequired
Always `true` on a 2xx response. Errors return `success: false` with an `error` field.true
dataarray<object>required
Array of result items.
Itemobject
timestampstringrequired
Candle open timestamp (ISO 8601)"2026-01-01T12:00:00Z"
opennumberrequired
Opening price42150.5
highnumberrequired
Highest price in interval42200
lownumberrequired
Lowest price in interval42100
closenumberrequired
Closing price42180
volumenumberrequired
Volume in base asset125.5
quote_volumenumber
Volume in quote asset (USD)5290000
trade_countinteger
Number of trades in interval1234
metaobjectrequired
Response metadata. Inspect this to drive cursor pagination and trace requests.
countintegerrequired
Number of items returned in this page.100
next_cursorstring
Opaque cursor for the next page. Omitted on the final page — when missing, you have reached the end of the range."1761840000596_907964252522803"
request_idstringrequired
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"
  }
}

Funding History

GET /v1/{venue}/funding/:symbol

Schema
successbooleanrequired
Always `true` on a 2xx response. Errors return `success: false` with an `error` field.true
dataarray<object>required
Array of result items.
Itemobject
symbolstringrequired
Trading pair symbol (preferred)"BTC"
coinstringrequired
Trading pair symbol (deprecated, use symbol)"BTC"
timestampstringrequired
Funding timestamp (ISO 8601)"2026-01-01T00:00:00Z"
funding_ratestringrequired
Funding rate as decimal (0.0001 = 0.01%)"0.0001"
premiumstring
Premium component of funding rate (Hyperliquid/HIP-3 only)"0.00005"
metaobjectrequired
Response metadata. Inspect this to drive cursor pagination and trace requests.
countintegerrequired
Number of items returned in this page.100
next_cursorstring
Opaque cursor for the next page. Omitted on the final page — when missing, you have reached the end of the range."1761840000596_907964252522803"
request_idstringrequired
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"
  }
}

Open Interest History

GET /v1/{venue}/openinterest/:symbol

Schema
successbooleanrequired
Always `true` on a 2xx response. Errors return `success: false` with an `error` field.true
dataarray<object>required
Array of result items.
Itemobject
symbolstringrequired
Trading pair symbol (preferred)"BTC"
coinstringrequired
Trading pair symbol (deprecated, use symbol)"BTC"
timestampstringrequired
Snapshot timestamp (ISO 8601)"2026-01-01T12:00:00Z"
open_intereststringrequired
Total open interest in contracts"12500.5"
mark_pricestring
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_pricestring
Oracle price from external feed (omitted on HIP-4 — outcome markets have no oracle feed)"42148.50"
day_ntl_volumestring
24-hour notional volume"1250000000"
prev_day_pricestring
Price 24 hours ago"41500.00"
mid_pricestring
Current mid price (HIP-4: implied probability in [0,1])"42150.75"
impact_bid_pricestring
Best bid price after applying impact size — used by Hyperliquid for funding calculations"42150.00"
impact_ask_pricestring
Best ask price after applying impact size — used by Hyperliquid for funding calculations"42151.50"
metaobjectrequired
Response metadata. Inspect this to drive cursor pagination and trace requests.
countintegerrequired
Number of items returned in this page.100
next_cursorstring
Opaque cursor for the next page. Omitted on the final page — when missing, you have reached the end of the range."1761840000596_907964252522803"
request_idstringrequired
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"
  }
}

Price History

GET /v1/{venue}/prices/:symbol

Schema
successbooleanrequired
Always `true` on a 2xx response. Errors return `success: false` with an `error` field.true
dataarray<object>required
Array of result items.
Itemobject
timestampstringrequired
Snapshot timestamp (ISO 8601)"2026-01-01T12:00:00Z"
mark_pricestring
Mark price"42150.75"
oracle_pricestring
Oracle price"42148.50"
mid_pricestring
Mid price (Hyperliquid/HIP-3/HIP-4 only; HIP-4 mid_price is implied probability in [0,1])"42150.75"
metaobjectrequired
Response metadata. Inspect this to drive cursor pagination and trace requests.
countintegerrequired
Number of items returned in this page.100
next_cursorstring
Opaque cursor for the next page. Omitted on the final page — when missing, you have reached the end of the range."1761840000596_907964252522803"
request_idstringrequired
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"
  }
}

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
successbooleanrequired
Always `true` on a 2xx response. Errors return `success: false` with an `error` field.true
dataarray<object>required
Array of result items.
Itemobject
coinstringrequired
Trading pair symbol"BTC"
timestampstringrequired
Liquidation timestamp (ISO 8601)"2026-01-01T12:00:00Z"
liquidated_userstringrequired
Wallet address of liquidated user"0xf0e35ea2542c070b74faba2dfbe6c16e599fdaa3"
liquidator_userstringrequired
Wallet address of liquidator. Equals liquidated_user when the position closes itself"0xf0e35ea2542c070b74faba2dfbe6c16e599fdaa3"
pricestringrequired
Liquidation price"42150.50"
sizestringrequired
Position size liquidated"1.5"
sidestringrequired
Position side: "B" (long) or "A" (short)"A"
mark_pricestring
Mark price at liquidation"42148.00"
closed_pnlstring
Realized PnL from liquidation"-500.25"
directionstring
Position direction description"Close Long"
trade_idinteger
Unique trade ID63845468834205
tx_hashstring
Blockchain transaction hash"0xf89907d0bf82aa6afa120439d0b66e0207ea00b65a85c93d9c61b3237e868455"
metaobjectrequired
Response metadata. Inspect this to drive cursor pagination and trace requests.
countintegerrequired
Number of items returned in this page.100
next_cursorstring
Opaque cursor for the next page. Omitted on the final page — when missing, you have reached the end of the range."1761840000596_907964252522803"
request_idstringrequired
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"
  }
}

Liquidation Volume

GET /v1/hyperliquid/liquidations/:symbol/volume and /v1/hyperliquid/hip3/liquidations/:symbol/volume

Schema
successbooleanrequired
Always `true` on a 2xx response. Errors return `success: false` with an `error` field.true
dataarray<object>required
Array of result items.
Itemobject
symbolstring
Trading pair symbol"BTC"
coinstring
Trading pair symbol (legacy)"BTC"
timestampstringrequired
Bucket start timestamp (ISO 8601)"2026-01-01T12:00:00Z"
total_usdnumberrequired
Total liquidation notional in USD716220.9
long_usdnumberrequired
Long liquidation notional in USD631463.06
short_usdnumberrequired
Short liquidation notional in USD84757.84
countinteger
Total liquidation events in bucket258
long_countinteger
Long liquidation events in bucket228
short_countinteger
Short liquidation events in bucket30
metaobjectrequired
Response metadata. Inspect this to drive cursor pagination and trace requests.
countintegerrequired
Number of items returned in this page.100
next_cursorstring
Opaque cursor for the next page. Omitted on the final page — when missing, you have reached the end of the range."1761840000596_907964252522803"
request_idstringrequired
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"
  }
}

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
successbooleanrequired
Always `true` on a 2xx response. Errors return `success: false` with an `error` field.true
dataobjectrequired
Response payload.
coinstringrequired
Trading pair symbol"BTC"
timestampstringrequired
Reconstruction timestamp (ISO 8601)"2026-03-12T12:00:00Z"
checkpoint_timestampstringrequired
Checkpoint that anchors this reconstruction"2026-03-12T12:00:00Z"
diffs_appliedintegerrequired
Number of diffs replayed since checkpoint1523
last_block_numberintegerrequired
Last processed block number (0 on history snapshots)921539055
bidsarray<object>required
Individual bid orders
Orderobject
oidintegerrequired
Unique order ID81250648524
user_addressstringrequired
Wallet address of order owner"0x1234...abcd"
pricenumberrequired
Limit price68355
sizenumberrequired
Remaining order size0.5
sidestringrequired
"B" (bid) or "A" (ask)"B"
asksarray<object>required
Individual ask orders
Orderobject
oidintegerrequired
Unique order ID81250652360
user_addressstringrequired
Wallet address of order owner"0x5678...efgh"
pricenumberrequired
Limit price68356
sizenumberrequired
Remaining order size0.8
sidestringrequired
"B" (bid) or "A" (ask)"A"
bid_countinteger
Total bid orders in book30561
ask_countinteger
Total ask orders in book22323
total_bid_sizenumber
Aggregate bid size across all levels6551.5
total_ask_sizenumber
Aggregate ask size across all levels5028
metaobjectrequired
Response metadata. Inspect this to drive cursor pagination and trace requests.
countintegerrequired
Number of items returned. For object responses, always 1.1
request_idstringrequired
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"
  }
}

L4 Order Book (history)

GET /v1/hyperliquid/orderbook/:symbol/l4/history and HIP-3 / HIP-4 equivalents — paginated checkpoints

Schema
successbooleanrequired
Always `true` on a 2xx response. Errors return `success: false` with an `error` field.true
dataarray<object>required
Array of result items.
Itemobject
coinstringrequired
Trading pair symbol"BTC"
timestampstringrequired
Reconstruction timestamp (ISO 8601)"2026-03-12T12:00:00Z"
checkpoint_timestampstringrequired
Checkpoint that anchors this reconstruction"2026-03-12T12:00:00Z"
diffs_appliedintegerrequired
Number of diffs replayed since checkpoint1523
last_block_numberintegerrequired
Last processed block number (0 on history snapshots)921539055
bidsarray<object>required
Individual bid orders
Orderobject
oidintegerrequired
Unique order ID81250648524
user_addressstringrequired
Wallet address of order owner"0x1234...abcd"
pricenumberrequired
Limit price68355
sizenumberrequired
Remaining order size0.5
sidestringrequired
"B" (bid) or "A" (ask)"B"
asksarray<object>required
Individual ask orders
Orderobject
oidintegerrequired
Unique order ID81250652360
user_addressstringrequired
Wallet address of order owner"0x5678...efgh"
pricenumberrequired
Limit price68356
sizenumberrequired
Remaining order size0.8
sidestringrequired
"B" (bid) or "A" (ask)"A"
bid_countinteger
Total bid orders in book30561
ask_countinteger
Total ask orders in book22323
total_bid_sizenumber
Aggregate bid size across all levels6551.5
total_ask_sizenumber
Aggregate ask size across all levels5028
metaobjectrequired
Response metadata. Inspect this to drive cursor pagination and trace requests.
countintegerrequired
Number of items returned in this page.100
next_cursorstring
Opaque cursor for the next page. Omitted on the final page — when missing, you have reached the end of the range."1761840000596_907964252522803"
request_idstringrequired
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"
  }
}

L4 Diff

GET /v1/hyperliquid/orderbook/:symbol/l4/diffs and HIP-3 / HIP-4 equivalents — order-level changes

Schema
successbooleanrequired
Always `true` on a 2xx response. Errors return `success: false` with an `error` field.true
dataarray<object>required
Array of result items.
Itemobject
timestampstringrequired
Diff timestamp (ISO 8601)"2026-03-12T12:00:00.100Z"
block_numberintegerrequired
Block number of the change921540000
seqintegerrequired
Sequence number within the block278
coinstringrequired
Trading pair symbol"BTC"
oidintegerrequired
Unique order ID81250700001
user_addressstringrequired
Wallet address of order owner"0x1234...abcd"
sidestringrequired
"B" (bid) or "A" (ask)"B"
pricenumberrequired
Order price68360
new_sizenumberrequired
New size (0 for full removes)0.5
diff_typestringrequired
Change type: "new", "remove", or "update""new"
metaobjectrequired
Response metadata. Inspect this to drive cursor pagination and trace requests.
countintegerrequired
Number of items returned in this page.100
next_cursorstring
Opaque cursor for the next page. Omitted on the final page — when missing, you have reached the end of the range."1761840000596_907964252522803"
request_idstringrequired
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"
  }
}

L2 Full-Depth Order Book

GET /v1/hyperliquid/orderbook/:symbol/l2 and HIP-3 / HIP-4 equivalents — derived from L4

Schema
successbooleanrequired
Always `true` on a 2xx response. Errors return `success: false` with an `error` field.true
dataobjectrequired
Response payload.
symbolstringrequired
Trading pair symbol"BTC"
coinstringrequired
Trading pair symbol (legacy)"BTC"
timestampstringrequired
Snapshot timestamp"2026-04-30 17:13:07.908"
bidsarray<object>required
Aggregated bid levels (best bid first)
PriceLevelobject
pxnumberrequired
Price at this level76183
sznumberrequired
Total size at this level75.5
nintegerrequired
Number of orders at this level405
asksarray<object>required
Aggregated ask levels (best ask first)
PriceLevelobject
pxnumberrequired
Price at this level76184
sznumberrequired
Total size at this level0.44
nintegerrequired
Number of orders at this level5
bid_levelsinteger
Total bid levels in the full book12649
ask_levelsinteger
Total ask levels in the full book8032
total_bid_sizenumber
Aggregate bid size across all levels5878.9
total_ask_sizenumber
Aggregate ask size across all levels4405.5
mid_pricenumber
Mid price76183.5
spreadnumber
Spread in absolute terms1
spread_bpsnumber
Spread in basis points0.13
metaobjectrequired
Response metadata. Inspect this to drive cursor pagination and trace requests.
countintegerrequired
Number of items returned. For object responses, always 1.1
request_idstringrequired
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"
  }
}

L2 Full-Depth Order Book (history)

GET /v1/hyperliquid/orderbook/:symbol/l2/history and HIP-3 / HIP-4 equivalents — paginated full-depth checkpoints

Schema
successbooleanrequired
Always `true` on a 2xx response. Errors return `success: false` with an `error` field.true
dataarray<object>required
Array of result items.
Itemobject
symbolstringrequired
Trading pair symbol"BTC"
coinstringrequired
Trading pair symbol (legacy)"BTC"
timestampstringrequired
Snapshot timestamp"2026-04-30 17:13:07.908"
bidsarray<object>required
Aggregated bid levels (best bid first)
PriceLevelobject
pxnumberrequired
Price at this level76183
sznumberrequired
Total size at this level75.5
nintegerrequired
Number of orders at this level405
asksarray<object>required
Aggregated ask levels (best ask first)
PriceLevelobject
pxnumberrequired
Price at this level76184
sznumberrequired
Total size at this level0.44
nintegerrequired
Number of orders at this level5
bid_levelsinteger
Total bid levels in the full book12649
ask_levelsinteger
Total ask levels in the full book8032
total_bid_sizenumber
Aggregate bid size across all levels5878.9
total_ask_sizenumber
Aggregate ask size across all levels4405.5
mid_pricenumber
Mid price76183.5
spreadnumber
Spread in absolute terms1
spread_bpsnumber
Spread in basis points0.13
metaobjectrequired
Response metadata. Inspect this to drive cursor pagination and trace requests.
countintegerrequired
Number of items returned in this page.100
next_cursorstring
Opaque cursor for the next page. Omitted on the final page — when missing, you have reached the end of the range."1761840000596_907964252522803"
request_idstringrequired
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"
  }
}

L2 Diff

GET /v1/hyperliquid/orderbook/:symbol/l2/diffs and HIP-3 / HIP-4 equivalents — tick-level price-level changes

Schema
successbooleanrequired
Always `true` on a 2xx response. Errors return `success: false` with an `error` field.true
dataarray<object>required
Array of result items.
Itemobject
timestampstringrequired
Diff timestamp (ISO 8601)"2026-04-29T17:13:54.739+00:00"
block_numberintegerrequired
Block number of the change977546590
pricenumberrequired
Price level changed75799
sizenumberrequired
New aggregate size at this level (0 if level cleared)2.05
countintegerrequired
New order count at this level5
sidestringrequired
"B" (bid) or "A" (ask)"B"
metaobjectrequired
Response metadata. Inspect this to drive cursor pagination and trace requests.
countintegerrequired
Number of items returned in this page.100
next_cursorstring
Opaque cursor for the next page. Omitted on the final page — when missing, you have reached the end of the range."1761840000596_907964252522803"
request_idstringrequired
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"
  }
}

L3 Order Book (Lighter)

GET /v1/lighter/l3orderbook/:symbol — single snapshot

Schema
successbooleanrequired
Always `true` on a 2xx response. Errors return `success: false` with an `error` field.true
dataobjectrequired
Response payload.
coinstringrequired
Trading pair symbol"BTC"
timestampstringrequired
Snapshot timestamp (ISO 8601)"2026-04-30T17:11:01.247Z"
ordersarray<object>required
Individual orders in the book
Orderobject
order_indexintegerrequired
Unique Lighter order index562952175455810
owner_account_indexintegerrequired
Lighter account index of the order's owner102394
sidestringrequired
"bid" or "ask""ask"
pricenumberrequired
Limit price76281.7
remaining_sizenumberrequired
Remaining size on the book0.39322
original_sizenumberrequired
Size at placement0.39322
bid_countintegerrequired
Total bid orders in book1250
ask_countintegerrequired
Total ask orders in book980
total_bid_sizenumber
Aggregate bid size across all orders450.5
total_ask_sizenumber
Aggregate ask size across all orders380.2
mid_pricenumber
Mid price76357.95
spreadnumber
Spread in absolute terms1
spread_bpsnumber
Spread in basis points0.13
metaobjectrequired
Response metadata. Inspect this to drive cursor pagination and trace requests.
countintegerrequired
Number of items returned. For object responses, always 1.1
request_idstringrequired
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"
  }
}

L3 Order Book (history)

GET /v1/lighter/l3orderbook/:symbol/history — paginated snapshots

Schema
successbooleanrequired
Always `true` on a 2xx response. Errors return `success: false` with an `error` field.true
dataarray<object>required
Array of result items.
Itemobject
coinstringrequired
Trading pair symbol"BTC"
timestampstringrequired
Snapshot timestamp (ISO 8601)"2026-04-30T17:11:01.247Z"
ordersarray<object>required
Individual orders in the book
Orderobject
order_indexintegerrequired
Unique Lighter order index562952175455810
owner_account_indexintegerrequired
Lighter account index of the order's owner102394
sidestringrequired
"bid" or "ask""ask"
pricenumberrequired
Limit price76281.7
remaining_sizenumberrequired
Remaining size on the book0.39322
original_sizenumberrequired
Size at placement0.39322
bid_countintegerrequired
Total bid orders in book1250
ask_countintegerrequired
Total ask orders in book980
total_bid_sizenumber
Aggregate bid size across all orders450.5
total_ask_sizenumber
Aggregate ask size across all orders380.2
mid_pricenumber
Mid price76357.95
spreadnumber
Spread in absolute terms1
spread_bpsnumber
Spread in basis points0.13
metaobjectrequired
Response metadata. Inspect this to drive cursor pagination and trace requests.
countintegerrequired
Number of items returned in this page.100
next_cursorstring
Opaque cursor for the next page. Omitted on the final page — when missing, you have reached the end of the range."1761840000596_907964252522803"
request_idstringrequired
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"
  }
}

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
successbooleanrequired
Always `true` on a 2xx response. Errors return `success: false` with an `error` field.true
dataarray<object>required
Array of result items.
Itemobject
timestampstringrequired
Event timestamp (ISO 8601)"2026-03-12T12:00:01Z"
block_timestringrequired
Block timestamp"2026-03-12T12:00:01Z"
block_numberintegerrequired
Block number921540000
seqintegerrequired
Sequence number within the block641
coinstringrequired
Trading pair symbol"BTC"
user_addressstringrequired
Wallet address of order owner"0x1234...abcd"
statusstringrequired
Order status: open, filled, canceled, triggered, force_canceled"canceled"
sidestringrequired
"B" (buy) or "A" (sell)"B"
limit_pricenumberrequired
Limit price68313
sizenumberrequired
Current remaining size0.0029
orig_sizenumberrequired
Original order size0.0029
oidintegerrequired
Unique order ID403692588220
order_typestringrequired
Type: Limit, Stop Market, etc."Limit"
is_triggerboolean
Whether the order is a trigger orderfalse
is_position_tpslboolean
Whether the order is a position TP/SLfalse
reduce_onlyboolean
Whether the order is reduce-onlyfalse
tifstring
Time-in-force: Gtc, Ioc, Alo"Alo"
cloidstring
Client order ID (if set)"0x00000000000000000b56a219d5668a74"
metaobjectrequired
Response metadata. Inspect this to drive cursor pagination and trace requests.
countintegerrequired
Number of items returned in this page.100
next_cursorstring
Opaque cursor for the next page. Omitted on the final page — when missing, you have reached the end of the range."1761840000596_907964252522803"
request_idstringrequired
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"
  }
}

TP / SL Order History

GET /v1/hyperliquid/orders/:symbol/tpsl and HIP-3 / HIP-4 equivalents — trigger and TP/SL orders

Schema
successbooleanrequired
Always `true` on a 2xx response. Errors return `success: false` with an `error` field.true
dataarray<object>required
Array of result items.
Itemobject
timestampstringrequired
Event timestamp (ISO 8601)"2026-04-29T17:14:32.795Z"
block_timestringrequired
Block timestamp"2026-04-29T17:14:32.795Z"
block_numberintegerrequired
Block number977548038
seqintegerrequired
Sequence number within the block2748
coinstringrequired
Trading pair symbol"BTC"
user_addressstringrequired
Wallet address of order owner"0x58a90dfa54eca4027bee2c23b931a8fd596e7261"
statusstringrequired
Order status (e.g., open, triggered, reduceOnlyCanceled)"reduceOnlyCanceled"
sidestringrequired
"B" (buy) or "A" (sell)"B"
limit_pricenumberrequired
Trigger limit price76503
sizenumberrequired
Remaining size0.00024
orig_sizenumberrequired
Original order size0.00024
oidintegerrequired
Unique order ID403666382043
order_typestringrequired
Type: Stop Market, Stop Limit, Take Profit Market, Take Profit Limit"Stop Market"
trigger_conditionstringrequired
Human-readable trigger condition"Price above 76503"
trigger_pricenumber
Numeric trigger price76503
is_triggerboolean
Always true for TP/SL orderstrue
is_position_tpslboolean
Whether attached to a positionfalse
reduce_onlyboolean
Whether the order is reduce-onlytrue
metaobjectrequired
Response metadata. Inspect this to drive cursor pagination and trace requests.
countintegerrequired
Number of items returned in this page.100
next_cursorstring
Opaque cursor for the next page. Omitted on the final page — when missing, you have reached the end of the range."1761840000596_907964252522803"
request_idstringrequired
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"
  }
}

Order Flow

GET /v1/hyperliquid/orders/:symbol/flow and HIP-3 / HIP-4 equivalents — bucketed activity counts

Schema
successbooleanrequired
Always `true` on a 2xx response. Errors return `success: false` with an `error` field.true
dataarray<object>required
Array of result items.
Itemobject
timestampstringrequired
Bucket start timestamp (ISO 8601)"2026-03-12T12:00:00Z"
limit_orders_placedintegerrequired
Limit orders placed in bucket342
orders_canceledintegerrequired
Orders canceled in bucket128
orders_filledintegerrequired
Orders filled in bucket89
trigger_orders_placedintegerrequired
Trigger orders placed15
tpsl_orders_placedintegerrequired
TP/SL orders placed7
orders_triggeredintegerrequired
Orders triggered3
orders_force_canceledintegerrequired
Orders force-canceled0
metaobjectrequired
Response metadata. Inspect this to drive cursor pagination and trace requests.
countintegerrequired
Number of items returned. For object responses, always 1.1
request_idstringrequired
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"
  }
}

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
statusstringrequired
Overall system status: operational, degraded, down"operational"
updated_atstringrequired
Status timestamp (ISO 8601)"2026-04-30T17:15:00Z"
exchangesobjectrequired
Per-exchange status keyed by exchange id (hyperliquid, spot, lighter, hip3, hip4)
<exchange>object
statusstringrequired
operational, degraded, down"operational"
last_data_atstring
Most recent ingestion timestamp (ISO 8601)"2026-04-30T17:14:55Z"
latency_msinteger
Current ingestion lag in milliseconds1601
data_typesobjectrequired
Per-data-type status (orderbook, fills, funding, open_interest)
<data_type>object
statusstringrequired
operational, degraded, down"operational"
completeness_24hnumber
Percentage of expected data captured in the last 24 hours100
active_incidentsintegerrequired
Number of currently open incidents0
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
}

Exchange Coverage

GET /v1/data-quality/coverage and /v1/data-quality/coverage/:exchange

Schema
exchangestringrequired
Exchange identifier"hyperliquid"
data_typesobjectrequired
Coverage keyed by data type
<data_type>object
fills, funding, l4_checkpoints, orderbook, open_interest, orders, liquidations, etc.
earlieststringrequired
Earliest datapoint (ISO 8601)"2023-04-15T00:00:07Z"
lateststringrequired
Most recent datapoint (ISO 8601)"2026-04-30T17:15:16Z"
total_recordsintegerrequired
Cumulative record count23262965687
symbolsinteger
Number of symbols covered (exchange-level)190
completenessnumber
Percentage of expected data present100
historical_coveragenumber
Percentage of historical range covered100
resolutionstring
Typical sampling resolution where applicable"~1.2 seconds"
lagstring
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
    }
  }
}

Symbol Coverage

GET /v1/data-quality/coverage/:exchange/:symbol — per-symbol gap detection and cadence

Schema
exchangestringrequired
Exchange identifier"hyperliquid"
symbolstringrequired
Trading pair symbol"BTC"
data_typesobjectrequired
Coverage keyed by data type (orderbook, fills, funding, open_interest, etc.)
<data_type>object
earlieststringrequired
Earliest datapoint (ISO 8601)"2023-05-20T02:50:04Z"
lateststringrequired
Most recent datapoint (ISO 8601)"2026-04-30T17:09:39.281Z"
total_recordsintegerrequired
Cumulative record count for the symbol1525080
completenessnumber
Percentage of expected data present100
historical_coveragenumber
Percentage of historical range covered98.8
gapsarray<object>
Detected gap windows in the requested range
Gapobject
startstringrequired
"2026-04-25T07:32:53.589Z"
endstringrequired
"2026-04-25T07:35:07.775Z"
duration_minutesnumber
2.24
cadenceobject
Empirical sampling cadence for the data type
median_interval_secondsnumber
61
p95_interval_secondsnumber
61
sample_countinteger
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
      }
    }
  }
}

Incidents (list)

GET /v1/data-quality/incidents — uses limit/offset pagination, not cursor

Schema
incidentsarray<object>required
Page of incidents matching the filters
Incidentobject
idstringrequired
Incident identifier"INC-2026-001"
statusstringrequired
open or resolved"resolved"
severitystringrequired
critical, major, minor"major"
exchangestringrequired
"lighter"
data_typesarray<string>
stringstring
"orderbook"
symbols_affectedarray<string>
Affected symbols, or ["ALL"]
stringstring
"ALL"
started_atstringrequired
"2026-02-12T22:02:03Z"
resolved_atstring
Null until the incident closes"2026-02-12T22:52:00Z"
duration_minutesinteger
49
titlestringrequired
"Lighter.xyz upstream outage"
descriptionstring
"Lighter.xyz experienced a service disruption..."
root_causestring
"Lighter.xyz upstream service disruption"
resolutionstring
"Lighter.xyz services recovered on their own."
paginationobjectrequired
Offset/limit pagination — incidents use offset rather than cursors
totalintegerrequired
42
limitintegerrequired
50
offsetintegerrequired
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
  }
}

Incident (detail)

GET /v1/data-quality/incidents/:id

Schema
idstringrequired
Incident identifier"INC-2026-001"
statusstringrequired
open or resolved"resolved"
severitystringrequired
critical, major, minor"major"
exchangestringrequired
"lighter"
data_typesarray<string>
stringstring
"orderbook"
symbols_affectedarray<string>
Affected symbols, or ["ALL"]
stringstring
"ALL"
started_atstringrequired
"2026-02-12T22:02:03Z"
resolved_atstring
Null until the incident closes"2026-02-12T22:52:00Z"
duration_minutesinteger
49
titlestringrequired
"Lighter.xyz upstream outage"
descriptionstring
"Lighter.xyz experienced a service disruption..."
root_causestring
"Lighter.xyz upstream service disruption"
resolutionstring
"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."
}

Latency

GET /v1/data-quality/latency — current WebSocket and ingestion lag

Schema
measured_atstringrequired
Server time when latency was sampled (ISO 8601)"2026-04-30T17:10:11.613Z"
exchangesobjectrequired
Latency metrics keyed by exchange
<exchange>object
websocketobject
current_msintegerrequired
2049
avg_1h_msinteger
2049
avg_24h_msinteger
2049
data_freshnessobject
orderbook_lag_msinteger
2049
fills_lag_msinteger
5349
funding_lag_msinteger
32332
oi_lag_msinteger
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
      }
    }
  }
}

SLA

GET /v1/data-quality/sla — monthly compliance

Schema
periodstringrequired
YYYY-MM month identifier"2026-03"
sla_targetsobjectrequired
Targets for the period
uptimenumberrequired
99.9
data_completenessnumberrequired
99.5
api_latency_p99_msintegerrequired
500
actualobjectrequired
Measured values for the period
uptimenumberrequired
99.999
uptime_statusstringrequired
met, missed"met"
data_completenessobject
orderbooknumber
83.3
fillsnumber
83.3
fundingnumber
83.3
overallnumber
83.3
completeness_statusstring
"missed"
api_latency_p99_msinteger
32662
latency_statusstring
"missed"
incidents_this_periodintegerrequired
0
total_downtime_minutesintegerrequired
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
}