debug_traceBlockByHash - Base

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

The debug_traceBlockByHash method returns traces for all transactions in a block, identified by block hash. This is useful for analyzing all activity within a specific block.

Parameters

Parameter	Type	Required	Description
blockHash	string	Yes	32-byte hash of the block
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 --location --request POST 'https://go.getblock.io/<ACCESS-TOKEN>/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "method": "debug_traceBlockByHash",
    "params": [
        "0x849a3ac8f0d81df1a645701cdb9f90e58500d2eabb80ff3b7f4e8c13f025eff2",
        {"tracer": "callTracer"}
    ],
    "id": "getblock.io"
}'

Axios

Request

Rust

Response

{
    "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

• Block Analysis: Analyze all transactions in a block

• MEV Detection: Identify sandwich attacks and arbitrage

• Gas Profiling: Profile gas usage across block transactions

• Security Auditing: Trace internal calls for vulnerabilities

• Chain Forensics: Investigate block-level activity

Error Handling

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

Web3 Integration

Ethers.js

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

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

async function traceBlockByHash(blockHash) {
    const traces = await provider.send('debug_traceBlockByHash', [
        blockHash,
        { tracer: 'callTracer' }
    ]);
    
    console.log('Total Transactions:', traces.length);
    
    traces.forEach((trace, index) => {
        const result = trace.result;
        console.log(`\nTransaction ${index}:`);
        console.log('  Hash:', trace.txHash);
        console.log('  Type:', result.type);
        console.log('  From:', result.from);
        console.log('  To:', result.to);
        console.log('  Gas Used:', parseInt(result.gasUsed, 16));
        
        if (result.error) {
            console.log('  Error:', result.error);
        }
    });
    
    return traces;
}

traceBlockByHash('0x849a3ac8f0d81df1a645701cdb9f90e58500d2eabb80ff3b7f4e8c13f025eff2');

Viem