Response Schemas

Check field names and example payloads before you model responses or write validation.

Fields
Normalized and venue-specific
Format
Nested objects and examples
For
Typed clients and QA
REST API
Error Handling

Use these schema references when you need exact field names, nested structures, and example payloads.

Top-level fields are open by default. Expand nested objects only when you need the full shape for types, validation, or QA.

Market state

Real-time and current-state responses for books, trades, pricing, funding, and open interest.

Order Book Response

GET /v1/hyperliquid/orderbook/:symbol

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
asksarray<object>required
Ask price levels (best ask first)
PriceLevelobject
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"

Trade Response

GET /v1/hyperliquid/trades/:symbol

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

Funding Rate Response

GET /v1/hyperliquid/funding/:symbol

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

Open Interest Response

GET /v1/hyperliquid/openinterest/:symbol

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"42150.75"
oracle_pricestring
Oracle price from external 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"42150.75"

Symbol Summary Response

GET /v1/*/summary/:symbol

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 only)"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_24hstring
24h liquidation volume (Hyperliquid only)"5000000"
long_liquidation_volume_24hstring
24h long liquidation volume"3000000"
short_liquidation_volume_24hstring
24h short liquidation volume"2000000"

Price Snapshot Response

GET /v1/*/prices/:symbol

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 only)"42150.75"

Historical series and monitoring

Time-series payloads, liquidation aggregates, and freshness signals used in backfills and health checks.

Candle Response

GET /v1/*/candles/:symbol

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

Liquidation Response

GET /v1/hyperliquid/liquidations/:symbol (December 2025+ data, long and short)

symbolstringrequired
Trading pair symbol (preferred)"BTC"
coinstringrequired
Trading pair symbol (deprecated, use symbol)"BTC"
timestampstringrequired
Liquidation timestamp (ISO 8601)"2026-01-01T12:00:00Z"
liquidated_userstringrequired
Wallet address of liquidated user"0x..."
liquidator_userstringrequired
Wallet address of liquidator"0x..."
pricestringrequired
Liquidation price"42150.50"
sizestringrequired
Position size liquidated"1.5"
sidestringrequired
Position side: "B" (long) or "S" (short)"B"
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 ID12345678
tx_hashstring
Blockchain transaction hash"0x..."

Liquidation Volume Response

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

timestampstringrequired
Bucket start timestamp (ISO 8601)"2026-01-01T12:00:00Z"
total_usdstringrequired
Total liquidation volume in USD"5000000"
long_usdstringrequired
Long liquidation volume in USD"3000000"
short_usdstringrequired
Short liquidation volume in USD"2000000"

Symbol Freshness Response

GET /v1/*/freshness/:symbol

symbolstringrequired
Trading pair symbol (preferred)"BTC"
coinstringrequired
Trading pair symbol (deprecated, use symbol)"BTC"
data_typesobjectrequired
Freshness per data type
orderbookobject
fillsobject
fundingobject
open_interestobject

Order books and diffs

Order-level snapshots and diff feeds for higher-tier depth analysis across Hyperliquid, HIP-3, and Lighter.

L4 Order Book Response

GET /v1/hyperliquid/orderbook/:symbol/l4 (Hyperliquid & HIP-3, Pro+)

symbolstringrequired
Trading pair symbol (preferred)"BTC"
coinstringrequired
Trading pair symbol (deprecated, use symbol)"BTC"
checkpoint_timestampstringrequired
Checkpoint timestamp (ISO 8601)"2026-03-12T12:00:00Z"
diffs_appliedintegerrequired
Number of diffs applied since checkpoint1523
last_block_numberintegerrequired
Last processed block number921539055
bidsarray<object>required
Individual bid orders
Orderobject
asksarray<object>required
Individual ask orders
Orderobject

L4 Diff Response

GET /v1/hyperliquid/orderbook/:symbol/l4/diffs (Hyperliquid & HIP-3, Pro+)

timestampstringrequired
Diff timestamp (ISO 8601)"2026-03-12T12:00:00.100Z"
diff_typestringrequired
Type of change: "add", "remove", or "update""add"
oidintegerrequired
Unique order ID81250700001
user_addressstringrequired
Wallet address of order owner"0x1234...abcd"
pricestringrequired
Order price"68360.0"
new_sizestringrequired
New size (0 for removes)"0.5"
sidestringrequired
"B" (bid) or "A" (ask)"B"
block_numberintegerrequired
Block number of the change921540000

L3 Order Book Response

GET /v1/lighter/l3orderbook/:symbol (Lighter, Pro+)

ordersarray<object>required
Individual orders in the book
Orderobject
bid_countintegerrequired
Total number of bid orders1250
ask_countintegerrequired
Total number of ask orders980
total_bid_sizestringrequired
Aggregate bid size"450.5"
total_ask_sizestringrequired
Aggregate ask size"380.2"
mid_pricestring
Mid price"68355.5"
spreadstring
Spread in absolute terms"1.0"
spread_bpsstring
Spread in basis points"1.46"

Order lifecycle and flow

Order history and aggregated flow responses used for event analysis, reconstruction, and monitoring.

Order History Response

GET /v1/hyperliquid/orders/:symbol/history (Hyperliquid & HIP-3, Pro+)

timestampstringrequired
Event timestamp (ISO 8601)"2026-03-12T12:00:01Z"
block_timestringrequired
Block timestamp"2026-03-12T12:00:01Z"
block_numberintegerrequired
Block number921540000
user_addressstringrequired
Wallet address of order owner"0x1234...abcd"
statusstringrequired
Order status: open, filled, canceled, triggered, force_canceled"filled"
sidestringrequired
"B" (buy) or "A" (sell)"B"
limit_pricestringrequired
Limit price"68355.0"
sizestringrequired
Current remaining size"0.5"
orig_sizestringrequired
Original order size"0.5"
oidintegerrequired
Unique order ID81250700001
order_typestringrequired
Type: limit, trigger, tpsl"limit"
is_triggerboolean
Whether order is a trigger orderfalse
is_position_tpslboolean
Whether order is a position TP/SLfalse
reduce_onlyboolean
Whether order is reduce-onlyfalse
tifstring
Time-in-force: Gtc, Ioc, Alo"Gtc"
cloidstring
Client order ID (if set)null

Order Flow Response

GET /v1/hyperliquid/orders/:symbol/flow (Hyperliquid & HIP-3, Pro+)

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