debug_traceBlockByNumber - Base

Example code for the debug_traceBlockByNumber JSON-RPC method. Complete guide on how to use debug_traceBlockByNumber JSON-RPC in GetBlock Web3 documentation.

The debug_traceBlockByNumber method returns traces for all transactions in a block, identified by block number. This is useful for analyzing all activity within a specific block when you know the block number.

Parameters

Parameter	Type	Required	Description
blockNumber	string	Yes	Block number in hex, or "latest", "earliest", "pending"
traceOptions	object	No	Tracing options object

Trace Options

Field	Type	Description
tracer	string	Tracer type: "callTracer", "prestateTracer", or custom JS
tracerConfig	object	Configuration for the tracer
timeout	string	Timeout for the trace operation

Request

cURL

cURL

curl --location --request POST 'https://go.getblock.io/<ACCESS-TOKEN>/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "method": "debug_traceBlockByNumber",
    "params": ["0x12d687f", {"tracer": "callTracer"}],
    "id": "getblock.io"
}'

Axios (JavaScript)

Requests (Python)

Rust

Response

response.json

{
    "jsonrpc": "2.0",
    "id": "getblock.io",
    "result": [
        {
            "txHash": "0x...",
            "result": {
                "type": "CALL",
                "from": "0x...",
                "to": "0x...",
                "value": "0x0",
                "gas": "0x...",
                "gasUsed": "0x...",
                "input": "0x...",
                "output": "0x...",
                "calls": []
            }
        }
    ]
}

Response Parameters

Parameter	Type	Description
jsonrpc	string	JSON-RPC protocol version ("2.0")
id	string	Request identifier matching the request
result	array	Array of transaction traces

Trace Object

Field	Type	Description
txHash	string	Transaction hash
result	object	Trace result object

Use Cases

• Sequential Analysis: Analyze blocks in sequence by number

• Historical Research: Trace historical block activity

• Gas Analysis: Profile gas usage per block

• Indexing: Build transaction traces for indexing

• Monitoring: Track activity at specific block heights

Error Handling

Error Code	Message	Description
-32602	Invalid params	Invalid block number or options
-32603	Internal error	Trace execution failed
-32000	Block not found	Block does not exist

Web3 Integration

Ethers.js (v6)

ethers-trace.js

const { ethers } = require('ethers');

const provider = new ethers.JsonRpcProvider('https://go.getblock.io/<ACCESS-TOKEN>/');

async function traceBlockByNumber(blockNumber) {
    // Convert number to hex if needed
    const blockHex = typeof blockNumber === 'number' 
        ? '0x' + blockNumber.toString(16) 
        : blockNumber;
    
    const traces = await provider.send('debug_traceBlockByNumber', [
        blockHex,
        { tracer: 'callTracer' }
    ]);
    
    console.log('Block:', blockNumber);
    console.log('Total Transactions:', traces.length);
    
    let totalGas = 0n;
    traces.forEach((trace, index) => {
        const gasUsed = BigInt(trace.result.gasUsed);
        totalGas += gasUsed;
        
        console.log(`\nTransaction ${index}:`);
        console.log('  Type:', trace.result.type);
        console.log('  Gas Used:', gasUsed.toString());
    });
    
    console.log('\nTotal Gas Used:', totalGas.toString());
    
    return traces;
}

// Trace latest block
async function traceLatestBlock() {
    const blockNumber = await provider.getBlockNumber();
    return traceBlockByNumber(blockNumber);
}

traceLatestBlock();

Viem