Get trades
- Hyperliquid
- Spot
- HIP-3
- HIP-4
- Lighter
/v1/hyperliquid/trades/{symbol}, /recent. Plain perp symbols such as BTC.Request parameters
Fill retrieval decisions
The main trades routes do not accept auser or builder_address query parameter. user_address and builder_address may be null, depending on source, so a missing value is not evidence that the fill belongs to another wallet or builder.
For fill rows for a wallet or builder, pull the venue, market, and time window, paginate with cursor, then filter rows client-side on data[].user_address or data[].builder_address. Large market-wide studies should use the corresponding export schema instead of widening many row-level requests.
The user filter on order-history is order lifecycle, not fill retrieval. Use /v1/hyperliquid/orders/{symbol}/history?user=... for placed, filled, canceled, or other order states, and use the trades route for execution rows.
A trade returns:
Response fields
Each item in thedata array:
HIP-3 fills carry
deployer_fee on most rows and cloid where the order was placed with a client order id; builder_address, builder_fee, and priority_gas are conditional and appear only on fills where they were set, omitted when null, so do not model them as always-present. order_id, maker_address, taker_address, and twap_id appear where applicable. price, size, and fee are decimal strings. Paginate with meta.next_cursor and keep meta.request_id per page. Full field meanings live in the field dictionary.
Lighter trades: canonical history and preliminary recent
Lighter trade routes are two-tier and do not follow the core trade shape above./v1/lighter/trades/{symbol} serves canonical history: per-fill rows reconciled daily from the Lighter Foundation archive, marked source: "bucket" and enriched to roughly 30 fields. The observed per-fill history begins August 27, 2025; exact starts vary by market. On top of the shared symbol, side, price, size, timestamp, trade_id, and crossed, canonical rows carry maker/taker attribution such as is_maker, plus order_id, tx_hash, fee, realized_pnl, usdc_amount, trade_type, l2_block_height, transaction_time_us, client_id, integrator_fee, fee_account_id, and position and margin state: position_size_before, position_size_after, entry_quote_before, initial_margin_fraction_before, allocated_margin_before, allocated_margin_after, and position_sign_changed.
/v1/lighter/trades/{symbol}/recent serves preliminary rows from the live feed, marked source: "ws", with a smaller set of about 14 fields: the shared trade fields plus account_index and the position state fields, without fee, tx_hash, order_id, or realized_pnl. Treat preliminary rows as provisional until the daily reconcile finalizes their window; meta.preliminary_row_count counts them. Recent Lighter trade responses can include preliminary rows before they enter finalized historical replay.
Lighter identity fields are account indexes, not wallet addresses: account_index and counterparty_address carry Lighter integer account ids as strings. Maker/taker attribution is per fill; do not reinterpret a fill row as a venue-wide aggregate trade. On both routes, fields are omitted when null, so parse defensively.
History requests clamp to the finalization watermark. meta.finalized_through on both routes reports the latest finalized timestamp; when your end lands past it, the history response adds meta.requested_end and meta.clamped_to and returns canonical rows only. Rows newer than the watermark are served by /recent.
Stream or replay it
Trade subscriptions are family-specific. Subscribe totrades for Hyperliquid core, or use spot_trades, hip3_trades, and hip4_trades for their venue families. Keep the symbol shape that matches the family.
Lighter current trade reads use /v1/lighter/trades/{symbol}/recent for preliminary rows, while lighter_trades supports historical WebSocket replay but not live subscriptions through the 0xArchive WebSocket. Historical data is also available through REST and exports.
Export in bulk
For the historical tape as files, use thetrades export schema ($4/GB, $7.50 minimum), delivered as Parquet with ZSTD compression. Build a selection in the Data catalog; columns and coverage keys are on Export schemas.