get_block (gRPC) | Hyperliquid API Docs

Retrieve a single block from Hyperliquid L1 Gateway via gRPC. Get blockchain data at a specific position.

Retrieve a single block 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

GetBlock is essential for:

Point-in-Time Analysis - Get blockchain state at a specific block or timestamp
Backtesting - Retrieve historical block data for strategy analysis
Auditing - Verify transactions and state changes at specific points
Debugging - Investigate specific blocks during development

Method Signature

protobuf

rpc GetBlock(Position) returns (Block) {}

Common Use Cases

1. Historical Block Analysis

Python

def analyze_block_activity(client, block_height):
    """Analyze trading activity in a specific block"""
    request = hyperliquid_pb2.Position(block_height=block_height)
    response = client.GetBlock(request, metadata=metadata)
    block = json.loads(response.data)

    abci_block = block.get('abci_block', {})
    bundles = abci_block.get('signed_action_bundles', [])

    analysis = {
        'block_height': abci_block.get('round'),
        'timestamp': abci_block.get('time'),
        'total_bundles': len(bundles),
        'total_actions': 0,
        'order_count': 0,
        'cancel_count': 0,
        'transfer_count': 0
    }

    for bundle in bundles:
        if len(bundle) >= 2:
            for action in bundle[1].get('signed_actions', []):
                analysis['total_actions'] += 1
                action_type = action.get('action', {}).get('type', '')

                if action_type == 'order':
                    analysis['order_count'] += 1
                elif action_type in ['cancel', 'cancelByCloid']:
                    analysis['cancel_count'] += 1
                elif action_type in ['spotSend', 'usdSend', 'withdraw3']:
                    analysis['transfer_count'] += 1

    return analysis

2. Block Comparison

func compareBlocks(client pb.HyperliquidL1GatewayClient, ctx context.Context, height1, height2 int64) {
    block1, _ := client.GetBlock(ctx, &pb.Position{Position: &pb.Position_BlockHeight{BlockHeight: height1}})
    block2, _ := client.GetBlock(ctx, &pb.Position{Position: &pb.Position_BlockHeight{BlockHeight: height2}})

    var data1, data2 map[string]interface{}
    json.Unmarshal(block1.Data, &data1)
    json.Unmarshal(block2.Data, &data2)

    abci1 := data1["abci_block"].(map[string]interface{})
    abci2 := data2["abci_block"].(map[string]interface{})

    bundles1 := abci1["signed_action_bundles"].([]interface{})
    bundles2 := abci2["signed_action_bundles"].([]interface{})

    fmt.Printf("Block %d: %d bundles\n", height1, len(bundles1))
    fmt.Printf("Block %d: %d bundles\n", height2, len(bundles2))
}

3. Transaction Verification

JavaScript

async function verifyTransaction(client, metadata, txHash, blockHeight) {
    return new Promise((resolve, reject) => {
        const request = { block_height: blockHeight };

        client.GetBlock(request, metadata, (error, response) => {
            if (error) {
                reject(error);
                return;
            }

            const block = JSON.parse(response.data);
            const bundles = block.abci_block?.signed_action_bundles || [];

            for (const bundle of bundles) {
                const bundleHash = bundle[0];
                if (bundleHash === txHash) {
                    resolve({
                        found: true,
                        block_height: block.abci_block.round,
                        bundle_data: bundle[1]
                    });
                    return;
                }
            }

            resolve({ found: false });
        });
    });
}

Best Practices

Position Selection: Use block height for precise queries; timestamps may return different blocks across requests if near block boundaries
Data Validation: Always validate JSON structure before processing
Error Recovery: Implement retry logic with exponential backoff
Resource Management: Close gRPC connections properly to avoid resource leaks
Caching: Cache block data when analyzing the same blocks multiple times

Current Limitations

Data Retention: Historical block data is limited to a 24-hour rolling window
Rate Limits: Be mindful of request frequency to avoid overwhelming the service

Resources

GitHub: gRPC Code Examples - Complete working examples
StreamBlocks Documentation - Full block specification and action types reference

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

GetBlock - Get Block Data