GetRawBookDiffs - Get Book Diff Data

Retrieve order book diffs at a specific position from the Hyperliquid L1 Gateway.

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(Position) returns (BlockRawBookDiffs) {}

Common Use Cases

1. Inspect a Single Block

def get_block_diffs(client, metadata, block_height):
    request = hyperliquid_pb2.Position(block_height=block_height)
    response = client.GetRawBookDiffs(request, metadata=metadata)
    block = json.loads(response.data)

    for event in block.get('events', []):
        print(event['coin'], event['oid'], event['raw_book_diff'])

2. Replay a Block Range

def replay_diffs(client, metadata, start_block, end_block):
    for block_height in range(start_block, end_block + 1):
        request = hyperliquid_pb2.Position(block_height=block_height)
        response = client.GetRawBookDiffs(request, metadata=metadata)
        apply(json.loads(response.data))

Best Practices

1. Position Selection: Use block height for precise queries; timestamps may resolve to different blocks across requests
2. Stable Keys: Index resting orders on (coin, oid), never on oid alone
3. Data Validation: Always validate JSON structure and branch on the raw_book_diff shape
4. Error Recovery: Implement retry logic with exponential backoff
5. Resource Management: Close gRPC connections properly to avoid resource leaks

Current Limitations

• Backfill Window: Positions outside the node's retained on-disk feed are not available; an unconfigured feed directory returns NotFound
• 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
• Archival Data - Historical node_raw_book_diffs_by_block downloads

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