Transaction traces: debug_traceTransaction and the Data API trace endpoints

Two ways to reconstruct a call tree

A transaction trace is the reconstructed call tree of an execution: which contract was called, with which input, how much gas it consumed, and which sub-calls it made. BlockVectra exposes it through two surfaces:

• JSON-RPC debug_trace methods (such as debug_traceTransaction) — run against the chain's node through the JSON-RPC endpoint, so they can trace recent state the node still has.
• Data API traces — GET /{chain}/transactions/{hash}/trace and GET /{chain}/blocks/{number}/traces return stored, indexed call trees over REST.

Both use the same API key and are metered in CU by method weight (see the weights below). Which one fits depends on whether you need a single transaction or a whole block, how recent the target is, and whether you want to walk a full block without pagination.

Limits that apply to debug_trace methods

debug_trace requests are accepted only for methods and tracers the chain's method policy allows:

• Allowed tracers: the tracer parameter accepts only the built-in native tracers — callTracer, flatCallTracer, prestateTracer, 4byteTracer, noopTracer, or omitting it to use the default struct logger. Any other value is rejected with JSON-RPC error -32602 tracer not allowed (not billed).
• Trace timeout: the timeout parameter must be a valid duration and at most 30s; otherwise the request is rejected with -32602 trace timeout not allowed (not billed).
• Node sync guard: while a chain's node is not synced, every method except eth_chainId — including debug_trace methods — returns -32010 (not billed).
• State window: debug_traceCall, debug_traceBlockByNumber, debug_traceTransaction, and debug_traceBlockByHash target a block that must be inside the chain's state window. A target earlier than the window, or one that uses the safe, finalized, or earliest tag, returns -32011 (not billed).
• Hash and block lookups: a malformed or unknown hash returns -32000 transaction not found / block not found; a temporary failure returns -32603 upstream unavailable (retryable). Not billed.
• Per-chain method policy: which debug_trace methods a chain allows is published by the public GET /v1/chains response. Read it at runtime instead of hardcoding a method list; chains are listed on Supported Chains, and the method reference is in the JSON-RPC methods page.

Requesting debug_traceTransaction with callTracer

The call below adds the tracer parameter to request a call tree:

export BLOCKVECTRA_API_KEY=rgw_your_api_key

# Add "tracer" to request a call tree with one of the allowed native tracers.
curl -s "https://api.blockvectra.com/v1/robinhood_mainnet" \
  -H 'Content-Type: application/json' \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "debug_traceTransaction",
    "params": [
      "0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd",
      { "tracer": "callTracer" }
    ]
  }'

What the Data API trace endpoints provide

The Data API returns stored call trees for two scopes. Neither is paginated: next_cursor is never present.

• GET /{chain}/transactions/{hash}/trace — the call frame of one transaction, looked up by transaction hash.
• GET /{chain}/blocks/{number}/traces — one call tree per transaction in a block, in tx_index order. A block with no transactions returns data: [].

The response envelope is:

• TxTraceEnvelope: data is a CallFrame directly, plus meta.
• BlockTracesEnvelope: data is an array of BlockTraceItem, each with txHash and the result CallFrame, plus meta.

Both trace endpoints return the standard Ethereum callTracer format. This is an exception to the Data API's money-safety encoding: elsewhere, a value that can exceed 2^53 is serialized as a decimal string; on these two endpoints, value, gas, and gasUsed are 0x-prefixed hex quantities, not decimal strings. Every CallFrame carries type, from, gas, gasUsed, and input; type is one of CALL, DELEGATECALL, STATICCALL, CREATE, CREATE2, or SELFDESTRUCT. to is absent for a CREATE/CREATE2 frame's target, and value is absent for a STATICCALL frame. Optional members are output (absent when the call returned no data), error (absent on success), revertReason (present only for an Error(string) revert), and calls (nested sub-calls in call order). Additional members of the frame are preserved.

To make the shape concrete, here is the CallFrame field skeleton:

{
  "type": "CALL | DELEGATECALL | STATICCALL | CREATE | CREATE2 | SELFDESTRUCT",
  "from": "0x…",                      // 20-byte address
  "to": "0x…",                        // absent for a CREATE/CREATE2 target
  "value": "0x…",                     // 0x-prefixed hex quantity; absent for STATICCALL
  "gas": "0x…",                       // 0x-prefixed hex quantity
  "gasUsed": "0x…",                   // 0x-prefixed hex quantity
  "input": "0x…",
  "output": "0x…",                    // absent when the call returned no data
  "error": "…",                       // absent on success
  "revertReason": "…",                // absent unless the call reverted with Error(string)
  "calls": []                         // nested sub-calls in call order; absent for a leaf frame
}

Parameters

• {chain} (path parameter, required): chain identifier, the chain value of an entry in GET /chains. Matching is exact and case-sensitive; aliases and numeric chain IDs are not accepted.
• {hash} (path parameter, required for the transaction trace): 32-byte transaction hash, 0x prefix optional, either digit case.
• {number} (path parameter, required for the block traces): non-negative block height.

Coverage and finality

• Both endpoints belong to the traces capability. A chain without it returns 422 no_coverage. Chains that provide this dataset are subject to the Supported Chains page and the dataset directory.
• Trace data can start later than the rest of a chain's indexed history. GET /chains reports the boundary as coverage.traces_from_block; a request before it, or inside a range that could not be traced, returns 422 no_coverage.
• For transaction traces: if the hash is not found, it returns 404 not_found (for a just-submitted or mined transaction, retry after a few seconds before treating this as permanent); if the hash resolves to a block higher than as_of_block, it returns 409 not_indexed_yet instead.
• The block traces endpoint takes a block number. A {number} above as_of_block returns 409 not_indexed_yet with indexed_through; a {number} at or below as_of_block is served immediately.
• A recent block with transactions but no trace data yet returns 503 unavailable with a Retry-After header.

Requesting a trace from the Data API

export BLOCKVECTRA_API_KEY=rgw_your_api_key

# One transaction's call frame.
curl -s "https://api.blockvectra.com/v1/data/robinhood_mainnet/transactions/0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd/trace" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"

# One call tree per transaction in a block.
curl -s "https://api.blockvectra.com/v1/data/robinhood_mainnet/blocks/79900000/traces" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"

Which one to use

CU per call

Every method is billed by its CU weight. The weights below are read from the platform plans API:

Rejected requests are not billed. For the full billing rules, see What is not billed: error codes and billing rules.

Next steps

• See the free plan and pricing to check what your account includes.
• Log in to the console to create an API key.