Debug & Trace APIs - Chainstack

Overview

They provide detailed information about transactions, blocks, and smart contracts execution making it easier to identify and resolve issues within decentralized applications. By using debug and trace APIs, developers can build more reliable and secure DApps with improved user experience and thus contribute to the overall health of a network.

Historical states limitations

To debug and trace transactions, you need to have historical states on the node. Full nodes of different protocols can store different amount of historical states. At the same time, archive nodes keep historical states for the entire chain.

The debug and trace APIs do not include the mempool. The txpool_* methods are a separate namespace with their own requirements — see What gives you mempool access.

Protocols with debug and trace APIs

Ethereum

To enable debug and trace APIs on your Ethereum node, you must have a paid plan and deploy the node as a Global Node.

Dedicated Nodes

To enable debug and trace APIs on your dedicated Ethereum node, you must have a paid plan. Dedicated Nodes can be deployed either as the Geth or Erigon client implementation for the full and archive modes respectively, however, they slightly differ from each other:

With a node running on Geth, only debug_*namespace is exposed.
With a node running on Erigon, both debug_* and trace_*namespaces are exposed.

Learn how to deploy your dedicated Ethereum node run on different clients with debug and trace APIs enabled. For the full list of the available debug and trace API methods, see:

Geth: debug namespace

Erigon: RPC implementation status

Polygon

To enable debug and trace APIs on your Polygon node, you must have a paid plan and deploy the node as a Global Node.

Dedicated Nodes

To enable debug and trace APIs on your dedicated Polygon node, you must have a paid plan. Dedicated Polygon nodes run the Bor client, which exposes the debug_* namespace. Bor does not implement the Erigon-only Parity trace_* namespace — see Polygon methods for the trace_* → debug_* migration.

BNB Smart Chain

To enable debug and trace APIs on your BNB Smart Chain node, you must have a paid plan and deploy the node as a Global Node.

Dedicated Nodes

To enable debug and trace APIs on your dedicated BNB Smart Chain node, you must have a paid plan. Dedicated Nodes can be deployed either as the Geth or Erigon client implementation for the full and archive modes respectively, however, they slightly differ from each other:

With a node running on Geth, only debug_*namespace is exposed.
With a node running on Erigon, both debug_* and trace_*namespaces are exposed.

For the full list of the available debug and trace API methods, see:

Geth: debug namespace

Erigon: RPC implementation status

Base

To enable debug and trace APIs on your Base node, you must have a paid plan and deploy the node as a Global Node.

Avalanche

To enable debug and trace APIs on your Avalanche node, you must have a paid plan and deploy the node in the archive mode. Your node will run the AvalancheGo client, which is the Go language implementation of an Avalanche node. Avalanche offers an API interface identical to Geth’s API, but with a limited set of services that include debug_trace*. For a full list of the Geth debug API methods, see the Debug namespace section of the Geth documentation. You can deploy a dedicated Avalanche node starting from a paid plan.

Arbitrum

To enable debug and trace APIs on your Arbitrum node, you must have a paid plan and deploy the node as a Global Node.

Dedicated Nodes

To enable debug and trace APIs on your dedicated Arbitrum node, you must have a paid plan.

Available methods

Both Global Nodes and dedicated Arbitrum nodes with debug and trace APIs enabled will expose the debug_* and arbtrace_* methods. Arbitrum uses the Nitro client (a Geth fork) and does not support the trace_* namespace. Instead, use the arbtrace_* methods for pre-Nitro blocks and debug_* methods for post-Nitro blocks. Blocks older than 22,207,815 were added to the chain before the Nitro migration and cannot be queried with Geth debug_* methods. Starting from block 22,207,815, Arbitrum migrated to Nitro which made Geth debug_* methods available for newer blocks. Use the following arbtrace_* methods for calling on blocks prior to 22,207,815:

arbtrace_block
arbtrace_call
arbtrace_callMany
arbtrace_filter
arbtrace_get
arbtrace_replayBlockTransactions
arbtrace_replayTransaction
arbtrace_transaction

The following debug_* methods are available for blocks from 22,207,815 onward:

debug_traceBlockByHash
debug_traceBlockByNumber
debug_traceTransaction
debug_traceCall

For the full list of the available debug_* namespace methods, see Geth documentation.

zkSync Era

To enable debug and trace APIs on your zkSync Era node, you must deploy an node in the archive mode. The node will expose the debug_* API methods. A debug and trace node for zkSync Era is available starting from a paid plan.

Optimism

To enable debug and trace APIs on your Optimism node, deploy a Global Node with the debug & trace APIs enabled. For the full list of the available debug and trace API methods, see Debug namespace.

Scroll

To enable debug and trace APIs on your Scroll node, deploy a Global Node with the debug & trace APIs enabled.

Ronin

To enable debug and trace APIs on your Ronin node, deploy a Global Node with the debug & trace APIs enabled.

Gnosis Chain

To enable debug and trace APIs on your Gnosis Chain node, you must deploy a Dedicated Node in the full or archive mode. The node will expose the debug_* and trace_* API methods. A dedicated debug and trace node for Gnosis Chain is available starting from a paid plan. Full-mode nodes run Nethermind; archive-mode nodes run Erigon. For the full list of available debug and trace API methods, see the Nethermind documentation for full-mode nodes, or the Erigon documentation for archive-mode nodes.

Fantom

To enable debug and trace APIs on your Fantom node, you must deploy a Dedicated Node in the full or archive mode. The node will expose the debug_* API methods. A dedicated debug and trace node for Fantom is available starting from a paid plan. For the full list of the available debug and trace API methods, see Debug namespace.

Hyperliquid

To enable debug and trace APIs on your Hyperliquid HyperEVM node, you must have a paid plan and deploy the node as a Global Node. Debug and trace APIs are available on both mainnet and testnet. The HyperEVM supports standard Ethereum debug and trace APIs, allowing you to debug smart contracts and trace transactions on Hyperliquid’s EVM-compatible layer. For the full list of the available debug and trace API methods, see Debug namespace.

Sonic

To enable debug and trace APIs on your Sonic node, you must have a paid plan and deploy the node as a Global Node. For the full list of the available debug and trace API methods, see Debug namespace.

Unichain

To enable debug and trace APIs on your Unichain node, you must have a paid plan and deploy the node as a Global Node. For the full list of the available debug and trace API methods, see Debug namespace.

Berachain

To enable debug and trace APIs on your Berachain node, you must have a paid plan and deploy the node as a Global Node. For the full list of the available debug and trace API methods, see Debug namespace.

Robinhood Chain

To enable debug and trace APIs on your Robinhood Chain node, you must have a paid plan and deploy the node as a Global Node. For the full list of the available debug and trace API methods, see Debug namespace.

Arc

To enable debug and trace APIs on your Arc node, you must have a paid plan and deploy the node as a Global Node. Arc runs the Reth client, which exposes both the debug_* and trace_* namespaces. For the full list of the available methods, see the Reth documentation for the debug namespace and the trace namespace.

Linea

To enable debug and trace APIs on your Linea node, you must have a paid plan and deploy the node as a Global Node. For the full list of the available debug and trace API methods, see Debug namespace.

Mantle

To enable debug and trace APIs on your Mantle node, you must have a paid plan and deploy the node as a Global Node. For the full list of the available debug and trace API methods, see Debug namespace.

Zora

To enable debug and trace APIs on your Zora node, you must have a paid plan and deploy the node as a Global Node. For the full list of the available debug and trace API methods, see Debug namespace.

Blast

To enable debug and trace APIs on your Blast node, you must have a paid plan and deploy the node as a Global Node. For the full list of the available debug and trace API methods, see Debug namespace.

Celo

To enable debug and trace APIs on your Celo node, you must have a paid plan and deploy the node as a Global Node. For the full list of the available debug and trace API methods, see Debug namespace.

Kaia

To enable debug and trace APIs on your Kaia node, you must have a paid plan and deploy the node as a Global Node. For the full list of the available debug and trace API methods, see Debug namespace.

opBNB

To enable debug and trace APIs on your opBNB node, you must have a paid plan and deploy the node as a Global Node. For the full list of the available debug and trace API methods, see Debug namespace.

World Chain

To enable debug and trace APIs on your World Chain node, you must have a paid plan and deploy the node as a Global Node. World Chain runs world-chain, an OP Stack execution client built on Reth, so it exposes both the debug_* and the trace_* namespaces. For the full list of the available methods, see the Reth documentation for the debug namespace and the trace namespace, and World Chain methods for per-method availability on Chainstack.

rpc_modules is not available on World Chain — it returns -32601 Method not found. Do not use it to decide which namespaces you have.

Stable

To enable debug and trace APIs on your Stable node, you must have a paid plan and deploy the node as a Global Node. The node will expose the debug_* API methods.

Stable does not serve the trace_* namespace. trace_block, trace_transaction, trace_call, trace_callMany, trace_filter, trace_get, trace_rawTransaction, trace_replayBlockTransactions, and trace_replayTransaction all return -32601. Use the debug_* equivalents instead — debug_traceBlockByNumber in place of trace_block, and debug_traceTransaction in place of trace_transaction, both with the callTracer. See Stable methods for the full per-method availability.

The available tracing methods are debug_traceTransaction, debug_traceBlockByNumber, debug_traceBlockByHash, and debug_traceCall. The Geth-era inspection methods — debug_storageRangeAt, debug_accountRange, debug_dumpBlock, and the rest — are not implemented; use eth_getStorageAt in place of debug_storageRangeAt.

Plasma

To enable debug and trace APIs on your Plasma node, you must have a paid plan and deploy the node as a Global Node. Plasma runs the Reth client, which exposes both the debug_* and the trace_* namespaces. For the full list of the available methods, see the Reth documentation for the debug namespace and the trace namespace.

Tempo

To enable debug and trace APIs on your Tempo node, you must have a paid plan and deploy the node as a Global Node. Tempo runs a Reth-based client and exposes both the debug_* and the trace_* namespaces. For the full list of the available methods, see the Reth documentation for the debug namespace and the trace namespace.

MegaETH

To enable debug and trace APIs on your MegaETH node, you must have a paid plan and deploy the node as a Global Node. MegaETH runs mega-reth, a Reth derivative, and exposes both the debug_* and the trace_* namespaces. For the full list of the available methods, see the Reth documentation for the debug namespace and the trace namespace.

Monad

To enable debug and trace APIs on your Monad node, you must have a paid plan and deploy the node as a Global Node. The node will expose the debug_* API methods. Monad does not serve the trace_* namespace — trace_block, trace_transaction, trace_call, and trace_filter all return -32601. Use debug_traceBlockByNumber and debug_traceTransaction instead.

Monad accepts a narrower set of tracers than the other EVM chains: callTracer and prestateTracer work, while 4byteTracer and noopTracer are rejected with -32602. See Available native tracers.

Cronos

To enable debug and trace APIs on your Cronos node, you must have a paid plan and deploy the node as a Global Node. The node will expose the debug_* API methods. Cronos does not serve the trace_* namespace. The available tracing methods are debug_traceTransaction, debug_traceBlockByNumber, debug_traceBlockByHash, and debug_traceCall; the Geth-era inspection methods such as debug_storageRangeAt are not implemented. Note that Cronos Mainnet archive nodes rate-limit debug_traceBlockByNumber to 10 RPS on all plans — see Cronos-specific limits.

Usage examples

You can debug and trace transactions by replaying them in the Ethereum Virtual Machine to get the execution details in the exact same way as they happened on the chain.

debug_traceBlockByNumber

Trace all transactions included in a block with debug_traceBlockByNumber in block 14,976,695:

curl 'YOUR_CHAINSTACK_ENDPOINT' \
-H 'Content-Type: application/json' \
-d '{"id": 1, "method": "debug_traceBlockByNumber", "params": ["0xE486B7", {"tracer": "callTracer"}]}'

where

0xE486B7 — the number of the block to get the traces of included transactions. For Geth, you need to provide the block number in hex.
YOUR_CHAINSTACK_ENDPOINT — your Chainstack node HTTPS endpoint. See View node access and credentials.

See a reverted transaction in the output:

"calls": [
  {
    "type": "DELEGATECALL",
    "from": "0x68b3465833fb72a70ecdf485e0e4c7bd8665fc45",
    "to": "0x68b3465833fb72a70ecdf485e0e4c7bd8665fc45",
    "gas": "0x38ed0",
    "gasUsed": "0x31147",
    "input": "0x472b43f30000000000000000000000000000000000000000000000000429d069189e00000000000000000000000000000000000000000000000000160d962fcdfd0bb02400000000000000000000000000000000000000000000000000000000000000800000000000000000000000000b5ec97d9a8a9941a28a88084a1f670c62bd8bf40000000000000000000000000000000000000000000000000000000000000002000000000000000000000000c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2000000000000000000000000b00b2e950d7ef8bdc49377c49676d1550deab982",
     "error": "execution reverted"

trace_block

Trace all transactions included in a block with trace_block in block 14,976,695:

curl 'YOUR_CHAINSTACK_ENDPOINT' \
-H 'Content-Type: application/json' \
-d '{"id": 1, "method": "trace_block", "params": ["14976695"]}'

where

14976695 — the number of the block to get the traces of included transactions
YOUR_CHAINSTACK_ENDPOINT — your Chainstack node HTTPS endpoint. See View node access and credentials.

See a reverted transaction in the output:

"action": {
  "from": "0x68b3465833fb72a70ecdf485e0e4c7bd8665fc45",
  "callType": "delegatecall",
  "gas": "0x38ed0",
  "input": "0x472b43f30000000000000000000000000000000000000000000000000429d069189e00000000000000000000000000000000000000000000000000160d962fcdfd0bb02400000000000000000000000000000000000000000000000000000000000000800000000000000000000000000b5ec97d9a8a9941a28a88084a1f670c62bd8bf40000000000000000000000000000000000000000000000000000000000000002000000000000000000000000c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2000000000000000000000000b00b2e950d7ef8bdc49377c49676d1550deab982",
  "to": "0x68b3465833fb72a70ecdf485e0e4c7bd8665fc45",
  "value": "0x429d069189e0000"
  },
  "blockHash": "0x03a83bf066e81498804f26caf5d49e47820f6a0e92fd1c9cb7dc3b87bf46cf0f",
  "blockNumber": 14976695,
  "error": "Reverted"

Advanced options on paid plans

Dedicated Nodes, archive nodes, debug & trace APIs are available starting from a paid plan.

​Overview

​Historical states limitations

​Protocols with debug and trace APIs

​Ethereum

​Dedicated Nodes

Geth: debug namespace

Erigon: RPC implementation status

​Polygon

​Dedicated Nodes

​BNB Smart Chain

​Dedicated Nodes

Geth: debug namespace

Erigon: RPC implementation status

​Base

​Avalanche

​Arbitrum

​Dedicated Nodes

​Available methods

​zkSync Era

​Optimism

​Scroll

​Ronin

​Gnosis Chain

​Fantom

​Hyperliquid

​Sonic

​Unichain

​Berachain

​Robinhood Chain

​Arc

​Linea

​Mantle

​Zora

​Blast

​Celo

​Kaia

​opBNB

​World Chain

​Stable

​Plasma

​Tempo

​MegaETH

​Monad

​Cronos

​Usage examples

​debug_traceBlockByNumber

​trace_block

​Advanced options on paid plans

Overview

Historical states limitations

Protocols with debug and trace APIs

Ethereum

Dedicated Nodes

Polygon

Dedicated Nodes

BNB Smart Chain

Dedicated Nodes

Base

Avalanche

Arbitrum

Dedicated Nodes

Available methods

zkSync Era

Optimism

Scroll

Ronin

Gnosis Chain

Fantom

Hyperliquid

Sonic

Unichain

Berachain

Robinhood Chain

Arc

Linea

Mantle

Zora

Blast

Celo

Kaia

opBNB

World Chain

Stable

Plasma

Tempo

MegaETH

Monad

Cronos

Usage examples

debug_traceBlockByNumber

trace_block

Advanced options on paid plans