debug_traceBlockByHash

A 32-byte block hash points at exactly one block, fork or no fork. That is what sets debug_traceBlockByHash apart from its by-number twin: feed it a hash and you get an opcode-level trace of every transaction in that specific block, even if a competing block won the same height. On BNB Smart Chain (BSC), where PoSA consensus seals a block roughly every three seconds and short reorgs do happen, that determinism matters. Send the request to chain ID 56 at https://bsc.therpc.io/YOUR_API_KEY. The call replays the whole block against historical state, so plan on a debug-enabled archive node.

Use cases

Trace a single block when all you have is its hash, for instance a candidate surfaced mid-way through a reorg investigation.
Inspect every internal call inside an orphaned or side-chain block that lost its height and never became canonical.
Build a block-level call graph for MEV work with callTracer, capturing each transaction's nested calls in fork order.

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://bsc.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 BNB Smart Chain 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

Cost matches debug_traceBlockByNumber, since both re-run every transaction the block carries.
Historical blocks demand archive state. A pruned BSC node only serves the recent window and rejects the rest.
A block stuffed with heavy BEP-20 or DeFi transactions can overrun the default remote timeout, and lower tiers may rate-limit it.

Supported networks

Mainnet — Chain ID: 56
Testnet — Chain ID: 97