GetRawBookDiffs - Get Book Diff Data
Retrieve order book diffs at a specific position from Hyperliquid L1 Gateway via gRPC. Get incremental book changes for analysis and reconstruction.
Retrieve order book diffs at a specific position from the Hyperliquid L1 Gateway.
Full Code Examples
Clone our gRPC Code Examples Repository for complete, runnable implementations in Go, Python, and Node.js.
When to Use This Method
GetRawBookDiffs is essential for:
- Targeted Reconstruction - Pull the book changes for a specific block
- Historical Analysis - Retrieve diffs for backtesting or reporting
- Auditing - Verify resting-book changes at a specific block
- Debugging - Investigate specific book transitions during development
Method signature
rpc GetRawBookDiffs(GetRequest) returns (Record) {}V3 accepts an inclusive position.block_number or Unix-millisecond position.timestamp; explicit zero is invalid. A positioned call returns the selected envelope. An empty GetRequest waits for the next diff record written after the call begins, so set a deadline.
filter: {
fields: {
field: "users"
op: FILTER_OP_IN
values: "0x1111111111111111111111111111111111111111"
}
}Raw book diffs accept users and coins filters. User matching is case-insensitive and coin matching is case-sensitive; values within a field use OR semantics and separate fields use AND semantics. A zero-match unary request returns the selected Record with data containing events: []. A pruned position returns NOT_FOUND; malformed filters return INVALID_ARGUMENT.
Seed any reconstruction from a snapshot or another known state before applying diffs.
Common Use Cases
For V3, select each record with GetRequest.position.block_number, decode Record.data, and apply the entries in its events array. Repeat positioned unary calls when reconciling a bounded block range.
Book Diff Field Reference
GetRawBookDiffs returns the same format as StreamRawBookDiffs. See the StreamRawBookDiffs documentation for the complete field reference, including the three raw_book_diff shapes and order-identifier keying.
Best Practices
- Position Selection: Use the exact sequential block cursor for precise queries; timestamp lookups may resolve to different blocks across requests
- Stable Keys: Index resting orders on
(coin, oid), never onoidalone - Data Validation: Always validate JSON structure and branch on the
raw_book_diffshape - Error Recovery: Implement retry logic with exponential backoff
- Resource Management: Close gRPC connections properly to avoid resource leaks
Current Limitations
- Replay History: Available replay history varies by feed and endpoint. A cursor outside retained history returns
NOT_FOUND - Rate Limits: Be mindful of request frequency to avoid overwhelming the service
Resources
- GitHub: gRPC Code Examples - Complete working examples
- StreamRawBookDiffs Documentation - Full book diff specification and streaming examples
- Historical Data - Historical
node_raw_book_diffs_by_blockdownloads
Need help? Contact our support team or check the Hyperliquid gRPC documentation.
GetOrderStatuses - Get Order Status Data
Retrieve order status events at a specific position from Hyperliquid L1 Gateway via gRPC. Get order lifecycle data for analysis and auditing.
GetTwapStatuses - Get TWAP Status Data
Retrieve TWAP order lifecycle events at a specific position from Hyperliquid L1 Gateway via gRPC. Get TWAP status data for reconciliation and auditing.