Migre de Enhanced Transactions para Parsed Events

Por que migrar?

A API Enhanced Transactions é um produto legado em modo de manutenção: ainda funciona, mas não está recebendo novos tipos de parser ou desenvolvimento de funcionalidades. Seu sucessor é o Parsed Events, que decodifica instruções através do catálogo IDL que também dá suporte ao Parsed Streams. A diferença está em como as transações são decodificadas. Enhanced Transactions classifica uma transação em uma de uma lista fixa de tipos de eventos (TRANSFER, SWAP, NFT_SALE, …) e retorna um resumo pré-construído para os tipos que conhece. Parsed Events decodifica toda instrução contra o próprio IDL do programa — mais de 3.600 programas — em argumentos nomeados e contas nomeadas, e constrói o resumo sobre isso:

	Enhanced Transactions	Parsed Events
Modelo de decodificação	Tipos de eventos fixos, parsers curados	Catálogo IDL, mais de 3.600 programas
Detalhe da instrução	Resumo de evento apenas	Toda instrução, argumentos e contas decodificados, CPIs incluídos
Programas sem um parser	Saída genérica `UNKNOWN`	Dados brutos e contas sempre retornados por instrução
Interface de consulta	REST	REST e GraphQL
Paginação	Cursores de assinatura, erros de busca em tempo de execução para lidar	`paginationToken` (cursores de assinatura ainda disponíveis)
Erros de programa decodificados	Não	Sim (`decodedError`)
Payload bruto da transação	Não	Opcional (`includeRawTransaction`)
Status	Legado, modo de manutenção	Beta aberto, desenvolvimento ativo

Parsed Events está em beta aberto em planos pagos. A API ainda pode mudar antes da disponibilidade geral; Enhanced Transactions continua funcionando enquanto isso, para que você possa migrar no seu próprio ritmo.

Mapeamento de endpoint

Ambos os métodos de Parsed Events são solicitações POST para https://mainnet.helius-rpc.com, autenticados com o mesmo parâmetro de consulta api-key que você já usa:

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

O endpoint de histórico move todas as entradas dos parâmetros de string de consulta para um corpo JSON. Corpos de solicitação rejeitam campos desconhecidos, de modo que erros de digitação falham de maneira explícita ao invés de serem ignorados silenciosamente.

Antes e depois

A mesma tarefa — buscar o histórico analisado de uma carteira — em ambas as APIs:

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);
}

Mapeamento de parâmetros

Analisar Transações

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

Antigo	Novo
`transactions` (corpo)	`transactions` — inalterado
`commitment`	`commitment` — `confirmed` (padrão) ou `finalized`; `processed` não é suportado

Novas opções sem equivalente antigo: includeRawTransaction retorna o payload original da transação Solana juntamente com o resultado analisado.

Histórico de Transações

GET /v0/addresses/{address}/transactions → POST /v1/parsed-events/transaction-history. Cada parâmetro de consulta se torna um campo de corpo JSON:

Antigo parâmetro de consulta	Novo campo do corpo
`{address}` (caminho)	`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`

Três padrões mudam ao longo do caminho:

limit tem padrão 100 ao invés de 10.
commitment tem padrão confirmed ao invés de finalized; processed não é suportado.
sortOrder mantém os mesmos valores asc/desc com desc como padrão.

Para paginação, prefira paginationToken da resposta anterior em vez de beforeSignature — veja Simplificar paginação abaixo. O antigo parâmetro type não tem equivalente em Parsed Events — não há filtro de tipo de transação no lado do servidor. Filtre no lado do cliente em parsed.summary.type (swap, transfer, add_liquidity, …), ou nas próprias instruções decodificadas, o que é mais preciso que os antigos tipos fixos. Para feeds específicos de tipo em tempo real, Parsed Streams filtra no lado do servidor no nível da instrução.

Mapeamento de campos de resposta

Enhanced Transactions retorna uma lista plana de transações enriquecidas. Parsed Events envolve cada resultado em um envelope — { signature, parserStatus, parsed } — e respostas de histórico envolvem a lista em um objeto de página com paginationToken. Os campos analisados mapeiam-se da seguinte forma:

Campo antigo	Novo campo
`description`	`parsed.summary.description` — `summary` é `null` quando nenhum resumo no nível da transação se aplica
`type` (`TRANSFER`, `SWAP`, …)	`parsed.summary.type` (`transfer`, `swap`, …) — um conjunto menor; detalhe por instrução movido para `parsed.instructions[]`
`source` (`SYSTEM_PROGRAM`, `JUPITER`, …)	`parsed.summary.parsedData.protocol`, ou por instrução como `instructions[].programName`
`events` (`events.swap`, `events.nft`, …)	`parsed.summary.parsedData` — payload estruturado identificado por tipo de resumo
`fee` / `feePayer`	`parsed.fee` / `parsed.feePayer` — inalterado
`signature`	`signature` (nível do envelope)
`slot`	`parsed.slot`
`timestamp`	`parsed.blockTime`
`transactionError`	`parsed.error`, além de `parsed.decodedError` com o nome de erro do próprio programa quando metadados estão disponíveis
`nativeTransfers`	`parsed.nativeTransfers` — mesma forma (`fromUserAccount`, `toUserAccount`, `amount` em lamports)
`tokenTransfers`	`parsed.tokenTransfers` — mesmos campos de conta, mas `tokenAmount` (decimal pré-escalado) se torna `rawTokenAmount` (inteiro bruto) além de `decimals`

E a maior mudança é um novo campo sem equivalente antigo: parsed.instructions[] contém todas as instruções de nível superior e internas em ordem de execução, com decoded.args e decoded.accounts nomeados a partir do IDL do programa. Onde Enhanced Transactions lhe dava um resumo de evento por transação, Parsed Events lhe dá o resumo e a lista completa de instruções decodificadas. Veja Resposta Analisada para cada campo.

Etapas de migração

Troque os endpoints

Aponte chamadas de Parse Transactions para POST /v1/parsed-events/transactions e chamadas de histórico para POST /v1/parsed-events/transaction-history. Mesmo host, mesmo parâmetro de consulta api-key. Solicitações de histórico mudam de GET com parâmetros de consulta para POST com um corpo JSON — mova cada parâmetro conforme o mapeamento acima.

Atualize o tratamento de respostas

Desempacote o novo envelope: verifique parserStatus === "OK", então leia os campos de parsed em vez do nível superior. Renomeie timestamp para blockTime, leia description e type de summary (protegendo-se contra null), e divida rawTokenAmount por 10^decimals onde o código antigo lia tokenAmount.

Substitua o filtro de tipo

Onde o código antigo passava type=..., filtre os itens retornados no lado do cliente em parsed.summary.type ou em parsed.instructions[] — por exemplo, “instruções onde programId é Jupiter e instructionName é route” substitui type=SWAP por algo que você pode realmente verificar. Se o filtro de tipo existia para direcionar um feed em tempo real, mova esse consumidor para Parsed Streams, que filtra no nível da instrução no lado do servidor.

Simplifique a paginação

Substitua o loop de 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);

O loop termina quando paginationToken está ausente. Os antigos erros de busca em tempo de execução (“Falha ao encontrar eventos dentro do período de busca”) e o tratamento de assinatura de continuação desaparecem completamente — exclua esse código.

Verifique contra a saída antiga

Para um endereço de amostra, busque a mesma página de ambas as APIs e compare os conjuntos de assinaturas, taxas e montantes de transferência. Em seguida, implante e remova o caminho de código antigo. Enhanced Transactions continua funcionando enquanto você migra — não há corte forçado.

Diferenças de comportamento para revisar

Padrões de compromisso. O histórico tem como padrão confirmed onde o antigo endpoint tinha como padrão finalized. Passe commitment: "finalized" explicitamente se sua linha de processamento depende da finalização. processed não é suportado.
Erros por item. Uma assinatura que não pode ser analisada não falha mais na solicitação — ela retorna como um item com parserStatus: "ERROR" e um parserError. Trate-a por item em vez de por solicitação.
Cobertura de resumo. summary é null para transações sem uma ação reconhecida no nível da transação. A antiga API retornou type: "UNKNOWN" nesse caso; a nova API ainda fornece todas as instruções decodificadas para trabalhar.
Acesso. Parsed Events está em beta aberto em planos pagos, e a API ainda pode mudar antes da disponibilidade geral.

Deixe um agente de IA fazer a migração

Se você usa Claude Code, Cursor ou outro agente de codificação, cole o prompt abaixo na sessão do agente do seu repositório. Ele encontra locais de chamada de Enhanced Transactions e os reescreve.

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.

O prompt é autônomo — o agente não precisa de acesso a esta página. Para docs prontos para agentes, pesquisa MCP e habilidades, veja Helius for AI agents.

Próximas etapas

Início Rápido de Parsed Events

Analise sua primeira transação, busque histórico de endereços e percorra os resultados.

Resposta Analisada

Referência de campo para transações analisadas, transferências e instruções.

Parsed Streams

A mesma decodificação em tempo real via WebSocket, filtrada no lado do servidor.

getTransactionsForAddress

Histórico de transações brutas com suporte a contas de token e filtros no lado do servidor.

Introdução

Transmissão de Dados e Escuta de Eventos

APIs de Dados & RPCs

Negociação

Enviando Transações

Carteira-como-Serviço

Privacidade

Guias

Recursos

Migre de Enhanced Transactions para Parsed Events

Por que migrar?

Mapeamento de endpoint

Antes e depois

Mapeamento de parâmetros

Analisar Transações

Histórico de Transações

Mapeamento de campos de resposta

Etapas de migração

Diferenças de comportamento para revisar

Deixe um agente de IA fazer a migração

Próximas etapas

Início Rápido de Parsed Events

Resposta Analisada

Parsed Streams

getTransactionsForAddress

​Por que migrar?

​Mapeamento de endpoint

​Antes e depois

​Mapeamento de parâmetros

​Analisar Transações

​Histórico de Transações

​Mapeamento de campos de resposta

​Etapas de migração

​Diferenças de comportamento para revisar

​Deixe um agente de IA fazer a migração

​Próximas etapas

Início Rápido de Parsed Events

Resposta Analisada

Parsed Streams

getTransactionsForAddress

Por que migrar?

Mapeamento de endpoint

Antes e depois

Mapeamento de parâmetros

Analisar Transações

Histórico de Transações

Mapeamento de campos de resposta

Etapas de migração

Diferenças de comportamento para revisar

Deixe um agente de IA fazer a migração

Próximas etapas