debug_traceBlockByHash

Replays a block and returns traces for all transactions.

Geth reference · All supported methods

Parameters

Parameters are positional, in the order below.

Parameter	Type	Required	Description
Block hash	32-byte hash	Yes	See the linked specification for field encoding.
TraceConfig	Trace configuration	Yes	Specify callTracer or prestateTracer; see Direct behavior below.

Tracing options

Field	Supported values
tracer	callTracer or prestateTracer; explicitly required by Direct
tracerConfig.onlyTopCall	Boolean for callTracer; omit or use false to include nested calls
tracerConfig.diffMode	Boolean for prestateTracer; use true for state changes, otherwise return accessed pre-state
timeout	Duration string such as 5s; cannot extend the gateway waiting deadline

Return value

An array in transaction order. Each entry contains the transaction hash and the selected tracer’s result.

Example

Replace <gateway-url> with your gateway base URL and <service-url> with the chain’s service path, such as service/ethereum.

curl -X POST "<gateway-url>/<service-url>" \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":1,"method":"debug_traceBlockByHash","params":["0x1111111111111111111111111111111111111111111111111111111111111111",{"tracer":"callTracer"}]}'

Illustrative response; values depend on the selected network and request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "txHash": "0x1111111111111111111111111111111111111111111111111111111111111111",
      "result": {
        "type": "CALL",
        "from": "0x2222222222222222222222222222222222222222",
        "to": "0x3333333333333333333333333333333333333333",
        "value": "0x0",
        "gas": "0x5208",
        "gasUsed": "0x0",
        "input": "0x",
        "output": "0x"
      }
    }
  ]
}

Direct behavior

The gateway selects providers supporting the requested tracing group and format. Unsupported formats are rejected rather than replaced.

Specify tracer: "callTracer" with optional tracerConfig.onlyTopCall, or tracer: "prestateTracer" with optional tracerConfig.diffMode. Default opcode logging and arbitrary JavaScript tracers are not supported. An omitted tracer does not select a default output.

Historical replay requires archive state and full chain history alongside the tracing group. Checks exercise that combination, not just old balance queries and recent traces.

Limits

The shared limits cover the entire block and all its trace results. Internal reconstruction does not restart the deadline or create a new response allowance for each transaction. Genesis cannot be replayed because it has no parent execution state.

A debug timeout can request a shorter execution budget, but cannot extend the shared gateway deadline.

For providers

Qualify for the entire applicable tracing group, including required formats and options. Historical combinations are verified separately; recent success alone does not establish historical coverage.

See provider qualification for checks and continued eligibility.