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

# Order history

> Per-order history routes across Hyperliquid core, Spot, HIP-3, and HIP-4, with filters for auditing the order lifecycle.

Order history is the per-order lifecycle on Hyperliquid core, Spot, HIP-3, and HIP-4: placements, fills, cancels, and status changes for a symbol, in the sequence they happened. Lighter has no order-lifecycle routes.

Each row is one lifecycle event with the order ID, status, size, wallet, and timestamps. Unlike [Order flow](/rest-api/order-flow), it does not collapse activity into time buckets.

<Warning>
  Order history is backed by the `l4_orders` order-event capture, which starts later than trades, funding, and open interest for the same symbol: Hyperliquid core, Spot, and HIP-3 order-event coverage begins 2026-03-10; HIP-4 begins 2026-05-02. A query entirely before that window returns `200` with an empty array. That means the order-event dataset does not cover that period, not that the wallet or symbol had no activity. For activity before the order-event start date, use [Trades](/rest-api/trades) instead.
</Warning>

## Get order history

<Tabs>
  <Tab title="Hyperliquid">
    ```bash theme={"theme":"github-dark"}
    curl "https://api.0xarchive.io/v1/hyperliquid/orders/BTC/history?start=1783886308365&end=1783886308365&limit=1" \
      -H "X-API-Key: $OXARCHIVE_API_KEY"
    ```

    `/v1/hyperliquid/orders/{symbol}/history`. Plain perp symbols such as `BTC`.
  </Tab>

  <Tab title="Spot">
    ```bash theme={"theme":"github-dark"}
    curl "https://api.0xarchive.io/v1/hyperliquid/spot/orders/HYPE-USDC/history" \
      -H "X-API-Key: $OXARCHIVE_API_KEY"
    ```

    `/v1/hyperliquid/spot/orders/{symbol}/history`. Pair symbols such as `HYPE-USDC`. Spot accepts the time-window filters (`start`, `end`, `limit`, `cursor`); the status, order-type, and wallet filters are core, HIP-3, and HIP-4 only.
  </Tab>

  <Tab title="HIP-3">
    ```bash theme={"theme":"github-dark"}
    curl "https://api.0xarchive.io/v1/hyperliquid/hip3/orders/km:US500/history" \
      -H "X-API-Key: $OXARCHIVE_API_KEY"
    ```

    `/v1/hyperliquid/hip3/orders/{symbol}/history`. Namespaced builder symbols, case-sensitive.
  </Tab>

  <Tab title="HIP-4">
    ```bash theme={"theme":"github-dark"}
    curl "https://api.0xarchive.io/v1/hyperliquid/hip4/orders/%230/history" \
      -H "X-API-Key: $OXARCHIVE_API_KEY"
    ```

    `/v1/hyperliquid/hip4/orders/{symbol}/history`. Outcome side ids such as `%230`.
  </Tab>
</Tabs>

Response items are untyped in OpenAPI. The Hyperliquid core example below is representative and abridged. Fields can be omitted or added by order type and venue family, so capture a live response before binding a strict client model. The core example uses a July 2026 window, which needs a paid plan; on Free, use a window inside the most recent 30 days.

## Request parameters

| Parameter | Description |
| - | - |
| `symbol` | Path, required, string. Trading pair symbol, e.g. `BTC` |
| `start` | Query, optional, integer (ms) or string. Start time, Unix milliseconds or RFC 3339 (e.g. `1767225600000`) |
| `end` | Query, optional, integer (ms) or string. End time, Unix milliseconds or RFC 3339 |
| `status` | Query, optional, string. Filter by order status |
| `order_type` | Query, optional, string. Filter by order type |
| `triggered` | Query, optional, boolean. `true` returns only orders whose trigger fired; `false` excludes them. Hyperliquid core, HIP-3, and HIP-4. Keep it unchanged between pages |
| `user` | Query, optional, string. Filter by wallet address. This route does not read `user_address`; passing it is silently ignored and returns unfiltered results, so use `user`. |
| `limit` | Query, optional, integer. Max results. Core, HIP-3, and HIP-4 default to 1000 and cap at 10000. Spot defaults to 100 and caps at 1000 |
| `cursor` | Query, optional, string. Pagination cursor from `meta.next_cursor` |

## Example response

Hyperliquid core, `BTC`. The example is representative and abridged. The wallet, client order ID, and request ID values are synthetic. The opaque response cursor and transaction hash are omitted.

```json theme={"theme":"github-dark"}
{
  "success": true,
  "data": [
    {
      "timestamp": "2026-07-12T19:58:28.365Z",
      "block_time": "2026-07-12T19:58:28.365Z",
      "block_number": 1070259873,
      "seq": 7,
      "coin": "BTC",
      "user_address": "0x1234567890abcdef1234567890abcdef12345678",
      "status": "open",
      "side": "B",
      "limit_price": 64211,
      "size": 0.05,
      "orig_size": 0.05,
      "oid": 494264716805,
      "order_type": "Limit",
      "is_trigger": false,
      "is_position_tpsl": false,
      "reduce_only": false,
      "tif": "Alo",
      "cloid": "0x00000000000000000000000000000001"
    }
  ],
  "meta": {
    "count": 1,
    "request_id": "22222222-2222-4222-8222-222222222222"
  }
}
```

## What the lifecycle covers

Each record is one event in an order's life: placed, partially filled, filled, canceled, or triggered. Join history to [Trades](/rest-api/trades) and the [L4 order book](/rest-api/order-books-l4) with the order id to follow a single order from placement to fill, and use the `status` and `order_type` filters to narrow to the lifecycle stage you care about. Store the order id, status, and timestamps so a later run can rebuild the same sequence.

## 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 2026-03-11 01:03 UTC<br />WebSocket `l4_orders`: live and replay<br />Up to 10,000 rows a page<br />WebSocket replay is bulk (speed is ignored) and single-channel only, anchored at L4 checkpoints. |
| Hyperliquid Spot | From 2026-05-05 22:57 UTC<br />WebSocket `spot_l4_orders`: live and replay<br />Up to 1,000 rows a page<br />WebSocket replay is bulk (speed is ignored) and single-channel only, anchored at L4 checkpoints (PURR-USDC from 2026-03-11 01:03 UTC; other pairs from 2026-05-05 or later). REST order history reaches back further for every pair. |
| HIP-3 | From 2026-03-11 01:03 UTC<br />WebSocket `hip3_l4_orders`: live and replay<br />Up to 10,000 rows a page<br />WebSocket replay is bulk (speed is ignored) and single-channel only, anchored at L4 checkpoints. |
| HIP-4 | From 2026-05-02 07:47 UTC<br />WebSocket `hip4_l4_orders`: live and replay<br />Up to 10,000 rows a page<br />WebSocket replay is bulk (speed is ignored) and single-channel only, anchored at L4 checkpoints. |

| Surface | Names |
| - | - |
| Python SDK | `client.hyperliquid.orders.history(symbol, ..., triggered=True)`; Spot `client.spot.orders.history` |
| TypeScript SDK | `client.hyperliquid.orders.history(symbol, { ..., triggered: true })`; Spot `client.spot.orders.history` |
| Rust SDK | `client.hyperliquid.orders.history` (with `triggered`); Spot `client.hyperliquid.spot.orders.history` |
| CLI | `oxa orders history --triggered true\|false`; Spot `oxa spot orders`; HIP-4 `oxa hip4 orders history` |
| MCP tools | `get_order_history`, `get_spot_order_history`, `get_hip3_order_history`, `get_hip4_order_history` |

## Stream it live

There is no separate order-history channel. Live order events stream through the L4 order channels (`l4_orders`, plus `spot_l4_orders`, `hip3_l4_orders`, `hip4_l4_orders`), which carry placements, fills, cancels, and status changes as they happen. The same four channels replay history as checkpoint-anchored bulk delivery, one channel per replay.

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

Connection and reconnect handling live in the [WebSocket](/websocket) tab; see [WebSocket channels](/websocket/channels) for the family matrix.

## Export in bulk

For order-event history as files, use the `l4_orders` (Order Events / TP/SL) export schema (`$4/GB`, `$12.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

For trigger-order rows only, continue to [Take profits and stop losses](/rest-api/tpsl).


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