> ## Documentation Index
> Fetch the complete documentation index at: https://docs.0xarchive.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Crypto Trades API: Hyperliquid and Lighter Trade History

> Crypto trades API and trade history for Hyperliquid and Lighter with pagination, decimal-safe fields, and replay guidance.

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.

1. **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](/core-concepts/free-tier).
2. **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](/openapi).
3. **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.
4. **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](/venue-coverage).

Keep every page's `meta.request_id` with its query and raw response. [Pull historical market data](/guides/historical-market-data) walks through a saved run, and [Data quality](/data-quality) covers the checks.

## Get trades

<Tabs>
  <Tab title="Hyperliquid">
    ```bash theme={"theme":"github-dark"}
    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`.
  </Tab>

  <Tab title="Spot">
    ```bash theme={"theme":"github-dark"}
    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`.
  </Tab>

  <Tab title="HIP-3">
    ```bash theme={"theme":"github-dark"}
    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`).
  </Tab>

  <Tab title="HIP-4">
    ```bash theme={"theme":"github-dark"}
    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).
  </Tab>

  <Tab title="Lighter">
    ```bash theme={"theme":"github-dark"}
    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`.
  </Tab>

  <Tab title="Lighter on Robinhood Chain">
    ```bash theme={"theme":"github-dark"}
    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`.
  </Tab>
</Tabs>

The Lighter operations are [Get Lighter trades](/api-reference/lighter--trades/get-lighter-trades) and [Get recent Lighter trades](/api-reference/lighter--trades/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](/hyperliquid-fills-data-api) 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:

```json theme={"theme":"github-dark"}
{
  "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](/responses#field-dictionary), and [Example responses](/response-examples) 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](/rest-api/rh-lighter).

## Access

Each venue's start date, WebSocket channels, and page limit come from [`GET /v1/capabilities`](/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](/conventions).

| Venue | Availability |
| - | - |
| Hyperliquid | From 2023-04-15 03:31 UTC<br />WebSocket `trades`: live and replay<br />Up to 50,000 rows a page |
| Hyperliquid Spot | From 2025-03-22 10:50 UTC<br />WebSocket `spot_trades`: live only<br />Up to 50,000 rows a page |
| HIP-3 | From 2025-10-13 12:24 UTC<br />WebSocket `hip3_trades`: live and replay<br />Up to 50,000 rows a page |
| HIP-4 | From 2026-05-02 08:00 UTC<br />WebSocket `hip4_trades`: live and replay<br />Up to 50,000 rows a page |
| Lighter | From 2025-01-17 08:43 UTC<br />WebSocket `lighter_trades`: live and replay<br />Up to 50,000 rows a page<br />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<br />WebSocket `rh_lighter_trades`: live and replay<br />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](/websocket/lighter). 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.

```javascript theme={"theme":"github-dark"}
ws.send(JSON.stringify({ op: "subscribe", channel: "trades", symbol: "BTC" }));
```

Connection, keep-alive, and reconnect handling live in the [WebSocket](/websocket) tab; the full channel list is on [WebSocket channels](/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](/data-catalog); columns and coverage keys are on [Export schemas](/export-schemas).

## Next step

To see the resting depth these trades executed against, continue to [Order books](/rest-api/order-books).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.