debug_traceTransaction

Replays a transaction and returns its trace.

Geth reference · All supported methods

Parameters

Parameters are positional, in the order below.

Parameter	Type	Required	Description
Transaction hash	32-byte hash	Yes	Hash of the transaction.
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

The selected tracer’s result: a call-frame tree for callTracer, or account/state data for prestateTracer. diffMode returns pre- and post-execution changes.

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_traceTransaction","params":["0x1111111111111111111111111111111111111111111111111111111111111111",{"tracer":"callTracer"}]}'

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "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

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.