# Hyperliquid Raw Book Diffs - Node Data

`node_raw_book_diffs_by_block` captures order-level additions, size changes, and removals. Diffs are incremental. You need an initial snapshot or another known state seed before you apply ordered diffs; raw diffs alone cannot establish the starting book.

## Access

| Availability  | Access                                                                                                                    | Details                                                                                                                                                                                                                                                                                                                                                           |
| ------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Live / replay | [StreamRawBookDiffs](https://www.dwellir.com/docs/hyperliquid/stream_raw_book_diffs) and [GetRawBookDiffs](https://www.dwellir.com/docs/hyperliquid/get_raw_book_diffs) | V3 selects with `position.block_number` or `position.timestamp`; `Record.block_number` and `Record.timestamp` are transport cursors. V3 supports the documented `users` and `coins` filters. V2 selects with `block_height` or `timestamp_ms` and returns source JSON bytes in `BlockRawBookDiffs.data`; it does not use the V3 record fields or filter contract. |
| Archival      | [S3 Bucket](https://www.dwellir.com/docs/hyperliquid/historical-data)                                                                            | S3 coverage for `node_raw_book_diffs_by_block`: `2026-01-22` to today, stored as `hourly .lz4`. Pair these objects with a snapshot or state seed.                                                                                                                                                                                                                 |

## File layout

```text
node_raw_book_diffs_by_block/<YYYYMMDD>/<hour>.lz4
```

Files contain JSON block envelopes with book mutations in `events`.

## Sample data

```json
{
  "local_time": "2026-01-01T00:00:00.100000000",
  "block_time": "2026-01-01T00:00:00.000000000",
  "block_number": 12345,
  "events": [
    {
      "user": "<redacted-user-a>",
      "oid": 101,
      "coin": "LTC",
      "side": "A",
      "px": "68.177",
      "raw_book_diff": { "new": { "sz": "5.33" } }
    },
    {
      "user": "<redacted-user-b>",
      "oid": 102,
      "coin": "xyz:XYZ100",
      "side": "A",
      "px": "25471.0",
      "raw_book_diff": "remove"
    },
    {
      "user": "<redacted-user-c>",
      "oid": 103,
      "coin": "IP",
      "side": "A",
      "px": "2.466",
      "raw_book_diff": { "update": { "origSz": "4.5", "newSz": "0.0" } }
    }
  ]
}
```

This is synthetic representative data. Production account and order identifiers are replaced or use visible `<redacted-...>` markers.

## Important fields

| Field                     | Description                                    |
| ------------------------- | ---------------------------------------------- |
| `user`                    | Owner of the resting order.                    |
| `coin`, `oid`             | Stable local-book key when used together.      |
| `side`, `px`              | Book side and price level.                     |
| `raw_book_diff.new.sz`    | Adds an order with the given size.             |
| `raw_book_diff.update`    | Changes resting size from `origSz` to `newSz`. |
| `raw_book_diff: "remove"` | Removes the order.                             |

Start from a snapshot or state seed that corresponds to a known point, then apply later envelopes in sequential `block_number` order. Detect gaps before advancing local state.

## Observed fields

`[]` marks an array element, `[0]` a tuple position, `<name>` an object whose `type` is that name, and `{key}` a map keyed by user, asset, or ID. Values after a colon are every distinct value seen for a short enum field. A field missing here can still appear in record types the sample did not contain.

Generated from 2,993 records in `node_raw_book_diffs_by_block/20261021/14.lz4` (2026-10-21).

```text
block_number                     number
block_time                       string
events                           array
events[]                         object
  coin                           string
  oid                            number
  px                             string
  raw_book_diff                  object | string: remove
    new                          object
      insertBefore               number
      sz                         string
    update                       object
      newSz                      string
      origSz                     string
  side                           string: A, B
  user                           string
local_time                       string
```

## Related pages

- [Generated order-book snapshots](https://www.dwellir.com/docs/hyperliquid/data-catalog/derived/book-snapshots) — Start reconstruction from a known order-level state.
- [L4 books](https://www.dwellir.com/docs/hyperliquid/data-catalog/derived/l4-book) — Consume the maintained order-level view instead of rebuilding it yourself.
- [Order book WebSocket guide](https://www.dwellir.com/guides/order-book-server) — Build a resilient snapshot-and-update client.