# Trazas de transacciones: debug_traceTransaction y los endpoints de trazas de la Data API

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

## Dos formas de reconstruir un árbol de llamadas

Una traza de transacción es el árbol de llamadas reconstruido de una ejecución: qué contrato se llamó, con qué entrada, cuánto gas consumió y qué subllamadas realizó. BlockVectra lo ofrece mediante dos interfaces:

* **Métodos JSON-RPC `debug_trace`** (como `debug_traceTransaction`) — se ejecutan contra el nodo de la cadena mediante el endpoint JSON-RPC, por lo que pueden trazar el estado reciente que el nodo aún conserva.
* **Trazas de la Data API** — `GET /{chain}/transactions/{hash}/trace` y `GET /{chain}/blocks/{number}/traces` devuelven árboles de llamadas almacenados e indexados mediante REST.

Ambas usan la misma API key y se miden en CU según el peso del método (consulta los pesos más abajo). La elección depende de si necesitas una transacción o un bloque completo, de lo reciente que sea el objetivo y de si quieres recorrer un bloque completo sin paginación.

## Límites aplicables a los métodos debug\_trace

Las solicitudes `debug_trace` solo se aceptan para los métodos y trazadores que permite la política de métodos de la cadena:

* **Trazadores permitidos**: el parámetro `tracer` solo acepta los trazadores nativos integrados — `callTracer`, `flatCallTracer`, `prestateTracer`, `4byteTracer`, `noopTracer`, o puede omitirse para usar el registro estructurado predeterminado. Cualquier otro valor se rechaza con el error JSON-RPC `-32602 tracer not allowed` (sin facturación).
* **Tiempo máximo de trazado**: el parámetro `timeout` debe ser una duración válida de como máximo 30s; de lo contrario, la solicitud se rechaza con `-32602 trace timeout not allowed` (sin facturación).
* **Control de sincronización del nodo**: mientras el nodo de una cadena no esté sincronizado, todos los métodos excepto `eth_chainId` —incluidos los métodos `debug_trace`— devuelven `-32010` (sin facturación).
* **Ventana de estado**: `debug_traceCall`, `debug_traceBlockByNumber`, `debug_traceTransaction` y `debug_traceBlockByHash` apuntan a un bloque que debe estar dentro de la ventana de estado de la cadena. Un objetivo anterior a la ventana, o que use la etiqueta `safe`, `finalized` o `earliest`, devuelve `-32011` (sin facturación).
* **Consultas de hash y bloque**: un hash mal formado o desconocido devuelve `-32000 transaction not found` / `block not found`; un fallo temporal devuelve `-32603 upstream unavailable` (se puede reintentar). Sin facturación.
* **Política de métodos por cadena**: los métodos `debug_trace` que permite cada cadena se publican en la respuesta pública de `GET /v1/chains`. Léela en tiempo de ejecución en lugar de fijar una lista de métodos; las cadenas aparecen en [cadenas compatibles](https://docs.blockvectra.com/es/chains/) y la referencia de métodos está en la página de [métodos JSON-RPC](https://docs.blockvectra.com/es/api/json-rpc/methods/).

### Solicitar debug\_traceTransaction con callTracer

La siguiente llamada añade el parámetro `tracer` para solicitar un árbol de llamadas:

**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"])
```


## Qué ofrecen los endpoints de trazas de la Data API

La Data API devuelve árboles de llamadas almacenados para dos ámbitos. Ninguno usa paginación: `next_cursor` nunca está presente.

* `GET /{chain}/transactions/{hash}/trace` — el marco de llamada de una transacción, consultado por su hash.
* `GET /{chain}/blocks/{number}/traces` — un árbol de llamadas por transacción de un bloque, en orden de `tx_index`. Un bloque sin transacciones devuelve `data: []`.

La estructura de la respuesta es:

* `TxTraceEnvelope`: `data` es directamente un `CallFrame`, más `meta`.
* `BlockTracesEnvelope`: `data` es una matriz de `BlockTraceItem`, cada uno con `txHash` y `result` de tipo `CallFrame`, más `meta`.

Ambos endpoints de trazas devuelven el formato estándar Ethereum `callTracer`. Esto es una excepción a la codificación de seguridad numérica para importes de la Data API: en otros endpoints, un valor que puede superar `2^53` se serializa como cadena decimal; en estos dos endpoints, `value`, `gas` y `gasUsed` son cantidades hexadecimales con prefijo `0x`, no cadenas decimales. Cada `CallFrame` contiene `type`, `from`, `gas`, `gasUsed` e `input`; `type` es uno de `CALL`, `DELEGATECALL`, `STATICCALL`, `CREATE`, `CREATE2` o `SELFDESTRUCT`. `to` no está presente para el destino de un marco `CREATE`/`CREATE2`, y `value` no está presente en un marco `STATICCALL`. Los miembros opcionales son `output` (ausente cuando la llamada no devolvió datos), `error` (ausente en caso de éxito), `revertReason` (presente solo para una reversión `Error(string)`) y `calls` (subllamadas anidadas en orden de llamada). Se conservan los miembros adicionales del marco.

Para concretar la estructura, este es el esquema de campos de `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 ruta, obligatorio): identificador de cadena, el valor `chain` de una entrada en `GET /chains`. La coincidencia es exacta y distingue mayúsculas de minúsculas; no se aceptan alias ni Chain IDs numéricos.
* `{hash}` (parámetro de ruta, obligatorio para la traza de transacción): hash de transacción de 32 bytes, con prefijo `0x` opcional y dígitos en mayúsculas o minúsculas.
* `{number}` (parámetro de ruta, obligatorio para las trazas del bloque): altura de bloque no negativa.

### Cobertura y finalidad

* Ambos endpoints pertenecen a la capacidad `traces`. Una cadena que no la tenga devuelve `422 no_coverage`. Las cadenas que ofrecen este conjunto de datos se indican en la página de [cadenas compatibles](https://docs.blockvectra.com/es/chains/) y en el directorio de conjuntos de datos.
* Los datos de trazas pueden comenzar después que el resto del historial indexado de una cadena. `GET /chains` indica el límite en `coverage.traces_from_block`; una solicitud anterior a él, o dentro de un rango que no pudo trazarse, devuelve `422 no_coverage`.
* Para trazas de transacciones: si no se encuentra el hash, devuelve `404 not_found` (para una transacción recién enviada o minada, reintenta tras unos segundos antes de tratarlo como permanente); si el hash corresponde a un bloque superior a `as_of_block`, devuelve `409 not_indexed_yet` en su lugar.
* El endpoint de trazas de bloques recibe un número de bloque. Un `{number}` superior a `as_of_block` devuelve `409 not_indexed_yet` con `indexed_through`; un `{number}` igual o inferior a `as_of_block` se sirve inmediatamente.
* Un bloque reciente con transacciones pero sin datos de trazas todavía devuelve `503 unavailable` con una cabecera `Retry-After`.

### Solicitar una traza a la 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"]])
```


## Cuál usar

| Tarea habitual                                                                                   | Opción más adecuada                      | Motivo                                                                                                         |
| ------------------------------------------------------------------------------------------------ | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Reconstruir una transacción justo después de su inclusión                                        | `debug_traceTransaction`                 | Se ejecuta contra el estado actual del nodo; su disponibilidad depende de la política de métodos de la cadena. |
| Leer el árbol de llamadas almacenado de una transacción                                          | `GET /{chain}/transactions/{hash}/trace` | Devuelve directamente el `CallFrame` de la transacción mediante REST; se sirve hasta `as_of_block`.            |
| Leer todos los árboles de llamadas de un bloque en una solicitud                                 | `GET /{chain}/blocks/{number}/traces`    | Devuelve el bloque completo sin paginación, en orden de `tx_index`; se sirve hasta `as_of_block`.              |
| Trazar un estado que el nodo aún conserva pero que el conjunto de datos todavía no ha almacenado | Métodos `debug_trace`                    | La Data API sirve datos almacenados hasta `as_of_block`; el nodo puede responder para bloques aún no escritos. |

## CU por llamada

Cada método se factura según su peso en CU. Los siguientes pesos se leen de la API de planes de la plataforma:

**Peso en CU por llamada**

| Método | CU por llamada |
| --- | --- |
| `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 |

Las solicitudes rechazadas no se facturan. Consulta las reglas de facturación completas en [qué no se factura: códigos de error y reglas de facturación](https://docs.blockvectra.com/en/guides/billing-rules/).

## Próximos pasos

* [Consulta el Plan gratuito y los precios](https://blockvectra.com/es/pricing/#free) para comprobar qué incluye tu cuenta.
* [Inicia sesión en la consola](https://console.blockvectra.com/login/?next=%2Fkeys%2F) para crear una API key.