Crypto Trades API: Hyperliquid and Lighter Trade History

A trade is a single fill: side, price, size, the wallets involved, and the chain transaction. Hyperliquid core, Spot, HIP-3, HIP-4, Lighter, and Lighter on Robinhood Chain each serve per-fill trade history; choose the venue family and symbol, page through the route, and keep prices and sizes as decimal strings.

Pull a historical window

To pull a named window, such as Hyperliquid BTC from January through March 2025, handle access, paging, and completeness as separate steps.

Authenticate. Send X-API-Key with the key from your runtime environment. Free reaches the most recent 30 days, so a window like January to March 2025 needs Build or above, which keep the full archive. See Free tier.
Choose the route and window. For Hyperliquid core BTC, request /v1/hyperliquid/trades/BTC with explicit UTC start, end, and limit; the symbol belongs in the path. Page sizes and request spans are set per route; the exact operation is in OpenAPI.
Page to the end. Follow the exact opaque string in meta.next_cursor, keeping the original window, limit, side, and other filters unchanged, until meta.has_more is false. If your own page budget stops a pull while a cursor remains, mark the saved output partial and resume later from the saved cursor.
Check completeness. Before a backtest, check the symbol’s historical coverage and known gaps with /v1/data-quality/coverage/hyperliquid/BTC, and attach that result to the saved pages. Freshness is not historical completeness: it reports how recent the data is, not whether the requested window was fully captured. A venue-wide history floor, or the end of a known backfill period, is not a capture record for your window; each symbol’s start is on Venue coverage.

Keep every page’s meta.request_id with its query and raw response. Pull historical market data walks through a saved run, and Data quality covers the checks.

Get trades

curl "https://api.0xarchive.io/v1/hyperliquid/trades/BTC?limit=1" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"

Routes: /v1/hyperliquid/trades/{symbol}, /recent. Plain perp symbols such as BTC.

curl "https://api.0xarchive.io/v1/hyperliquid/spot/trades/HYPE-USDC?limit=1" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"

Route: /v1/hyperliquid/spot/trades/{symbol}. Pair symbols such as HYPE-USDC.

curl "https://api.0xarchive.io/v1/hyperliquid/hip3/trades/km:US500?limit=1" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"

Route: /v1/hyperliquid/hip3/trades/{symbol}. Namespaced builder symbols, case-sensitive (for example km:US500).

curl "https://api.0xarchive.io/v1/hyperliquid/hip4/trades/%230?limit=1" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"

Routes: /v1/hyperliquid/hip4/trades/{symbol}, /recent. Outcome side ids such as %230 (Yes).

curl "https://api.0xarchive.io/v1/lighter/trades/{symbol}?limit=1" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"

Routes: /v1/lighter/trades/{symbol}, /recent. Find symbols on /v1/lighter/instruments.

curl "https://api.0xarchive.io/v1/rh-lighter/trades/BTC?limit=1" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"

Routes: /v1/rh-lighter/trades/{symbol}, /recent. The same finalized and preliminary tiers as Lighter mainnet, with USDG amounts. Find symbols on /v1/rh-lighter/instruments.

The Lighter operations are Get Lighter trades and Get recent Lighter trades.

Request parameters

Parameter	Description
`symbol`	Path, required, string. Trading pair symbol, e.g. `BTC`
`start`	Query, optional, integer (ms) or string. Start time, Unix ms or RFC 3339. Defaults to 24h ago
`end`	Query, optional, integer (ms) or string. End time, Unix ms or RFC 3339. Defaults to now
`side`	Query, optional, string. `buy` or `sell` (any case). Filters before paging, so a full page holds `limit` matching trades. Works on every trades route, including `/recent`, on all venues. Rows keep the venue side code, `B` or `A`
`limit`	Query, optional, integer. Max results. Default 100; the maximum is the page limit in the Access table below
`cursor`	Query, optional, string. Pagination cursor from `meta.next_cursor`; send it unchanged, with the same `side`, while `meta.has_more` is `true`

Filter by side, wallet, or builder

To keep only buys or only sells, pass side=buy or side=sell; the filter runs before paging. The main trades routes do not accept a user 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 one wallet’s or builder’s fills, pull the venue, market, and time window, paginate with cursor, then filter rows client-side on data[].user_address or data[].builder_address. For large market-wide studies, use the corresponding export schema instead of widening many row-level requests. Hyperliquid fills covers the fills workflow with wallet attribution and TP/SL context. 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 the trades route for execution rows.

Example response

A trade returns:

{
  "success": true,
  "data": [
    {
      "coin": "BTC",
      "side": "B",
      "price": "63743",
      "size": "0.0002",
      "timestamp": "2026-06-04T13:53:39.609Z",
      "trade_id": 397759113671327,
      "direction": "Open Long",
      "fee": "0.005507",
      "fee_token": "USDC",
      "start_position": "0.03919",
      "crossed": true,
      "user_address": "0x1f1fab9e5fc092f02cf833fd487b64703cbf536a",
      "tx_hash": "0xcf8038aff0c5753fd0f9043cf4049502051b00958bc894117348e402afc94f2a"
    }
  ],
  "meta": {
    "count": 1,
    "has_more": true,
    "next_cursor": "1780581219809_333265093496905",
    "symbol": "BTC",
    "venue": "hyperliquid",
    "request_id": "45678901-4567-4456-8456-456789012345"
  }
}

Response fields

Each item in the data array:

Field	Description
`symbol`	String. Trading pair symbol (`coin` is a deprecated alias)
`side`	String. `B` (buy) or `A` (sell)
`price`	String. Execution price (decimal string)
`size`	String. Trade size (decimal string)
`timestamp`	String. Execution time (UTC)
`trade_id`	Integer. Unique trade ID
`crossed`	Boolean. True if taker (crossed the spread), false if maker
`fee`	String. Fee paid, including any builder fee; a negative value is a maker rebate. `"0"` is a real zero fee
`fee_token`	String. Fee denomination, e.g. `USDC`
`closed_pnl`	String. Realized PnL on this fill; `"0"` when the fill opened or added to a position
`direction`	String. Human label such as `Open Long`, `Close Short`
`start_position`	String. Position size before this fill; `"0"` means flat
`user_address`	String or null. User wallet address when the source reports it; may be null depending on source
`builder_address`	String or null. Builder attribution when the source reports it; may be null depending on source
`tx_hash`	String. Blockchain transaction hash

fee, fee_token, closed_pnl, and start_position are returned whenever the source recorded them, zeros included, on Hyperliquid, Spot, HIP-3, and HIP-4 trades. A missing field means the value is unknown, never zero. Hyperliquid and Spot fills from March 22 to May 25, 2025 come from market-level archive files that carry no fee or realized PnL, so those two fields are omitted there; start_position is still returned when it is non-zero. Some Spot trades recorded from the live trade feed carry none of the four. Lighter trades carry fees only on the finalized record, covered below. 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, and Example responses has more payload shapes.

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 January 17, 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. Lighter on Robinhood Chain, Lighter’s second deployment, uses the same two tiers under /v1/rh-lighter/trades/{symbol} and /v1/rh-lighter/trades/{symbol}/recent. Its canonical rows are reconciled daily from Lighter’s trade export for that deployment and begin at its first trade, 2026-06-26 20:10:26 UTC. Amounts are in USDG, and account indexes are separate from mainnet. See Lighter on Robinhood Chain REST.

Access

Each venue’s start date, WebSocket channels, and page limit come from GET /v1/capabilities, followed by the SDK, CLI, and MCP names for the same data. The start date is the first served row on that venue; exact starts vary by market, so check /v1/symbols for a single symbol. Send 0xArchive-Version: 2026-10-01 for the current response contract; see API conventions.

Venue	Availability
Hyperliquid	From 2023-04-15 03:31 UTC WebSocket `trades`: live and replay Up to 50,000 rows a page
Hyperliquid Spot	From 2025-03-22 10:50 UTC WebSocket `spot_trades`: live only Up to 50,000 rows a page
HIP-3	From 2025-10-13 12:24 UTC WebSocket `hip3_trades`: live and replay Up to 50,000 rows a page
HIP-4	From 2026-05-02 08:00 UTC WebSocket `hip4_trades`: live and replay Up to 50,000 rows a page
Lighter	From 2025-01-17 08:43 UTC WebSocket `lighter_trades`: live and replay Up to 50,000 rows a page Trades up to meta.finalized_through are canonical; /recent and live trades are preliminary. Served trade history begins at this row; exact starts vary by market.
Lighter on Robinhood Chain	From 2026-06-26 20:10 UTC WebSocket `rh_lighter_trades`: live and replay Up to 50,000 rows a page

Surface	Names
Python SDK	`client.hyperliquid.trades.list(symbol, ..., side="buy")`; `.recent(...)` on the HIP-3 and Lighter clients
TypeScript SDK	`client.hyperliquid.trades.list(symbol, { ..., side: "buy" })`; `.recent(...)` on the HIP-3, HIP-4, Spot, Lighter, and Robinhood Chain clients
Rust SDK	`client.hyperliquid.trades.list` (with `side`); `.recent` on the HIP-3, Lighter, and Robinhood Chain clients
CLI	`oxa trades fetch --side buy\|sell`; Spot `oxa spot trades`; HIP-4 `oxa hip4 trades`
MCP tools	`get_trades`, `get_spot_trades`, `get_spot_trades_recent`, `get_hip3_trades`, `get_hip3_trades_recent`, `get_hip4_trades`, `get_hip4_trades_recent`, `get_lighter_trades`, `get_lighter_trades_recent`, `get_rh_lighter_trades`, `get_rh_lighter_trades_recent`

Stream or replay it

Trade subscriptions are family-specific. Subscribe to trades for Hyperliquid core, or use spot_trades, hip3_trades, hip4_trades, lighter_trades, and rh_lighter_trades for their venue families. Keep the symbol shape that matches the family. Every trade channel except spot_trades also supports timed replay. lighter_trades streams preliminary Lighter trades live as fill legs, two per trade with the same tid, in a different shape from the REST rows above. Live legs carry fee, fee_token, closed_pnl, and dir as null, which means unknown, never zero; the finalized record from /v1/lighter/trades/{symbol} carries fee, and realized_pnl where Lighter reports it. See Lighter WebSocket channels. Over REST, /v1/lighter/trades/{symbol}/recent serves preliminary rows, lighter_trades also supports historical WebSocket replay, and historical data is available through REST and exports.

ws.send(JSON.stringify({ op: "subscribe", channel: "trades", symbol: "BTC" }));

Connection, keep-alive, and reconnect handling live in the WebSocket tab; the full channel list is on WebSocket channels.

Export in bulk

For the historical tape as files, use the trades 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.

Next step

To see the resting depth these trades executed against, continue to Order books.

Endpoint reference

Requests and responses

Datasets

Venues

OpenAPI and schemas

Guides

Crypto Trades API: Hyperliquid and Lighter Trade History

Pull a historical window

Get trades

Request parameters

Filter by side, wallet, or builder

Example response

Response fields

Lighter trades: canonical history and preliminary recent

Access

Stream or replay it

Export in bulk

Next step

​Pull a historical window

​Get trades

​Request parameters

​Filter by side, wallet, or builder

​Example response

​Response fields

​Lighter trades: canonical history and preliminary recent

​Access

​Stream or replay it

​Export in bulk

​Next step

Pull a historical window

Get trades

Request parameters

Filter by side, wallet, or builder

Example response

Response fields

Lighter trades: canonical history and preliminary recent

Access

Stream or replay it

Export in bulk

Next step