debug_traceBlockByHash

debug_traceBlockByHash traces a whole Ethereum mainnet block (chain ID 1, native coin ETH) addressed by its 32-byte block hash. The hash pins down exactly one block — even one that lost a reorg and never became canonical — so this is the precise entry point when you know the hash and want no ambiguity about which block you mean. The node replays every transaction in that block through the EVM and returns an opcode-level trace per transaction, in block order. Point your calls at https://ethereum.therpc.io/YOUR_API_KEY. Tracing a full block is heavy work, so it expects a debug-enabled archive node holding the state at that height.

Use cases

• Trace a specific block when all you have is its hash — common during a reorg investigation, where two blocks share a slot height and only the hash distinguishes the orphaned one from the winner.
• Audit the internal calls inside a non-canonical block. Post-Merge there are no uncles, but a block that briefly sat at the head before being reorged out still has a hash you can trace here.
• Build a block-level call graph for MEV analysis with callTracer: reconstruct every sandwich, arbitrage, and liquidation in a block as a nested call tree without parsing raw opcodes.

Parameters

Response

Example request

1curl https://ethereum.therpc.io/YOUR_API_KEY \
2  -X POST \
3  -H "Content-Type: application/json" \
4  -d '{
5    "jsonrpc": "2.0",
6    "method": "debug_traceBlockByHash",
7    "params": [
8        "0x0000000000000000000000000000000000000000000000000000000000000000",
9        {}
10      ],
11    "id": 1
12  }'

Try it live in the Ethereum playground.

Errors & troubleshooting

Common pitfalls

• It costs the same as debug_traceBlockByNumber — both replay every transaction in the block. Identifying the block by hash buys precision, not speed.
• Historical blocks need archive state. A pruned node holds only the recent trie, so an old block hash returns block not found rather than a trace.
• A block packed with DeFi calls — think a busy mainnet block full of Uniswap routes and Aave liquidations — can run long enough to trip a remote node's default trace timeout. Use a compact tracer to keep it bounded.

Supported networks

• Mainnet — Chain ID: 1
• Sepolia — Chain ID: 11155111

See also

• debug_traceBlockByNumber
• debug_traceBlock
• debug_traceTransaction
• trace_block

1curl https://ethereum.therpc.io/YOUR_API_KEY \
2  -X POST \
3  -H 'Content-Type: application/json' \
4  -d '{"jsonrpc":"2.0","id":1,"method":"debug_traceBlockByHash","params":["0x0000000000000000000000000000000000000000000000000000000000000000",{}]}'