hl_getBatchBlocks | Hyperliquid API Docs

Retrieve a batch of fill blocks for a given stream and block range via the HyperCore JSON-RPC API.

Return fill blocks in a [from, to] range for a given stream.

Endpoint

Text

POST https://api-hyperliquid-mainnet-jsonrpc.n.dwellir.com/<API-KEY>/hypercore

Use this method for block retrieval. hl_getBlockByNumber is not implemented on this endpoint; to fetch a single block, set from and to to the same recent block number.

When to Use This Method

hl_getBatchBlocks is essential for:

Backfilling — Retrieve historical fill data in bulk
Batch Processing — Process trade events in ordered block ranges
Analytics Pipelines — Feed fill data into downstream systems
Reconciliation — Verify trade execution across block ranges

Curl Example

Bash

ENDPOINT='https://api-hyperliquid-mainnet-jsonrpc.n.dwellir.com/YOUR_API_KEY/hypercore'

LATEST_BLOCK=$(curl -s -X POST "$ENDPOINT" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "method": "hl_getLatestBlockNumber",
    "params": { "stream": "trades" },
    "id": 1
  }' | jq -r '.result')

FROM_BLOCK=$((LATEST_BLOCK - 100))

curl -X POST "$ENDPOINT" \
  -H 'Content-Type: application/json' \
  -d "{
    \"jsonrpc\": \"2.0\",
    \"method\": \"hl_getBatchBlocks\",
    \"params\": { \"stream\": \"trades\", \"from\": $FROM_BLOCK, \"to\": $FROM_BLOCK },
    \"id\": 2
  }"

Common Use Cases

1. Sequential Backfill

Fetch all blocks from a known starting point to the latest:

JavaScript

async function backfill(startBlock) {
  const response = await fetch(ENDPOINT, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      jsonrpc: '2.0',
      method: 'hl_getLatestBlockNumber',
      params: { stream: 'trades' },
      id: 1
    })
  });
  const { result: latestBlock } = await response.json();

  let current = startBlock;
  while (current <= latestBlock) {
    const to = Math.min(current + 99, latestBlock);
    const blocks = await getBatchBlocks(current, to);
    console.log(`Fetched blocks ${current}–${to}: ${blocks.length} blocks`);

    for (const block of blocks) {
      // Process each block
    }

    current = to + 1;
  }
}

2. Event Counting

Count fill events across a block range:

Python

def count_events(from_block: int, to_block: int) -> dict:
    blocks = get_batch_blocks(from_block, to_block)

    total_events = 0
    for block in blocks:
        total_events += len(block['events'])

    return {
        'block_range': f"{from_block}–{to_block}",
        'blocks_returned': len(blocks),
        'total_events': total_events
    }

Best Practices

Respect the batch limit — Keep ranges at or below 100 blocks per request
Use sequential fetching — Combine with hl_getLatestBlockNumber to walk forward
Stay within retention — Older ranges can return -32003 with requested range pruned
Handle sparse ranges — Some blocks in a range may have no events
Implement retries — Use exponential backoff for transient errors

hl_getLatestBlockNumber — Get the latest available block number

Query HyperCore fill data with Dwellir's JSON-RPC API. Get your API key →

hl_getBatchBlocks - Get Batch Fill Blocks