# Traces de transações: debug_traceTransaction e endpoints de trace da Data API

> Source: https://docs.blockvectra.com/pt-br/guides/transaction-traces/

## Duas formas de reconstruir uma árvore de chamadas

Um trace de transação é a árvore de chamadas reconstruída de uma execução: qual contrato foi chamado, com qual entrada, quanto gas consumiu e quais subchamadas realizou. A BlockVectra o disponibiliza por meio de duas superfícies:

* **Métodos `debug_trace` de JSON-RPC** (como `debug_traceTransaction`) — executados no nó da rede via endpoint JSON-RPC, permitindo rastrear o estado recente que o nó ainda mantém.
* **Traces da Data API** — `GET /{chain}/transactions/{hash}/trace` e `GET /{chain}/blocks/{number}/traces` retornam árvores de chamadas armazenadas e indexadas via REST.

Ambos usam a mesma API key e são medidos em CU pelo peso do método (consulte os pesos abaixo). A escolha adequada depende se você precisa de uma única transação ou de um bloco inteiro, de quão recente é o alvo e se deseja percorrer um bloco completo sem paginação.

## Limites aplicáveis aos métodos debug\_trace

As requisições `debug_trace` são aceitas apenas para métodos e rastreadores permitidos pela política de métodos da rede:

* **Rastreadores permitidos**: o parâmetro `tracer` aceita apenas os rastreadores nativos integrados — `callTracer`, `flatCallTracer`, `prestateTracer`, `4byteTracer`, `noopTracer`, ou a omissão dele para usar o registrador de estruturas padrão. Qualquer outro valor é rejeitado com o erro JSON-RPC `-32602 tracer not allowed` (não cobrado).
* **Tempo limite de trace**: o parâmetro `timeout` deve ser uma duração válida e de no máximo 30s; caso contrário, a requisição será rejeitada com `-32602 trace timeout not allowed` (não cobrado).
* **Proteção de sincronização do nó**: enquanto o nó de uma rede não estiver sincronizado, todos os métodos exceto `eth_chainId` — incluindo os métodos `debug_trace` — retornam `-32010` (não cobrado).
* **Janela de estado**: `debug_traceCall`, `debug_traceBlockByNumber`, `debug_traceTransaction` e `debug_traceBlockByHash` têm como alvo um bloco que deve estar dentro da janela de estado da rede. Um alvo anterior à janela, ou que use as tags `safe`, `finalized` ou `earliest`, retorna `-32011` (não cobrado).
* **Consultas de hash e bloco**: um hash malformado ou desconhecido retorna `-32000 transaction not found` / `block not found`; uma falha temporária retorna `-32603 upstream unavailable` (repetível). Não cobrado.
* **Política de métodos por rede**: quais métodos `debug_trace` uma rede permite é publicado pela resposta pública de `GET /v1/chains`. Leia-a em tempo de execução em vez de fixar uma lista de métodos no código; as redes estão listadas em [Redes suportadas](https://docs.blockvectra.com/en/chains/), e a referência de métodos está na página de [métodos JSON-RPC](https://docs.blockvectra.com/en/api/json-rpc/methods/).

### Requisitando debug\_traceTransaction com callTracer

A chamada abaixo adiciona o parâmetro `tracer` para solicitar uma árvore de chamadas:

**cURL**

```bash
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" }
    ]
  }'
```


  **TypeScript**

```ts
const RPC_ENDPOINT = "https://api.blockvectra.com/v1/robinhood_mainnet";

const res = await fetch(RPC_ENDPOINT, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.BLOCKVECTRA_API_KEY!,
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "debug_traceTransaction",
    params: [
      "0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd",
      { tracer: "callTracer" },
    ],
  }),
});

const body = (await res.json()) as {
  result?: unknown;
  error?: { code: number; message: string };
};

if (body.error) {
  throw new Error(`debug_traceTransaction error ${body.error.code}: ${body.error.message}`);
}
console.log(body.result);

// npx tsx example.mts
```


  **Python**

```python
import os
import requests

RPC_ENDPOINT = "https://api.blockvectra.com/v1/robinhood_mainnet"

res = requests.post(
    RPC_ENDPOINT,
    headers={
        "Content-Type": "application/json",
        "x-api-key": os.environ["BLOCKVECTRA_API_KEY"],
    },
    json={
        "jsonrpc": "2.0",
        "id": 1,
        "method": "debug_traceTransaction",
        "params": [
            "0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd",
            {"tracer": "callTracer"},
        ],
    },
)
res.raise_for_status()
body = res.json()

if "error" in body:
    err = body["error"]
    raise RuntimeError(f"debug_traceTransaction error {err.get('code')}: {err.get('message')}")
print(body["result"])
```


## O que os endpoints de trace da Data API oferecem

A Data API retorna árvores de chamadas armazenadas para dois escopos. Nenhum deles é paginado: `next_cursor` nunca está presente.

* `GET /{chain}/transactions/{hash}/trace` — o quadro de chamada de uma transação, consultado pelo hash da transação.
* `GET /{chain}/blocks/{number}/traces` — uma árvore de chamadas por transação em um bloco, em ordem de `tx_index`. Um bloco sem transações retorna `data: []`.

O envelope de resposta é:

* `TxTraceEnvelope`: `data` é diretamente um `CallFrame`, mais `meta`.
* `BlockTracesEnvelope`: `data` é um array de `BlockTraceItem`, cada um com `txHash` e o `CallFrame` em `result`, mais `meta`.

Ambos os endpoints de trace retornam o formato padrão `callTracer` do Ethereum. Esta é uma exceção à codificação segura de valores monetários da Data API: em outros locais, valores que podem exceder `2^53` são serializados como strings decimais; nesses dois endpoints, `value`, `gas` e `gasUsed` são quantidades hexadecimais com prefixo `0x`, e não strings decimais. Cada `CallFrame` contém `type`, `from`, `gas`, `gasUsed` e `input`; `type` é um entre `CALL`, `DELEGATECALL`, `STATICCALL`, `CREATE`, `CREATE2` ou `SELFDESTRUCT`. `to` fica ausente para o destino de um quadro `CREATE`/`CREATE2`, e `value` fica ausente para um quadro `STATICCALL`. Membros opcionais são `output` (ausente quando a chamada não retornou dados), `error` (ausente em caso de sucesso), `revertReason` (presente apenas para reversões `Error(string)`) e `calls` (subchamadas aninhadas na ordem de chamada). Membros adicionais do quadro são preservados.

Para tornar o formato concreto, aqui está a estrutura dos campos do `CallFrame`:

```jsonc
{
  "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
}
```

### Parâmetros

* `{chain}` (parâmetro de caminho, obrigatório): identificador da rede, o valor `chain` de uma entrada em `GET /chains`. A correspondência é exata e diferencia maiúsculas de minúsculas; aliases e IDs numéricos de rede não são aceitos.
* `{hash}` (parâmetro de caminho, obrigatório para o trace de transação): hash de transação de 32 bytes, prefixo `0x` opcional, em qualquer formatação de maiúsculas/minúsculas.
* `{number}` (parâmetro de caminho, obrigatório para os traces de bloco): altura de bloco não negativa.

### Cobertura e finalidade

* Ambos os endpoints pertencem à capacidade `traces`. Uma rede sem essa capacidade retorna `422 no_coverage`. Redes que fornecem este conjunto de dados estão sujeitas à página de [Redes suportadas](https://docs.blockvectra.com/en/chains/) e ao diretório de conjuntos de dados.
* Dados de trace podem iniciar posteriormente em relação ao restante do histórico indexado de uma rede. `GET /chains` informa esse limite como `coverage.traces_from_block`; uma requisição anterior a ele, ou dentro de um intervalo que não pôde ser rastreado, retorna `422 no_coverage`.
* Para traces de transações: se o hash não for encontrado, ele retorna `404 not_found` (para uma transação recém-enviada ou minerada, tente novamente após alguns segundos antes de tratar isso como permanente); se o hash for resolvido para um bloco superior a `as_of_block`, ele retorna `409 not_indexed_yet`.
* O endpoint de traces de bloco recebe um número de bloco. Um `{number}` acima de `as_of_block` retorna `409 not_indexed_yet` com `indexed_through`; um `{number}` igual ou inferior a `as_of_block` é atendido imediatamente.
* Um bloco recente com transações, mas ainda sem dados de trace, retorna `503 unavailable` com um cabeçalho `Retry-After`.

### Requisitando um trace da Data API

**cURL**

```bash
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"
```


  **TypeScript**

```ts
const hash = "0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd";

const txRes = await fetch(
  `https://api.blockvectra.com/v1/data/robinhood_mainnet/transactions/${hash}/trace`,
  { headers: { "x-api-key": process.env.BLOCKVECTRA_API_KEY! } },
);
const txBody = await txRes.json();
console.log(txBody.data, txBody.meta);

const blockRes = await fetch("https://api.blockvectra.com/v1/data/robinhood_mainnet/blocks/79900000/traces", {
  headers: { "x-api-key": process.env.BLOCKVECTRA_API_KEY! },
});
const blockBody = await blockRes.json();
console.log(blockBody.data.map((item: { txHash: string }) => item.txHash));

// npx tsx example.mts
```


  **Python**

```python
import os
import requests

hash_ = "0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd"
headers = {"x-api-key": os.environ["BLOCKVECTRA_API_KEY"]}

tx = requests.get(
    f"https://api.blockvectra.com/v1/data/robinhood_mainnet/transactions/{hash_}/trace",
    headers=headers,
)
tx.raise_for_status()
tx_body = tx.json()
print(tx_body["data"], tx_body["meta"])

block = requests.get(
    "https://api.blockvectra.com/v1/data/robinhood_mainnet/blocks/79900000/traces",
    headers=headers,
)
block.raise_for_status()
block_body = block.json()
print([item["txHash"] for item in block_body["data"]])
```


## Qual deles utilizar

| Tarefa típica                                                                          | Mais indicado                            | Motivo                                                                                                     |
| -------------------------------------------------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Reconstruir uma única transação logo após ela ser minerada                             | `debug_traceTransaction`                 | É executado no estado atual do nó; a disponibilidade segue a política de métodos da rede.                  |
| Ler a árvore de chamadas armazenada de uma única transação                             | `GET /{chain}/transactions/{hash}/trace` | Retorna o `CallFrame` da transação diretamente via REST; atendido até `as_of_block`.                       |
| Ler todas as árvores de chamadas de um bloco em uma única requisição                   | `GET /{chain}/blocks/{number}/traces`    | Retorna o bloco inteiro sem paginação, em ordem de `tx_index`; atendido até `as_of_block`.                 |
| Rastrear estado que o nó ainda mantém, mas que o conjunto de dados ainda não armazenou | Métodos `debug_trace`                    | A Data API fornece dados armazenados até `as_of_block`; o nó pode responder por blocos ainda não gravados. |

## CU por chamada

Todo método é cobrado pelo seu peso em CU. Os pesos abaixo são lidos a partir da API de planos da plataforma:

**Peso em CU por chamada**

| Método | CU por chamada |
| --- | --- |
| `debug_traceBlockByHash` | 100 |
| `debug_traceBlockByNumber` | 100 |
| `debug_traceCall` | 100 |
| `debug_traceTransaction` | 100 |
| `trace_block` | 100 |
| `trace_call` | 100 |
| `trace_get` | 100 |
| `trace_replayTransaction` | 100 |
| `trace_transaction` | 100 |
| `data.block_traces` | 200 |
| `data.transaction_trace` | 200 |

Requisições rejeitadas não são cobradas. Para obter as regras de cobrança completas, consulte [O que não é cobrado: códigos de erro e regras de cobrança](https://docs.blockvectra.com/en/guides/billing-rules/).

## Próximos passos

* [Consulte o plano gratuito e os preços](https://blockvectra.com/en/pricing/#free) para verificar o que sua conta inclui.
* [Entre no console](https://console.blockvectra.com/login/?next=%2Fkeys%2F) para criar uma API key.