debug_traceBlockByNumber

debug_traceBlockByNumber runs a full trace over one Ethereum block (chain ID 1, native coin ETH) that you select by height instead of by hash. Pass a hex block number, or one of latest, earliest, pending, safe, or finalized — the last two map onto Gasper's justified and finalized checkpoints, which is the dependable way to trace heights that can no longer be reorged. For each transaction in the selected block the node re-executes it on the EVM and emits a per-transaction opcode trace, ordered as they appear on chain. Send requests to https://ethereum.therpc.io/YOUR_API_KEY. Re-running an entire block is expensive, so this needs a debug-enabled archive node for any height beyond the recent state window.

Use cases

• Audit every state transition in a block in one shot — convenient for indexers that walk the chain height by height and need each block's full execution rather than one transaction at a time.
• Pull the complete call graph of a block for MEV research with callTracer, then study how searchers ordered their transactions within the 12-second slot.
• Compare the gas profiles of all transactions in a block to flag outliers — the one swap that burned ten times the gas of its neighbors usually points at a pricing bug or an unusually deep call path.

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_traceBlockByNumber",
7    "params": [
8        "latest",
9        {}
10      ],
11    "id": 1
12  }'

Try it live in the Ethereum playground.

Errors & troubleshooting

Common pitfalls

• Tracing a block means replaying every transaction in it. A packed mainnet block can take minutes and, with the default struct logger, return gigabytes — reach for callTracer unless you truly need opcode detail.
• Archive state is required for historical heights. A pruned full node keeps only the recent trie, so anything older returns block not found.
• Tags like latest resolve at request time and can race a freshly proposed block. For results that won't shift under a reorg, trace at finalized instead — once a checkpoint finalizes (~12.8 minutes), the block is locked in.

Supported networks

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

See also

• debug_traceBlockByHash
• 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_traceBlockByNumber","params":["latest",{}]}'