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

# Trades

> Real Hyperliquid and Lighter trade payloads by venue family: side, price, size, fees, wallets, and decimal-safe field notes for backtests.

A trade is a single fill: side, price, size, the wallets involved, and the chain transaction. Trades exist on every venue family.

## 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>
</Tabs>

## Request parameters

| Parameter | In    | Type         | Required | Description                               |
| --------- | ----- | ------------ | -------- | ----------------------------------------- |
| `symbol`  | path  | string       | Yes      | Trading pair symbol, e.g. `BTC`           |
| `start`   | query | integer (ms) | No       | Start time, Unix ms. Defaults to 24h ago  |
| `end`     | query | integer (ms) | No       | End time, Unix ms. Defaults to now        |
| `limit`   | query | integer      | No       | Max results. Default 100, max 1000        |
| `cursor`  | query | string       | No       | Pagination cursor from `meta.next_cursor` |

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, "next_cursor": "1780581219809_333265093496905", "request_id": "req_7d2b9c4f1a08e6d3" }
}
```

## Response fields

Each item in the `data` array:

| Field            | Type    | 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; a negative value is a maker rebate       |
| `fee_token`      | string  | Fee denomination, e.g. `USDC`                      |
| `closed_pnl`     | string  | Realized PnL on a closing fill                     |
| `direction`      | string  | Human label such as `Open Long`, `Close Short`     |
| `start_position` | string  | Position size before this trade                    |
| `user_address`   | string  | User wallet address                                |
| `tx_hash`        | string  | Blockchain transaction hash                        |

Builder and HIP-3 fills also carry `builder_address`, `builder_fee`, `deployer_fee`, and `priority_gas`; `order_id`, `cloid`, `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).

## Stream it live

Every venue streams trades. Subscribe to `trades` for Hyperliquid core, or the venue-prefixed channel for the rest: `spot_trades`, `hip3_trades`, `hip4_trades`, `lighter_trades`. Keep the symbol shape that matches the family.

```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 (`$8/GB`, `$15 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

Use [Order books](/rest-api/order-books) for resting depth, [Liquidations](/rest-api/liquidations) for forced exits, [Example responses](/response-examples) for more payload shapes, or [Data quality](/data-quality) before trades feed a model. For the Hyperliquid fills workflow with wallet attribution and TP/SL context, start with the [Hyperliquid Fills Data API](/hyperliquid-fills-data-api).