debug_traceTransaction

debug_traceTransaction takes the hash of a transaction already mined on Ethereum mainnet (chain ID 1, native coin ETH) and replays it opcode by opcode. The node rebuilds the exact EVM state as it stood at the start of that transaction — all earlier transactions in its block applied first — then re-runs it and records every instruction, stack frame, gas cost, and storage write along the way. It's the canonical tool for answering "what actually happened inside this transaction." Default output is the struct (opcode) logger, but callTracer and prestateTracer give you a call tree or a pre-execution state map instead. Send requests to https://ethereum.therpc.io/YOUR_API_KEY; older transactions need a debug-enabled archive node.

Use cases

Find out why a contract call reverted by reading the stack and memory at the exact REVERT opcode — far more precise than a generic "execution reverted" string when a Uniswap swap or token transfer fails on chain.
Profile gas opcode by opcode to find the hot spots: which SSTORE or external call dominated the bill, so you know where optimizing actually pays off against the EIP-1559 base fee.
Reconstruct an MEV bundle's full internal call tree with callTracer, mapping every nested call across the sandwich or arbitrage that the transaction triggered.
Capture the account and storage state right before execution with prestateTracer — the exact input you need to reproduce an exploit in a forked environment for a security post-mortem.

Parameters

#	Name	Type	Required	Description
1	`transactionHash`	string	Yes	Hash of the transaction to trace.
2	`options`	object	No	Tracer configuration object.

Response

Type	Description
object	With the default tracer: `{gas, failed, returnValue, structLogs[]}` where each structLog entry contains `{pc, op, gas, gasCost, depth, stack?, memory?, storage?}`. With callTracer: a nested call-tree object. With prestateTracer: a pre-execution account/storage map.

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_traceTransaction",
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 is not enabled on the node (requires --http.api=debug or equivalent).
`-32602`	`Invalid params`	Transaction hash is missing, malformed, or the options object contains unknown fields.
`-32000`	`transaction not found`	The transaction hash does not exist on the chain or the node lacks archive state for that block.

Common pitfalls

Anything older than the last few thousand blocks needs archive state. A pruned node can't rebuild the pre-execution state, so a transaction from months ago returns transaction not found unless you hit an archive node.
The default struct logger is verbose. A complex DeFi transaction can produce hundreds of megabytes of opcode records — switch to callTracer for a compact tree, or disable stack and storage in the options object when you only need the call shape.
Custom JavaScript tracers run in a sandboxed interpreter and are slow. On a long-running transaction with deep call stacks, a heavy JS tracer can blow past the node's trace timeout before it finishes.

Supported networks

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