Migra de Enhanced Transactions a Parsed Events

¿Por qué migrar?

La API Enhanced Transactions es un producto heredado en modo de mantenimiento: sigue funcionando, pero no recibe nuevos tipos de analizadores ni funcionalidades. Su sucesor es Parsed Events, que decodifica instrucciones mediante el catálogo de IDL que también impulsa Parsed Streams. La diferencia está en cómo se decodifican las transacciones. Enhanced Transactions clasifica una transacción en uno de una lista fija de tipos de eventos (TRANSFER, SWAP, NFT_SALE, …) y devuelve un resumen predefinido para los tipos que conoce. Parsed Events decodifica cada instrucción con la IDL propia del programa —más de 3,600 programas— en argumentos y cuentas con nombre, y crea el resumen a partir de estos datos:

	Enhanced Transactions	Parsed Events
Modelo de decodificación	Tipos de eventos fijos, analizadores seleccionados	Catálogo de IDL, más de 3,600 programas
Detalle de las instrucciones	Solo el resumen del evento	Cada instrucción, argumentos y cuentas decodificados, incluidas las CPI
Programas sin analizador	Salida genérica `UNKNOWN`	Siempre se devuelven los datos sin procesar y las cuentas de cada instrucción
Interfaz de consulta	REST	REST y GraphQL
Paginación	Cursores de firma, con errores de búsqueda en tiempo de ejecución que debes manejar	`paginationToken` (los cursores de firma siguen disponibles)
Errores de programa decodificados	No	Sí (`decodedError`)
Carga útil de la transacción sin procesar	No	Opcional (`includeRawTransaction`)
Estado	Heredado, en modo de mantenimiento	Beta abierta, desarrollo activo

Parsed Events está en beta abierta en los planes de pago. La API aún puede cambiar antes de alcanzar la disponibilidad general. Mientras tanto, Enhanced Transactions seguirá funcionando, por lo que puedes migrar a tu propio ritmo.

Correspondencia de endpoints

Ambos métodos de Parsed Events son solicitudes POST a https://mainnet.helius-rpc.com y se autentican con el mismo parámetro de consulta api-key que ya usas:

Enhanced Transactions	Parsed Events
`POST /v0/transactions`	`POST /v1/parsed-events/transactions`
`GET /v0/addresses/{address}/transactions`	`POST /v1/parsed-events/transaction-history`

El endpoint del historial mueve todas las entradas de los parámetros de la cadena de consulta a un cuerpo JSON. Los cuerpos de las solicitudes rechazan los campos desconocidos, por lo que los errores tipográficos producen un error visible en lugar de ignorarse silenciosamente.

Antes y después

La misma tarea —obtener el historial analizado de una billetera— en ambas API:

const walletAddress = "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K";
const url = `https://mainnet.helius-rpc.com/v0/addresses/${walletAddress}/transactions?api-key=YOUR_API_KEY&limit=100&sort-order=desc`;

const response = await fetch(url);
const transactions = await response.json(); // flat array of enriched transactions

for (const tx of transactions) {
  console.log(tx.signature, tx.type, tx.description);
}

const url = "https://mainnet.helius-rpc.com/v1/parsed-events/transaction-history?api-key=YOUR_API_KEY";

const response = await fetch(url, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    address: "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K",
    limit: 100,
    sortOrder: "desc",
  }),
});
const page = await response.json(); // { data: [...], paginationToken }

for (const item of page.data) {
  if (item.parserStatus !== "OK") continue;
  console.log(item.signature, item.parsed.summary?.type, item.parsed.summary?.description);
}

Correspondencia de parámetros

Analizar transacciones

POST /v0/transactions → POST /v1/parsed-events/transactions

Anterior	Nuevo
`transactions` (cuerpo)	`transactions` — sin cambios
`commitment`	`commitment` — `confirmed` (predeterminado) o `finalized`; `processed` no es compatible

Nuevas opciones sin equivalente anterior: includeRawTransaction devuelve la carga útil original de la transacción de Solana junto con el resultado analizado.

Historial de transacciones

GET /v0/addresses/{address}/transactions → POST /v1/parsed-events/transaction-history. Cada parámetro de consulta se convierte en un campo del cuerpo JSON:

Parámetro de consulta anterior	Nuevo campo del cuerpo
`{address}` (ruta)	`address`
`limit`	`limit`
`before-signature`	`beforeSignature`
`after-signature`	`afterSignature`
`sort-order`	`sortOrder`
`commitment`	`commitment`
`gt-time`	`time.gt`
`gte-time`	`time.gte`
`lt-time`	`time.lt`
`lte-time`	`time.lte`
`gt-slot`	`slot.gt`
`gte-slot`	`slot.gte`
`lt-slot`	`slot.lt`
`lte-slot`	`slot.lte`

Durante el proceso cambian tres valores predeterminados:

limit tiene un valor predeterminado de 100 en lugar de 10.
commitment tiene como valor predeterminado confirmed en lugar de finalized; processed no es compatible.
sortOrder conserva los mismos valores asc/desc, con desc como valor predeterminado.

Para la paginación, usa preferentemente paginationToken de la respuesta anterior en lugar de beforeSignature. Consulta Simplifica la paginación más adelante. El parámetro anterior type no tiene un equivalente en Parsed Events: no hay un filtro de tipo de transacción en el servidor. Filtra en el cliente por parsed.summary.type (swap, transfer, add_liquidity, …) o por las propias instrucciones decodificadas, lo que ofrece más precisión que los tipos fijos anteriores. Para feeds en tiempo real específicos por tipo, Parsed Streams filtra en el servidor a nivel de instrucción.

Correspondencia de campos de respuesta

Enhanced Transactions devuelve un arreglo plano de transacciones enriquecidas. Parsed Events envuelve cada resultado en una estructura —{ signature, parserStatus, parsed }— y las respuestas del historial envuelven el arreglo en un objeto de página con paginationToken. Los campos analizados se corresponden de la siguiente manera:

Campo anterior	Campo nuevo
`description`	`parsed.summary.description` — `summary` es `null` cuando no corresponde ningún resumen a nivel de transacción
`type` (`TRANSFER`, `SWAP`, …)	`parsed.summary.type` (`transfer`, `swap`, …) — un conjunto más pequeño; el detalle por instrucción se movió a `parsed.instructions[]`
`source` (`SYSTEM_PROGRAM`, `JUPITER`, …)	`parsed.summary.parsedData.protocol`, o por instrucción como `instructions[].programName`
`events` (`events.swap`, `events.nft`, …)	`parsed.summary.parsedData` — carga útil estructurada con claves según el tipo de resumen
`fee` / `feePayer`	`parsed.fee` / `parsed.feePayer` — sin cambios
`signature`	`signature` (a nivel de la estructura envolvente)
`slot`	`parsed.slot`
`timestamp`	`parsed.blockTime`
`transactionError`	`parsed.error`, además de `parsed.decodedError` con el nombre de error propio del programa cuando los metadatos están disponibles
`nativeTransfers`	`parsed.nativeTransfers` — misma estructura (`fromUserAccount`, `toUserAccount`, `amount` en lamports)
`tokenTransfers`	`parsed.tokenTransfers` — los mismos campos de cuenta, pero `tokenAmount` (decimal previamente escalado) se convierte en `rawTokenAmount` (entero sin procesar) más `decimals`

Y el cambio más importante es un campo nuevo sin equivalente anterior: parsed.instructions[] contiene todas las instrucciones de nivel superior e internas en orden de ejecución, con decoded.args y decoded.accounts nombrados a partir de la IDL del programa. Mientras que Enhanced Transactions te proporcionaba un resumen de evento por transacción, Parsed Events te proporciona el resumen y la lista completa de instrucciones decodificadas. Consulta Respuesta analizada para conocer todos los campos.

Pasos de migración

Swap the endpoints

Dirige las llamadas de Parse Transactions a POST /v1/parsed-events/transactions y las llamadas del historial a POST /v1/parsed-events/transaction-history. Usa el mismo host y el mismo parámetro de consulta api-key. Las solicitudes del historial cambian de GET con parámetros de consulta a POST con un cuerpo JSON. Mueve cada parámetro según la correspondencia anterior.

Update the response handling

Desenvuelve la nueva estructura: comprueba parserStatus === "OK" y luego lee los campos de parsed en lugar del nivel superior. Cambia el nombre de timestamp a blockTime, lee description y type desde summary (comprobando que no sea null) y divide rawTokenAmount entre 10^decimals donde el código anterior leía tokenAmount.

Replace type filtering

Donde el código anterior pasaba type=..., filtra los elementos devueltos en el cliente por parsed.summary.type o por parsed.instructions[]. Por ejemplo, “instrucciones donde programId es Jupiter y instructionName es route” reemplaza type=SWAP con algo que realmente puedes verificar. Si el filtro de tipo servía para impulsar un feed en tiempo real, mueve ese consumidor a Parsed Streams, que filtra en el servidor a nivel de instrucción.

Simplify pagination

Reemplaza el bucle del cursor before-signature por paginationToken:

let paginationToken = null;
const results = [];

do {
  const response = await fetch("https://mainnet.helius-rpc.com/v1/parsed-events/transaction-history?api-key=YOUR_API_KEY", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      address: "YOUR_ADDRESS_HERE",
      limit: 100,
      ...(paginationToken && { paginationToken }),
    }),
  });
  const page = await response.json();
  results.push(...page.data);
  paginationToken = page.paginationToken;
} while (paginationToken);

El bucle termina cuando falta paginationToken. Los errores anteriores de búsqueda en tiempo de ejecución (“No se pudieron encontrar eventos dentro del período de búsqueda”) y su manejo de firmas de continuación desaparecen por completo. Elimina ese código.

Verify against the old output

Para una dirección de muestra, obtén la misma página de ambas API y compara los conjuntos de firmas, las comisiones y los importes de las transferencias. Luego, implementa los cambios y elimina la ruta de código anterior. Enhanced Transactions seguirá funcionando durante la migración: no hay una fecha límite obligatoria.

Diferencias de comportamiento que debes revisar

Valores predeterminados del nivel de compromiso. El historial usa confirmed de forma predeterminada, mientras que el endpoint anterior usaba finalized. Pasa commitment: "finalized" explícitamente si tu canalización depende de la finalidad. processed no es compatible.
Errores por elemento. Una firma que no puede analizarse ya no hace que falle la solicitud. Se devuelve como un elemento con parserStatus: "ERROR" y un parserError. Maneja el error por elemento en lugar de hacerlo por solicitud.
Cobertura del resumen. summary es null para las transacciones sin una acción reconocida a nivel de transacción. La API anterior devolvía type: "UNKNOWN" en ese caso. La nueva API sigue proporcionándote todas las instrucciones decodificadas para que puedas trabajar con ellas.
Acceso. Parsed Events está en beta abierta en los planes de pago y la API aún puede cambiar antes de alcanzar la disponibilidad general.

Deja que un agente de IA realice la migración

Si usas Claude Code, Cursor u otro agente de programación, pega el siguiente prompt en la sesión del agente de tu repositorio. Este busca los lugares donde se llama a Enhanced Transactions y los reescribe.

Migrate this codebase from the Helius Enhanced Transactions API to the Helius
Parsed Events API.

## Background

Parsed Events is the successor to Enhanced Transactions. Same host
(https://mainnet.helius-rpc.com) and api-key query parameter; new paths,
JSON bodies, and response shapes.
Docs: https://www.helius.dev/docs/parsed-events/quickstart.md and
https://www.helius.dev/docs/parsed-events/parsed-response.md

## Step 1: Find the old call sites

Search for:
- POST requests to /v0/transactions
- GET requests to /v0/addresses/<address>/transactions (any query parameters)
- Pagination loops using before-signature / after-signature cursors, and
  handlers for the "Failed to find events within the search period" error

## Step 2: Rewrite each call site

Parse transactions:
- POST /v0/transactions -> POST /v1/parsed-events/transactions
- Body keeps { transactions: [...] }; optionally add commitment
  ("confirmed" default or "finalized") and includeRawTransaction.

Transaction history:
- GET /v0/addresses/{address}/transactions?... ->
  POST /v1/parsed-events/transaction-history with a JSON body.
- Parameter mapping (query -> body): address path segment -> address;
  limit -> limit (default is now 100, not 10);
  before-signature -> beforeSignature (prefer paginationToken, see below);
  after-signature -> afterSignature; sort-order -> sortOrder;
  commitment -> commitment (default is now "confirmed", not "finalized";
  "processed" unsupported);
  gt-time/gte-time/lt-time/lte-time -> time.gt/.gte/.lt/.lte;
  gt-slot/gte-slot/lt-slot/lte-slot -> slot.gt/.gte/.lt/.lte.
- type=... has no server-side equivalent: filter returned items client-side
  on parsed.summary?.type (lowercase: "swap", "transfer", ...) or on
  parsed.instructions[] (programId / instructionName).

Response shape changes:
- Each item is now { signature, parserStatus, parsed } — check
  parserStatus === "OK" and read fields from parsed.
- Field renames: timestamp -> parsed.blockTime; description ->
  parsed.summary?.description; type -> parsed.summary?.type;
  source -> parsed.summary?.parsedData?.protocol or
  parsed.instructions[].programName; events -> parsed.summary?.parsedData.
- nativeTransfers: unchanged shape under parsed.nativeTransfers.
- tokenTransfers: tokenAmount (pre-scaled decimal) is replaced by
  rawTokenAmount (raw integer string/number) plus decimals — divide by
  10**decimals where the old amount was used.
- History responses wrap results as { data, paginationToken }. Loop while
  paginationToken is present, passing it back in the next request body.
  Delete continuation-signature error handling for the old runtime type
  search — it no longer exists.

## Step 3: Constraints and cleanup

- Keep the same Helius API key and host; only paths, methods, bodies, and
  response handling change.
- Never hardcode an API key; keep reading it from the existing config or
  environment variable.
- Preserve the surrounding code style and error handling conventions.
- Leave Enhanced Transaction webhook payload handling unchanged — this
  migration covers only the /v0/transactions and /v0/addresses REST calls.

## Step 4: Verify

- Run the project's type checks and tests.
- Do NOT make any API calls yourself. Instead, write a standalone script
  (e.g. scripts/verify-parsed-events-migration.mjs) that fetches one page of
  history for an address from both APIs — the old
  GET /v0/addresses/{address}/transactions and the new
  POST /v1/parsed-events/transaction-history — and prints whether the
  signature sets, fees, and native transfer amounts match, listing any
  differences. Read the API key from an environment variable and the address
  from a CLI argument.
- Tell the user how to run it, for example:
  HELIUS_API_KEY=... node scripts/verify-parsed-events-migration.mjs <address>
- Summarize every call site changed and flag any you were unsure about.

El prompt es autosuficiente: el agente no necesita acceder a esta página. Para consultar documentación preparada para agentes, búsquedas MCP y habilidades, consulta Helius para agentes de IA.

Próximos pasos

Parsed Events Quickstart

Analiza tu primera transacción, obtén el historial de una dirección y pagina los resultados.

Parsed Response

Referencia de campos para transacciones, transferencias e instrucciones analizadas.

Parsed Streams

La misma decodificación en tiempo real mediante WebSocket, con filtrado en el servidor.

getTransactionsForAddress

Historial de transacciones sin procesar con compatibilidad con cuentas de tokens y filtros en el servidor.

Comienza aquí

Datos en tiempo real

Trading de baja latencia

Datos históricos y de billeteras

Guías de métodos RPC

Preparación para producción

Uso de Orb

Otras guías prácticas

Migra de Enhanced Transactions a Parsed Events

¿Por qué migrar?

Correspondencia de endpoints

Antes y después

Correspondencia de parámetros

Analizar transacciones

Historial de transacciones

Correspondencia de campos de respuesta

Pasos de migración

Diferencias de comportamiento que debes revisar

Deja que un agente de IA realice la migración

Próximos pasos

Parsed Events Quickstart

Parsed Response

Parsed Streams

getTransactionsForAddress

​¿Por qué migrar?

​Correspondencia de endpoints

​Antes y después

​Correspondencia de parámetros

​Analizar transacciones

​Historial de transacciones

​Correspondencia de campos de respuesta

​Pasos de migración

​Diferencias de comportamiento que debes revisar

​Deja que un agente de IA realice la migración

​Próximos pasos

Parsed Events Quickstart

Parsed Response

Parsed Streams

getTransactionsForAddress

¿Por qué migrar?

Correspondencia de endpoints

Antes y después

Correspondencia de parámetros

Analizar transacciones

Historial de transacciones

Correspondencia de campos de respuesta

Pasos de migración

Diferencias de comportamiento que debes revisar

Deja que un agente de IA realice la migración

Próximos pasos