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

# Export file columns

> Exact Parquet columns, types, row order, and timestamps for every Bulk Exports data type and venue, so you can load files into a warehouse.

Every Bulk Exports file is Apache Parquet compressed with zstd. This page lists the columns of each file in the order they appear, for every data type and venue. It is generated from the definitions the export service uses to write the files and the `README.md` in each order. The README in your order describes the files you received and is authoritative.

## How to read these tables

* **Timestamps.** `timestamp[ms, UTC]` columns have millisecond precision in UTC. A file holds the rows whose `timestamp` falls on a UTC date from your start date through your end date, inclusive.
* **Row order.** Rows are ordered by `timestamp`, except L4 order book changes and order events, which are ordered by `(block_number, seq)`. Apply Lighter L2 changes in `(timestamp, sequence)` order.
* **Nulls.** A column marked `(nullable)` can be null. Every other column always has a value, though a string can be empty and a number can be zero. Nullability is checked against how each column is written, not only against the README.
* **Sell side.** Hyperliquid perpetual trades and liquidations files and Lighter trades files write a sell as `S`. The REST API and WebSocket return `A` for the same sell, so map `S` to `A` before joining a file to API data. HIP-3, Spot, and HIP-4 files use `A`.
* **Spot symbols.** Spot files hold the venue's wire-format coin (`PURR/USDC` or `@<index>`) in `coin`, not the dashed pair name (`HYPE-USDC`) used in the Data Catalog and REST paths.
* **Lighter trades** end at the last finalized trade, the same boundary the REST trade routes report as `meta.finalized_through`.
* **File names.** The main file for each market and data type is `<symbol>_<data type>_<start>_to_<end>.parquet`, with `:` and `/` in the symbol written as `_`. Companion snapshot files are named the same way with `l4_checkpoints` or `l2_checkpoints` as the data type; L4 checkpoints come in one file per 7 days of the range.

## L2 Order Book (`l2_orderbook`)

### L2 Order Book: Hyperliquid perpetuals

L2 order book snapshots (\~1.2 second resolution). Rows are ordered by `timestamp`.

| Column | Type | Description |
| - | - | - |
| `timestamp` | timestamp\[ms, UTC] | Snapshot timestamp |
| `coin` | string | Symbol (e.g., `BTC`, `ETH`) |
| `bids` | string (JSON) | JSON text; the layout is below the table |
| `asks` | string (JSON) | JSON text; the layout is below the table |
| `mid_price` | double (nullable) | Mid price between best bid and ask |
| `spread` | double (nullable) | Absolute spread |
| `spread_bps` | double (nullable) | Spread in basis points |

**`bids` and `asks`**: JSON text: an array of price levels, best price first. Each level is an object with `px` (price as a decimal string), `sz` (total size at that price as a decimal string), and `n` (number of resting orders at that price).

| Field | Type | Meaning |
| - | - | - |
| `px` | string (decimal) | Price of the level |
| `sz` | string (decimal) | Total resting size at the level |
| `n` | integer | Number of resting orders at the level |

Example, with illustrative values:

```json theme={"theme":"github-dark"}
[{"px": "100.5", "sz": "1.25", "n": 3}, {"px": "100.4", "sz": "0.8", "n": 1}]
```

### L2 Order Book: Hyperliquid Spot

L2 order book snapshots for Hyperliquid spot pairs. Live coverage from 2026-05-05. Rows are ordered by `timestamp`.

| Column | Type | Description |
| - | - | - |
| `timestamp` | timestamp\[ms, UTC] | Snapshot timestamp |
| `coin` | string | Wire-format spot coin (`PURR/USDC` or `@<index>`) |
| `bids` | string (JSON) | JSON text; the layout is below the table |
| `asks` | string (JSON) | JSON text; the layout is below the table |
| `mid_price` | double (nullable) | Mid price between best bid and ask |
| `spread` | double (nullable) | Absolute spread |
| `spread_bps` | double (nullable) | Spread in basis points |

**`bids` and `asks`**: JSON text: an array of price levels, best price first. Each level is an object with `px` (price as a decimal string), `sz` (total size at that price as a decimal string), and `n` (number of resting orders at that price).

| Field | Type | Meaning |
| - | - | - |
| `px` | string (decimal) | Price of the level |
| `sz` | string (decimal) | Total resting size at the level |
| `n` | integer | Number of resting orders at the level |

Example, with illustrative values:

```json theme={"theme":"github-dark"}
[{"px": "100.5", "sz": "1.25", "n": 3}, {"px": "100.4", "sz": "0.8", "n": 1}]
```

### L2 Order Book: HIP-3

L2 order book snapshots for HIP-3 instruments. Rows are ordered by `timestamp`.

| Column | Type | Description |
| - | - | - |
| `timestamp` | timestamp\[ms, UTC] | Snapshot timestamp |
| `coin` | string | HIP-3 symbol (e.g., `xyz:CL`, `km:US500`) |
| `bids` | string (JSON) | JSON text; the layout is below the table |
| `asks` | string (JSON) | JSON text; the layout is below the table |
| `mid_price` | double (nullable) | Mid price |
| `spread` | double (nullable) | Spread |
| `spread_bps` | double (nullable) | Spread in basis points |

**`bids` and `asks`**: JSON text: an array of price levels, best price first. Each level is an object with `px` (price as a decimal string), `sz` (total size at that price as a decimal string), and `n` (number of resting orders at that price).

| Field | Type | Meaning |
| - | - | - |
| `px` | string (decimal) | Price of the level |
| `sz` | string (decimal) | Total resting size at the level |
| `n` | integer | Number of resting orders at the level |

Example, with illustrative values:

```json theme={"theme":"github-dark"}
[{"px": "100.5", "sz": "1.25", "n": 3}, {"px": "100.4", "sz": "0.8", "n": 1}]
```

### L2 Order Book: HIP-4

HIP-4 L2 order book snapshots for outcome markets. Prices are implied probabilities in \[0, 1]. Rows are ordered by `timestamp`.

| Column | Type | Description |
| - | - | - |
| `timestamp` | timestamp\[ms, UTC] | Snapshot timestamp |
| `coin` | string | HIP-4 outcome symbol (`#<10*outcome_id + side>`, e.g., `#10`) |
| `bids` | string (JSON) | JSON text; the layout is below the table |
| `asks` | string (JSON) | JSON text; the layout is below the table |
| `mid_price` | double (nullable) | Mid implied probability |
| `spread` | double (nullable) | Absolute spread (in probability units) |
| `spread_bps` | double (nullable) | Spread in basis points |
| `is_in_auction` | uint8 | `1` if observed during opening auction |

**`bids` and `asks`**: JSON text: an array of price levels, best price first. Each level is an object with `px` (price as a decimal string), `sz` (total size at that price as a decimal string), and `n` (number of resting orders at that price).

| Field | Type | Meaning |
| - | - | - |
| `px` | string (decimal) | Price of the level |
| `sz` | string (decimal) | Total resting size at the level |
| `n` | integer | Number of resting orders at the level |

Example, with illustrative values:

```json theme={"theme":"github-dark"}
[{"px": "0.62", "sz": "150.0", "n": 3}, {"px": "0.61", "sz": "40.0", "n": 1}]
```

### L2 Order Book: Lighter and Lighter on Robinhood Chain

L2 order book changes (event resolution): every individual price-level change. Delivered together with a second file of periodic full snapshots (l2\_checkpoints). See [Rebuilding order books](#rebuilding-order-books) for how to apply them. Rows are ordered by `timestamp`.

| Column | Type | Description |
| - | - | - |
| `timestamp` | timestamp\[ms, UTC] | Time of the book change |
| `symbol` | string | Symbol (e.g., `BTC`, `ETH`) |
| `side` | string | `bid` or `ask` |
| `price` | double | Price level that changed |
| `size` | double | New aggregate resting size at that level (`0` = level removed) |
| `sequence` | uint64 | Per-symbol ordering index; apply changes in (timestamp, sequence) order |
| `change_type` | string | `set` (level now has `size`) or `remove` (`size = 0`) |

### L2 Order Book: Lighter and Lighter on Robinhood Chain: `l2_checkpoints` snapshots file

Periodic full L2 order book snapshots (\~1 minute intervals). See [Rebuilding order books](#rebuilding-order-books) for how to combine it with the change file. Rows are ordered by `timestamp`.

| Column | Type | Description |
| - | - | - |
| `timestamp` | timestamp\[ms, UTC] | Snapshot timestamp |
| `symbol` | string | Symbol (e.g., `BTC`, `ETH`) |
| `bids` | string (JSON) | JSON text; the layout is below the table |
| `asks` | string (JSON) | JSON text; the layout is below the table |
| `mid_price` | double (nullable) | Mid price |
| `spread` | double (nullable) | Spread |
| `spread_bps` | double (nullable) | Spread in basis points |

**`bids` and `asks`**: JSON text: an array of `[price, size]` pairs, both numbers, best price first. The snapshot holds every level of the book.

| Field | Type | Meaning |
| - | - | - |
| `[0]` | number | Price of the level |
| `[1]` | number | Total resting size at the level |

Example, with illustrative values:

```json theme={"theme":"github-dark"}
[[100.5, 1.25], [100.4, 0.8]]
```

## Individual-Order Book (L3) (`l3_orderbook`)

### Individual-Order Book (L3): Lighter

L3 order-level orderbook snapshots with individual order IDs and sizes. Rows are ordered by `timestamp`.

| Column | Type | Description |
| - | - | - |
| `timestamp` | timestamp\[ms, UTC] | Snapshot timestamp |
| `symbol` | string | Symbol |
| `orders` | string (JSON) | JSON text; the layout is below the table |
| `bid_count` | uint32 | Number of bid orders |
| `ask_count` | uint32 | Number of ask orders |
| `total_bid_size` | double | Total bid size |
| `total_ask_size` | double | Total ask size |
| `mid_price` | double (nullable) | Mid price |
| `spread` | double (nullable) | Spread |
| `spread_bps` | double (nullable) | Spread in basis points |

**`orders`**: JSON text: an array with one object per resting order, using short keys.

| Field | Type | Meaning |
| - | - | - |
| `i` | integer | Order index (the order ID on Lighter) |
| `a` | integer | Account index of the order owner |
| `s` | integer | Side: `1` for a bid, `2` for an ask |
| `p` | number | Price |
| `r` | number | Remaining size |
| `o` | number | Original size |

Example, with illustrative values:

```json theme={"theme":"github-dark"}
[{"i": 101, "a": 7, "s": 1, "p": 100.5, "r": 0.5, "o": 1.0}]
```

## Order-Level Book (L4) (`l4_orderbook`)

### Order-Level Book (L4): Hyperliquid perpetuals

L4 order-level orderbook diffs. Every order placed, modified, or removed from the book with user attribution. Rows are ordered by `(block_number, seq)`.

| Column | Type | Description |
| - | - | - |
| `timestamp` | timestamp\[ms, UTC] | Event timestamp |
| `block_time` | timestamp\[ms, UTC] | Block timestamp |
| `block_number` | uint64 | Hyperliquid block number |
| `seq` | uint32 | Per-block event index (0-based). `(block_number, seq)` uniquely identifies an event. |
| `coin` | string | Symbol |
| `user_address` | string | Address of the order owner |
| `oid` | uint64 | Order ID |
| `side` | string | `B` = bid/buy, `A` = ask/sell |
| `price` | double | Order price |
| `diff_type` | string | `new` = placed, `update` = size changed, `remove` = removed |
| `new_size` | double (nullable) | New size after update. Null for removes. |

### Order-Level Book (L4): Hyperliquid perpetuals: `l4_checkpoints` snapshots file

Periodic L4 orderbook snapshots (\~14 min intervals). Each `data` value holds the full order-level book as JSON text. Rows are ordered by `timestamp`.

| Column | Type | Description |
| - | - | - |
| `timestamp` | timestamp\[ms, UTC] | Checkpoint timestamp |
| `coin` | string | Symbol |
| `data` | string (JSON) | JSON text; the layout is below the table |
| `last_block_number` | uint64 | Hyperliquid block height the snapshot reflects. 0 when the checkpoint has no block number; see [Rebuilding order books](#rebuilding-order-books). |

**`data`**: Plain JSON text, not compressed: `[bids, asks]`. Each side is an array of `[user_address, order]` pairs. Within a price level, orders are listed in queue order; sort by price yourself if you need the levels in order. Parse it with any JSON parser.

| Field | Type | Meaning |
| - | - | - |
| `oid` | integer | Order ID; matches `oid` in the change and order event files |
| `side` | string | `B` for a bid, `A` for an ask |
| `limitPx` | string (decimal) | Limit price |
| `sz` | string (decimal) | Remaining size |
| `timestamp` | integer | Time the order joined its price level, in Unix milliseconds; can be absent |
| `coin` | string | Symbol; can be absent, so take the symbol from the file name or the `coin` column instead |

Other order fields from the venue can appear in `order`.

Example, with illustrative values:

```json theme={"theme":"github-dark"}
[[["0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", {"oid": 2, "limitPx": "100.5", "sz": "1.0", "timestamp": 5, "side": "B"}]], [["0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", {"oid": 3, "limitPx": "101.0", "sz": "2.0", "timestamp": 6, "side": "A"}]]]
```

To read it in Python:

```python theme={"theme":"github-dark"}
import json
from decimal import Decimal

bids, asks = json.loads(row["data"])
for user_address, order in bids:
    price, size = Decimal(order["limitPx"]), Decimal(order["sz"])
```

### Order-Level Book (L4): Hyperliquid Spot

Spot L4 order-level orderbook diffs with user attribution. Every order placed, modified, or removed from the spot book. Live coverage from 2026-03-10. Rows are ordered by `(block_number, seq)`.

| Column | Type | Description |
| - | - | - |
| `timestamp` | timestamp\[ms, UTC] | Event timestamp |
| `block_time` | timestamp\[ms, UTC] | Block timestamp |
| `block_number` | uint64 | Hyperliquid block number |
| `seq` | uint32 | Per-block event index (0-based). `(block_number, seq)` uniquely identifies an event. |
| `coin` | string | Wire-format spot coin (`PURR/USDC` or `@<index>`) |
| `user_address` | string | Address of the order owner |
| `oid` | uint64 | Order ID |
| `side` | string | `B` = bid/buy, `A` = ask/sell |
| `price` | double | Order price (quote per base) |
| `diff_type` | string | `new` = placed, `update` = size changed, `remove` = removed |
| `new_size` | double (nullable) | New size after update. Null for removes. |

### Order-Level Book (L4): Hyperliquid Spot: `l4_checkpoints` snapshots file

Periodic spot L4 orderbook snapshots. Each `data` field contains the full order-level book as JSON. Live coverage from 2026-03-11. Rows are ordered by `timestamp`.

| Column | Type | Description |
| - | - | - |
| `timestamp` | timestamp\[ms, UTC] | Checkpoint timestamp |
| `coin` | string | Wire-format spot coin (`PURR/USDC` or `@<index>`) |
| `data` | string (JSON) | JSON text; the layout is below the table |
| `last_block_number` | uint64 | Hyperliquid block height the snapshot reflects. 0 when the checkpoint has no block number; see [Rebuilding order books](#rebuilding-order-books). |

**`data`**: Plain JSON text, not compressed: `[bids, asks]`. Each side is an array of `[user_address, order]` pairs. Within a price level, orders are listed in queue order; sort by price yourself if you need the levels in order. Parse it with any JSON parser.

| Field | Type | Meaning |
| - | - | - |
| `oid` | integer | Order ID; matches `oid` in the change and order event files |
| `side` | string | `B` for a bid, `A` for an ask |
| `limitPx` | string (decimal) | Limit price |
| `sz` | string (decimal) | Remaining size |
| `timestamp` | integer | Time the order joined its price level, in Unix milliseconds; can be absent |
| `coin` | string | Symbol; can be absent, so take the symbol from the file name or the `coin` column instead |

Other order fields from the venue can appear in `order`.

Example, with illustrative values:

```json theme={"theme":"github-dark"}
[[["0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", {"oid": 2, "limitPx": "100.5", "sz": "1.0", "timestamp": 5, "side": "B"}]], [["0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", {"oid": 3, "limitPx": "101.0", "sz": "2.0", "timestamp": 6, "side": "A"}]]]
```

To read it in Python:

```python theme={"theme":"github-dark"}
import json
from decimal import Decimal

bids, asks = json.loads(row["data"])
for user_address, order in bids:
    price, size = Decimal(order["limitPx"]), Decimal(order["sz"])
```

### Order-Level Book (L4): HIP-3

HIP-3 L4 order-level orderbook diffs with user attribution. Rows are ordered by `(block_number, seq)`.

| Column | Type | Description |
| - | - | - |
| `timestamp` | timestamp\[ms, UTC] | Event timestamp |
| `block_time` | timestamp\[ms, UTC] | Block timestamp |
| `block_number` | uint64 | Block number |
| `seq` | uint32 | Per-block event index (0-based). `(block_number, seq)` uniquely identifies an event. |
| `coin` | string | HIP-3 symbol |
| `user_address` | string | Order owner address |
| `oid` | uint64 | Order ID |
| `side` | string | `B` = bid, `A` = ask |
| `price` | double | Order price |
| `diff_type` | string | `new`, `update`, `remove` |
| `new_size` | double (nullable) | New size. Null for removes. |

### Order-Level Book (L4): HIP-3: `l4_checkpoints` snapshots file

Periodic L4 orderbook snapshots (\~14 min intervals). Each `data` value holds the full order-level book as JSON text. Rows are ordered by `timestamp`.

| Column | Type | Description |
| - | - | - |
| `timestamp` | timestamp\[ms, UTC] | Checkpoint timestamp |
| `coin` | string | Symbol |
| `data` | string (JSON) | JSON text; the layout is below the table |
| `last_block_number` | uint64 | Hyperliquid block height the snapshot reflects. 0 when the checkpoint has no block number; see [Rebuilding order books](#rebuilding-order-books). |

**`data`**: Plain JSON text, not compressed: `[bids, asks]`. Each side is an array of `[user_address, order]` pairs. Within a price level, orders are listed in queue order; sort by price yourself if you need the levels in order. Parse it with any JSON parser.

| Field | Type | Meaning |
| - | - | - |
| `oid` | integer | Order ID; matches `oid` in the change and order event files |
| `side` | string | `B` for a bid, `A` for an ask |
| `limitPx` | string (decimal) | Limit price |
| `sz` | string (decimal) | Remaining size |
| `timestamp` | integer | Time the order joined its price level, in Unix milliseconds; can be absent |
| `coin` | string | Symbol; can be absent, so take the symbol from the file name or the `coin` column instead |

Other order fields from the venue can appear in `order`.

Example, with illustrative values:

```json theme={"theme":"github-dark"}
[[["0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", {"oid": 2, "limitPx": "100.5", "sz": "1.0", "timestamp": 5, "side": "B"}]], [["0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", {"oid": 3, "limitPx": "101.0", "sz": "2.0", "timestamp": 6, "side": "A"}]]]
```

To read it in Python:

```python theme={"theme":"github-dark"}
import json
from decimal import Decimal

bids, asks = json.loads(row["data"])
for user_address, order in bids:
    price, size = Decimal(order["limitPx"]), Decimal(order["sz"])
```

### Order-Level Book (L4): HIP-4

HIP-4 L4 order-level orderbook diffs with user attribution. `price` is an implied probability in \[0, 1]. Rows are ordered by `(block_number, seq)`.

| Column | Type | Description |
| - | - | - |
| `timestamp` | timestamp\[ms, UTC] | Event timestamp |
| `block_time` | timestamp\[ms, UTC] | Block timestamp |
| `block_number` | uint64 | Block number |
| `seq` | uint32 | Per-block event index (0-based). `(block_number, seq)` uniquely identifies an event. |
| `coin` | string | HIP-4 outcome symbol |
| `user_address` | string | Order owner address |
| `oid` | uint64 | Order ID |
| `side` | string | `B` = bid, `A` = ask |
| `price` | double | Order price (implied probability in \[0, 1]) |
| `diff_type` | string | `new`, `update`, `remove` |
| `new_size` | double (nullable) | New size. Null for removes. |

### Order-Level Book (L4): HIP-4: `l4_checkpoints` snapshots file

Periodic HIP-4 L4 orderbook snapshots (\~60s intervals). Each `data` field contains the full order-level book as JSON. Rows are ordered by `timestamp`.

| Column | Type | Description |
| - | - | - |
| `timestamp` | timestamp\[ms, UTC] | Checkpoint timestamp |
| `coin` | string | HIP-4 outcome symbol |
| `data` | string (JSON) | JSON text; the layout is below the table |
| `bid_count` | uint32 | Number of bid orders in snapshot |
| `ask_count` | uint32 | Number of ask orders in snapshot |
| `last_block_number` | uint64 | Hyperliquid block height the snapshot reflects. 0 when the checkpoint has no block number; see [Rebuilding order books](#rebuilding-order-books). |

**`data`**: Plain JSON text, not compressed: `[bids, asks]`. Each side is an array of `[user_address, order]` pairs. Within a price level, orders are listed in queue order; sort by price yourself if you need the levels in order. Parse it with any JSON parser.

| Field | Type | Meaning |
| - | - | - |
| `oid` | integer | Order ID; matches `oid` in the change and order event files |
| `side` | string | `B` for a bid, `A` for an ask |
| `limitPx` | string (decimal) | Limit price |
| `sz` | string (decimal) | Remaining size |
| `timestamp` | integer | Time the order joined its price level, in Unix milliseconds; can be absent |
| `coin` | string | Symbol; can be absent, so take the symbol from the file name or the `coin` column instead |

Other order fields from the venue can appear in `order`.

Example, with illustrative values:

```json theme={"theme":"github-dark"}
[[["0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", {"oid": 2, "limitPx": "0.62", "sz": "100.0", "timestamp": 5, "side": "B"}]], [["0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", {"oid": 3, "limitPx": "0.63", "sz": "50.0", "timestamp": 6, "side": "A"}]]]
```

To read it in Python:

```python theme={"theme":"github-dark"}
import json
from decimal import Decimal

bids, asks = json.loads(row["data"])
for user_address, order in bids:
    price, size = Decimal(order["limitPx"]), Decimal(order["sz"])
```

## Order Events / TP/SL (`l4_orders`)

### Order Events / TP/SL: Hyperliquid perpetuals

Complete order lifecycle events: place, fill, cancel, trigger, liquidation. Includes TP/SL, stop orders, and user attribution. Rows are ordered by `(block_number, seq)`.

| Column | Type | Description |
| - | - | - |
| `timestamp` | timestamp\[ms, UTC] | Event timestamp |
| `block_time` | timestamp\[ms, UTC] | Block timestamp |
| `block_number` | uint64 | Hyperliquid block number |
| `seq` | uint32 | Per-block event index (0-based). `(block_number, seq)` uniquely identifies an event. |
| `coin` | string | Symbol |
| `user_address` | string | Address that placed the order |
| `oid` | uint64 | Order ID: links all lifecycle events |
| `status` | string | `open`, `filled`, `canceled`, `triggered`, etc. |
| `side` | string | `B` = buy, `A` = sell |
| `limit_price` | double | Limit price |
| `size` | double | Remaining size |
| `orig_size` | double | Original size at placement |
| `order_type` | string | `Limit` |
| `is_trigger` | uint8 | `1` = stop/trigger order |
| `trigger_price` | double | Trigger price (0 if not trigger) |
| `trigger_condition` | string | e.g., `Price above 70000` |
| `is_position_tpsl` | uint8 | `1` = TP/SL attached to position |
| `reduce_only` | uint8 | `1` = reduce-only |
| `tif` | string | `Gtc`, `Ioc`, `Alo` |
| `cloid` | string | Client order ID |
| `builder` | string | Builder address |
| `children` | string (JSON) | Linked child order IDs |
| `tx_hash` | string | Transaction hash |

### Order Events / TP/SL: Hyperliquid Spot

Spot order lifecycle events, including rejected orders. `status` is one of `open`, `filled`, `canceled`, `selfTradeCanceled`, `badAloPxRejected`, `insufficientSpotBalanceRejected`, `iocCancelRejected`, or `minTradeNtlRejected`. Live coverage from 2026-03-10. Rows are ordered by `(block_number, seq)`.

| Column | Type | Description |
| - | - | - |
| `timestamp` | timestamp\[ms, UTC] | Event timestamp |
| `block_time` | timestamp\[ms, UTC] | Block timestamp |
| `block_number` | uint64 | Hyperliquid block number |
| `seq` | uint32 | Per-block event index (0-based). `(block_number, seq)` uniquely identifies an event. |
| `coin` | string | Wire-format spot coin (`PURR/USDC` or `@<index>`) |
| `user_address` | string | Address that placed the order |
| `tx_hash` | string | Transaction hash |
| `oid` | uint64 | Order ID. Links all lifecycle events. |
| `status` | string | Order status; the values are listed above the table |
| `side` | string | `B` = buy, `A` = sell |
| `limit_price` | double | Limit price (quote per base) |
| `size` | double | Remaining size |
| `orig_size` | double | Original size at placement |
| `order_type` | string | `Limit` or `Market` |
| `is_trigger` | uint8 | `1` = stop/trigger order |
| `trigger_price` | double | Trigger price (0 if not trigger) |
| `trigger_condition` | string | Trigger description |
| `is_position_tpsl` | uint8 | `1` = TP/SL attached to position. Always 0 in practice for spot. |
| `reduce_only` | uint8 | `1` = reduce-only. Always 0 in practice for spot; field preserved for parity with perps. |
| `tif` | string | `Alo`, `FrontendMarket`, `Gtc`, `Ioc` |
| `cloid` | string | Client order ID |
| `builder` | string | Builder/router address (empty for direct submissions) |

### Order Events / TP/SL: HIP-3

HIP-3 order lifecycle events with user attribution. Rows are ordered by `(block_number, seq)`.

| Column | Type | Description |
| - | - | - |
| `timestamp` | timestamp\[ms, UTC] | Event timestamp |
| `block_time` | timestamp\[ms, UTC] | Block timestamp |
| `block_number` | uint64 | Block number |
| `seq` | uint32 | Per-block event index (0-based). `(block_number, seq)` uniquely identifies an event. |
| `coin` | string | HIP-3 symbol |
| `user_address` | string | Order owner |
| `oid` | uint64 | Order ID |
| `status` | string | `open`, `filled`, `canceled`, etc. |
| `side` | string | `B` = buy, `A` = sell |
| `limit_price` | double | Limit price |
| `size` | double | Remaining size |
| `orig_size` | double | Original size |
| `order_type` | string | Order type |
| `is_trigger` | uint8 | `1` = trigger order |
| `trigger_price` | double | Trigger price |
| `trigger_condition` | string | Trigger description |
| `is_position_tpsl` | uint8 | `1` = TP/SL |
| `reduce_only` | uint8 | `1` = reduce-only |
| `tif` | string | Time-in-force |
| `cloid` | string | Client order ID |
| `builder` | string | Builder address |
| `children` | string (JSON) | Child orders |
| `tx_hash` | string | Transaction hash |

### Order Events / TP/SL: HIP-4

HIP-4 order lifecycle events with user attribution. `status` values include `open`, `filled`, `canceled`, and `insufficientSpotBalanceRejected`. Rows are ordered by `(block_number, seq)`.

| Column | Type | Description |
| - | - | - |
| `timestamp` | timestamp\[ms, UTC] | Event timestamp |
| `block_time` | timestamp\[ms, UTC] | Block timestamp |
| `block_number` | uint64 | Block number |
| `seq` | uint32 | Per-block event index (0-based). `(block_number, seq)` uniquely identifies an event. |
| `coin` | string | HIP-4 outcome symbol |
| `user_address` | string | Order owner |
| `oid` | uint64 | Order ID |
| `status` | string | Order status; values are listed above the table |
| `side` | string | `B` = buy, `A` = sell |
| `limit_price` | double | Limit price (implied probability in \[0, 1]) |
| `size` | double | Remaining size |
| `orig_size` | double | Original size |
| `order_type` | string | Order type |
| `is_trigger` | uint8 | `1` = trigger order |
| `trigger_price` | double | Trigger price |
| `trigger_condition` | string | Trigger description |
| `is_position_tpsl` | uint8 | `1` = TP/SL |
| `reduce_only` | uint8 | `1` = reduce-only |
| `tif` | string | Time-in-force |
| `cloid` | string | Client order ID |
| `builder` | string | Builder address |
| `children` | string (JSON) | Child orders |
| `tx_hash` | string | Transaction hash |

## Trades (`trades`)

### Trades: Hyperliquid perpetuals

Individual trade fills with maker/taker attribution. Each trade produces two fills (one per side). `crossed=true` indicates the taker side. Rows are ordered by `timestamp`.

| Column | Type | Description |
| - | - | - |
| `timestamp` | timestamp\[ms, UTC] | Fill timestamp |
| `coin` | string | Symbol |
| `side` | string | `B` = buy, `S` = sell |
| `price` | double | Fill price |
| `size` | double | Fill size |
| `trade_id` | int64 | Trade ID (same for both sides of a trade) |
| `order_id` | int64 | Order ID for this fill (`oid`) |
| `user_address` | string | Ethereum address of this fill's owner |
| `crossed` | bool | `true` = taker (crossed the spread), `false` = maker |
| `direction` | string | `Open Long`, `Close Short`, etc. Empty for fills recorded from the live feed. |
| `fee` | double | Fee paid (negative = rebate) |
| `closed_pnl` | double | Realized PnL on this fill |
| `start_position` | double | Position size before this fill |
| `tx_hash` | string | Transaction hash |
| `builder_address` | string | Builder address that routed this order |
| `builder_fee` | double | Builder fee charged on this fill |
| `deployer_fee` | double | HIP-3 deployer fee share (0 for Hyperliquid perps) |
| `priority_gas` | double | Priority fee burned in HYPE for write priority |
| `cloid` | string | Client order ID |
| `twap_id` | int64 | TWAP execution ID (0 if not a TWAP order) |

### Trades: Hyperliquid Spot

Spot trade fills with maker/taker attribution and full fee breakdown. Each trade produces two fills (one per side). `direction` is `Buy` or `Sell` (spot semantics, not perp-style `Open Long` / `Close Short`). `fee_token` is open-set: USDC, PURR, HYPE, KHYPE, USOL, and other deployer tokens. History starts on 2025-03-22. Rows are ordered by `timestamp`.

| Column | Type | Description |
| - | - | - |
| `timestamp` | timestamp\[ms, UTC] | Fill timestamp |
| `block_time` | timestamp\[ms, UTC] | Block timestamp |
| `block_number` | uint64 | Hyperliquid block number |
| `coin` | string | Wire-format spot coin (`PURR/USDC` or `@<index>`) |
| `side` | string | `B` = buy, `A` = sell |
| `price` | double | Fill price (quote per base) |
| `size` | double | Fill size (base units) |
| `trade_id` | int64 | Trade ID (same for both sides of a trade) |
| `order_id` | int64 | Order ID for this fill (`oid`) |
| `user_address` | string (nullable) | Address of this fill's owner |
| `crossed` | bool (nullable) | `true` = taker (crossed the spread), `false` = maker |
| `direction` | string (nullable) | `Buy` or `Sell` (spot semantics) |
| `fee` | double | Fee paid (negative = rebate) |
| `fee_token` | string | Token the fee was paid in. Open set: `USDC`, `PURR`, `HYPE`, `KHYPE`, `USOL`, and other deployer tokens. |
| `closed_pnl` | double | Realized PnL on this fill |
| `start_position` | double | Position size before this fill |
| `tx_hash` | string (nullable) | Transaction hash. Null or zero when the fill has none. |
| `builder_address` | string | Builder/router address that submitted this order (empty for direct submissions) |
| `builder_fee` | double | Fee paid to the builder |
| `cloid` | string | Client order ID |
| `twap_id` | int64 | TWAP execution ID (0 if not a TWAP child fill). |
| `source` | string | How the fill was recorded: `node` (captured live) or `s3` (loaded from the history Hyperliquid publishes) |

### Trades: HIP-3

HIP-3 trade fills with direction, maker/taker attribution, fee breakdown, realized PnL, and tx hash. Each trade produces two fills (one per side). Rows are ordered by `timestamp`.

| Column | Type | Description |
| - | - | - |
| `timestamp` | timestamp\[ms, UTC] | Fill timestamp |
| `coin` | string | HIP-3 symbol |
| `side` | string | `B` = buy, `A` = sell |
| `price` | double | Fill price |
| `size` | double | Fill size |
| `trade_id` | int64 | Trade ID |
| `order_id` | int64 | Order ID for this fill (`oid`) |
| `user_address` | string (nullable) | Account address |
| `crossed` | bool (nullable) | `true` = taker (crossed the spread), `false` = maker |
| `direction` | string (nullable) | `Open Long`, `Close Short`, etc. |
| `fee` | double | Fee paid (negative = rebate). Denominated in the deployer's quote token. |
| `closed_pnl` | double | Realized PnL on this fill (nonzero only when closing a position) |
| `start_position` | double | Position size before this fill |
| `tx_hash` | string (nullable) | L1 transaction hash for this fill |
| `builder_address` | string | Builder address that routed this order |
| `builder_fee` | double | Builder fee charged on this fill |
| `deployer_fee` | double | HIP-3 deployer fee share |
| `priority_gas` | double | Priority fee burned in HYPE for write priority |
| `cloid` | string | Client order ID |
| `twap_id` | int64 | TWAP execution ID (0 if not a TWAP order) |

### Trades: HIP-4

HIP-4 trade fills for outcome markets. `price` is an implied probability in \[0, 1]. `is_settlement_fill=1` marks synthetic settlement-payout fills. Rows are ordered by `timestamp`.

| Column | Type | Description |
| - | - | - |
| `timestamp` | timestamp\[ms, UTC] | Fill timestamp |
| `coin` | string | HIP-4 outcome symbol |
| `side` | string | `B` = buy, `A` = sell |
| `price` | double | Fill price (implied probability in \[0, 1]) |
| `size` | double | Fill size (contracts) |
| `trade_id` | int64 | Trade ID |
| `order_id` | int64 | Order ID for this fill (`oid`) |
| `user_address` | string (nullable) | Account address |
| `crossed` | bool (nullable) | `true` = taker |
| `direction` | string (nullable) | `Open Long`, `Close Short`, etc. |
| `builder_address` | string | Builder address that routed this order |
| `builder_fee` | double | Builder fee charged on this fill |
| `deployer_fee` | double | Deployer fee share |
| `priority_gas` | double | Priority fee burned in HYPE for write priority |
| `cloid` | string | Client order ID |
| `twap_id` | int64 | TWAP execution ID (0 if not a TWAP order) |
| `is_settlement_fill` | uint8 | `1` = synthetic settlement-payout fill, `0` = normal trade |

### Trades: Lighter and Lighter on Robinhood Chain

Trade fills with maker/taker attribution. Rows are ordered by `timestamp`.

| Column | Type | Description |
| - | - | - |
| `timestamp` | timestamp\[ms, UTC] | Fill timestamp |
| `symbol` | string | Symbol |
| `side` | string | `B` = buy, `S` = sell |
| `price` | double | Fill price |
| `size` | double | Fill size |
| `trade_id` | int64 | Trade ID |
| `user_address` | string (nullable) | Account address |
| `crossed` | bool | `true` = taker |

## Funding Rates (`funding`)

### Funding Rates: Hyperliquid perpetuals

Funding rate snapshots. Rates are per-hour; multiply by 24 for daily or 8760 for annualized. Rows are ordered by `timestamp`.

| Column | Type | Description |
| - | - | - |
| `timestamp` | timestamp\[ms, UTC] | Snapshot timestamp |
| `coin` | string | Symbol |
| `funding_rate` | double | Hourly funding rate |
| `premium` | double (nullable) | Premium component |

### Funding Rates: HIP-3

HIP-3 funding rate snapshots. Rows are ordered by `timestamp`.

| Column | Type | Description |
| - | - | - |
| `timestamp` | timestamp\[ms, UTC] | Snapshot timestamp |
| `coin` | string | HIP-3 symbol |
| `funding_rate` | double | Funding rate |
| `premium` | double (nullable) | Premium component |

### Funding Rates: Lighter and Lighter on Robinhood Chain

Funding rate snapshots. Rows are ordered by `timestamp`.

| Column | Type | Description |
| - | - | - |
| `timestamp` | timestamp\[ms, UTC] | Snapshot timestamp |
| `symbol` | string | Symbol |
| `funding_rate` | double | Funding rate |

## Open Interest (`oi`)

### Open Interest: Hyperliquid perpetuals

Open interest snapshots with mark price and volume. Rows are ordered by `timestamp`.

| Column | Type | Description |
| - | - | - |
| `timestamp` | timestamp\[ms, UTC] | Snapshot timestamp |
| `coin` | string | Symbol |
| `open_interest` | double | Total open interest |
| `mark_price` | double (nullable) | Mark price |
| `oracle_price` | double (nullable) | Oracle price |
| `day_ntl_volume` | double (nullable) | 24h notional volume |
| `mid_price` | double (nullable) | Mid price |

### Open Interest: HIP-3

HIP-3 open interest snapshots. Rows are ordered by `timestamp`.

| Column | Type | Description |
| - | - | - |
| `timestamp` | timestamp\[ms, UTC] | Snapshot timestamp |
| `coin` | string | HIP-3 symbol |
| `open_interest` | double | Total open interest |
| `mark_price` | double (nullable) | Mark price |
| `oracle_price` | double (nullable) | Oracle price |
| `mid_price` | double (nullable) | Mid price |

### Open Interest: HIP-4

HIP-4 open interest snapshots. `mark_price` is an implied probability in \[0, 1], NOT a USD price. No oracle\_price column (HIP-4 outcomes have no oracle feed). Rows are ordered by `timestamp`.

| Column | Type | Description |
| - | - | - |
| `timestamp` | timestamp\[ms, UTC] | Snapshot timestamp |
| `coin` | string | HIP-4 outcome symbol |
| `open_interest` | double | Total open interest (contracts) |
| `mark_price` | double (nullable) | Implied probability in \[0, 1] (NOT a USD price) |
| `mid_price` | double (nullable) | Mid implied probability |

### Open Interest: Lighter and Lighter on Robinhood Chain

Open interest snapshots. Rows are ordered by `timestamp`.

| Column | Type | Description |
| - | - | - |
| `timestamp` | timestamp\[ms, UTC] | Snapshot timestamp |
| `symbol` | string | Symbol |
| `open_interest` | double | Total open interest |
| `mark_price` | double (nullable) | Mark price |
| `index_price` | double (nullable) | Index/oracle price |

## Liquidations (`liquidations`)

### Liquidations: Hyperliquid perpetuals

Individual liquidation events with user attribution. Rows are ordered by `timestamp`.

| Column | Type | Description |
| - | - | - |
| `timestamp` | timestamp\[ms, UTC] | Liquidation timestamp |
| `coin` | string | Symbol |
| `liquidated_user` | string | Address of the liquidated account |
| `liquidator_user` | string | Address of the liquidator |
| `side` | string | `B` = buy, `S` = sell |
| `price` | double | Liquidation price |
| `size` | double | Liquidated size |
| `mark_price` | double | Mark price at liquidation |
| `closed_pnl` | double | Realized PnL |
| `direction` | string | `Open Long`, `Close Short`, etc. |
| `trade_id` | int64 | Trade ID |
| `tx_hash` | string | Transaction hash |

### Liquidations: HIP-3

HIP-3 liquidation events. Rows are ordered by `timestamp`.

| Column | Type | Description |
| - | - | - |
| `timestamp` | timestamp\[ms, UTC] | Liquidation timestamp |
| `coin` | string | HIP-3 symbol |
| `side` | string | `B` = buy, `A` = sell |
| `price` | double | Liquidation price |
| `size` | double | Size |
| `trade_id` | int64 | Trade ID |
| `user_address` | string | Address of the fill |
| `direction` | string | `Open Long`, `Close Short`, etc. |
| `liquidated_user` | string | Liquidated account address |
| `mark_price` | double | Mark price at liquidation |

## Rebuilding order books

An L4 order book export and a Lighter L2 order book export each come as a file of changes and a file of snapshots. Both cover the same UTC dates as your order: nothing from before your start date is included. So the first moment you can rebuild is the first usable snapshot in the files, not 00:00 UTC on your start date. To rebuild from a given time, include enough earlier history in your order to contain a usable snapshot before that time.

### L4 order books

This applies to Hyperliquid perpetuals, Spot, HIP-3, and HIP-4. Checkpoint files come in one file per 7 days of your range; a window with no checkpoints has no file.

1. **Pick a checkpoint.** Use one whose `last_block_number` is greater than 0 and whose `data` does not contain the text `_backfilled`. Skip any other checkpoint: a 0 means the checkpoint has no block number to start from, and `_backfilled` marks a checkpoint that was rebuilt later rather than recorded.
2. **Load its book** from `data`.
3. **Apply changes in `(block_number, seq)` order, starting with the first change whose `block_number` is greater than the checkpoint's `last_block_number`.** Changes in that block or earlier are already in the checkpoint. `new` places an order of size `new_size`, `update` sets its remaining size to `new_size`, and `remove` deletes it.

Align by block number, never by timestamp. A checkpoint's `timestamp` is when it was written, which is after the block it reflects, so changes with an earlier timestamp can still come after it. Each change carries the order's full new size, so applying a change the checkpoint already reflects does no harm, but skipping one leaves the book wrong.

Checkpoint block numbers are exact from 2026-06-07 02:21 UTC. Earlier ones were filled in afterwards. Those that could be repaired are at or below the true block, which is safe; the rest may be above it, which skips changes. The files do not say which is which, so when you start from a checkpoint recorded before 2026-06-07 02:21 UTC, check the rebuilt book against the next checkpoint before relying on it.

Some new orders join their price level ahead of orders already waiting there. The change file does not record that position, so after a rebuild the order of orders within a level can differ from the venue's queue. Prices and sizes are exact.

### Lighter L2 order books

This applies to Lighter and Lighter on Robinhood Chain. The `l2_checkpoints` file holds a full-book snapshot about once a minute for each market.

1. **Load a snapshot** from `bids` and `asks`.
2. **Apply the changes whose `timestamp` is after the snapshot's `timestamp`, in `(timestamp, sequence)` order.** Each change sets a price level's total size; a size of 0 removes the level.

A snapshot is taken right after the changes of the update it is stamped with, so changes with the same timestamp are already in it. If a second update arrived in the same millisecond, its changes share the snapshot's timestamp but are not in it, and the files cannot tell them apart; the affected levels are corrected by their next change.


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