StreamRawBookDiffs - Real-time Book Diff Streaming

Stream incremental order book changes starting from a position, providing real-time access to every addition, size change, and removal in Hyperliquid's resting book.

When to Use This Method

StreamRawBookDiffs is essential for:

• Order Book Reconstruction - Maintain a live local book by applying per-block diffs
• Liquidity Analysis - Track depth, spread, and resting-order churn over time
• Microstructure Research - Study how the book evolves block by block
• Backtesting Inputs - Replay historical book changes from a chosen position

rpc StreamRawBookDiffs(StreamRequest) returns (stream Record) {}

position: {
  block_number: 1058646974
}
filter: {
  fields: {
    field: "coins"
    op: FILTER_OP_IN
    values: "BTC"
    values: "ETH"
  }
}

Response Stream

Decode the data field to access:

• Block reference (local_time, block_time, block_number)
• An events array of incremental resting-book changes
• Per-change order context (owner, order ID, coin, side, price)

Full Book Diff Spec

StreamRawBookDiffs emits a JSON payload matching Hyperliquid's node_raw_book_diffs_by_block format. Below is the exact structure.

Top-level keys (always present):

{
  "local_time": "2026-04-20T00:00:00.040479928",   // ISO-8601 timestamp when node processed the block (nanosecond precision)
  "block_time": "2026-04-19T23:59:59.576040791",    // ISO-8601 timestamp from block consensus
  "block_number": 12345,                            // Block height containing these changes
  "events": [                                       // Array of incremental book-change objects
    {
      "user": "0x1234567890abcdef1234567890abcdef12345678",  // Order owner address
      "oid": 12345,                                 // Order identifier
      "coin": "BTC",                                // Coin identifier
      "side": "B",                                  // "B" (buy) or "A" (sell/ask)
      "px": "42000.0",                              // Price (numeric string)
      "raw_book_diff": "remove"                     // Change applied to the book (see shapes below)
    },
    {
      "user": "0x1234567890abcdef1234567890abcdef12345678",
      "oid": 12346,
      "coin": "BTC",
      "side": "A",
      "px": "42050.0",
      "raw_book_diff": { "new": { "sz": "0.5" } }   // Order added with size
    },
    {
      "user": "0x1234567890abcdef1234567890abcdef12345678",
      "oid": 12347,
      "coin": "BTC",
      "side": "A",
      "px": "42100.0",
      "raw_book_diff": { "update": { "newSz": "0.4", "origSz": "1.0" } }  // Resting size changed
    }
  ]
}

Book diff event fields (events[i]):

The raw_book_diff value takes one of three shapes:

Guarantees and alignment:

• events contains all book changes from the block, across all coins and users.
• Messages arrive in strictly increasing block_number, one per source block (including blocks with an empty events array).
• block_number is sequential and distinct from the potentially skipping abci_block.round consensus value in StreamBlocks; block_time aligns with abci_block.time.

Developer tips:

• Apply diffs in order: branch on the raw_book_diff shape to add, resize, or remove the resting order.
• Key your local book on (coin, oid), never on oid alone. See Order Identifiers.
• Normalize px, sz, newSz, and origSz (strings) to numeric types as appropriate.

Order Identifiers

oid is not reliably unique across coins. Consumers that index or join per-order state must key on the (coin, oid) tuple, never on oid alone.

Outcome markets (HIP-4) demonstrably reuse oids across the two sides of a single market (for example #30 and #31) within one block, so a diff for an oid on one coin is not necessarily the same logical order as a diff for that oid on another coin in the same block. Keying on (coin, oid) is safe whether or not oids turn out to be globally unique elsewhere.

Common Use Cases

1. Local Book Reconstruction

class BookReconstructor:
    def __init__(self):
        # (coin, oid) -> {"side", "px", "sz"}
        self.orders = {}

    def apply_block(self, block):
        for event in block.get('events', []):
            key = (event['coin'], event['oid'])
            diff = event['raw_book_diff']

            if diff == 'remove':
                self.orders.pop(key, None)
            elif 'new' in diff:
                self.orders[key] = {
                    'side': event['side'],
                    'px': event['px'],
                    'sz': diff['new']['sz'],
                }
            elif 'update' in diff:
                order = self.orders.get(key)
                if order:
                    order['sz'] = diff['update']['newSz']

2. Streaming Diffs in Python

Error Handling and Reconnection

Best Practices

1. Connection Management: Implement robust reconnection logic with exponential backoff
2. Resumable State: Follow the version-specific recovery guidance above and persist the cursor required by your selected API version
3. Stable Keys: Index resting orders on (coin, oid) to stay correct across coins
4. Performance: Apply diffs asynchronously to avoid blocking the stream
5. Resource Cleanup: Properly close streams and connections on shutdown

Current Limitations

• Replay History: Available replay history varies by feed and endpoint. A cursor outside retained history returns NOT_FOUND.
• Backpressure: High-volume periods may require careful handling to avoid overwhelming downstream systems

Resources

• GitHub: gRPC Code Examples - Complete working examples
• GetRawBookDiffs - Point-in-time book diff retrieval
• StreamOrderStatuses - The sibling block-envelope stream for order lifecycle events
• Historical Data - Historical node_raw_book_diffs_by_block downloads

Need help? Contact our support team or check the Hyperliquid gRPC documentation.