Debug API Endpoints

Chains Supported

MethodDescriptionEthereumPolygonArbitrumOptimismBaseAstarSolana
debug_traceBlockByHashReplays the block that is already present in the database.All NetworksAll NetworksAll NetworksAll NetworksAll NetworksUnsupportedUnsupported
debug_traceBlockByNumberReplays the block that is already present in the database.All NetworksAll NetworksAll NetworksAll NetworksAll NetworksUnsupportedUnsupported
debug_traceTransactionAttempts to run the transaction in the exact same manner as it was executed on the network.All NetworksAll NetworksAll NetworksAll NetworksAll NetworksUnsupportedUnsupported
debug_traceCallRuns an eth_call within the context of the given block execution using the final state of parent block as the base.All NetworksAll NetworksAll NetworksOptimism GoerliAll NetworksUnsupportedUnsupported

What exactly is the Debug API?

Is this a standard RPC endpoint, or is it something Alchemy has developed?

The Debug API is a set of non-standard RPC methods developed by the Go-Ethereum team, not by Alchemy.
See https://geth.ethereum.org/docs/rpc/ns-debug.

What is the difference between the Ethereum Trace API and Debug API?

The Trace API , which is supported by Erigon node clients, is equivalent to Geth's Debug API. The Debug API offers more API methods than the Trace API and is more widely used because Geth is a more popular Ethereum node client. To compare the Trace API vs. Debug API, read our API comparison guide.

Handling Errors

"execution aborted (timeout = 15s)"

If you get a -32000 timeout error on a debug_traceBlockByNumber or debug_traceBlockByHash call, we recommend fetching the traces by transaction using debug_traceTransaction instead of by block. This will give you the same exact data but broken up into smaller requests.

In short:

  • all transactions will work with debug_traceTransaction
  • not all blocks will work with debug_traceBlockByNumber or debug_traceBlockByHash - depending on the number of txs in a block we can hit our timeout (15 seconds)
  • when this happen, you just have to trace by transaction instead of by block - this is more granular and does not require tracing all txs in block at once

The reason we have this timeout in place is to protect our nodes from very large requests.
Some blocks have a large amount of transactions and could cause the call to hit a timeout.