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

#	Name	Type	Required	Description
1	`blockHash`	string	Yes	Hash of the block to trace.
2	`options`	object	No	Same tracer configuration object as debug_traceTransaction.

Response

Type	Description
array	Array of per-transaction trace results in block order. Each element has the same shape as debug_traceTransaction output for the active tracer.

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

Code	Message	Cause
`-32601`	`Method not found`	debug namespace not enabled on the node.
`-32602`	`Invalid params`	Block hash is missing or not a valid 32-byte hex value.
`-32000`	`block not found`	Block hash not found or archive state unavailable.

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