> ## Documentation Index > Fetch the complete documentation index at: https://www.helius.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Migre de Enhanced Transactions para Parsed Events > Mude da API Enhanced Transactions para Parsed Events. Inclui mapeamento de endpoints e parâmetros, mapeamento de campos de resposta, código antes/depois e um prompt de agente de IA para copiar e colar. ## Por que migrar? A [API Enhanced Transactions](/docs/pt-BR/enhanced-transactions/overview) é 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](/docs/pt-BR/parsed-events), que decodifica instruções através do catálogo IDL que também dá suporte ao [Parsed Streams](/docs/pt-BR/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: ```javascript Before (Enhanced Transactions) theme={"system"} 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); } ``` ```javascript After (Parsed Events) theme={"system"} 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](#etapas-de-migraçã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](/docs/pt-BR/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](/docs/pt-BR/parsed-events/parsed-response) para cada campo. ## Etapas de migração 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](#mapeamento-de-parâmetros). 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`. 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](/docs/pt-BR/parsed-streams), que filtra no nível da instrução no lado do servidor. Substitua o loop de cursor `before-signature` por `paginationToken`: ```javascript theme={"system"} 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. 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. ```markdown theme={"system"} 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/
/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
- 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](/docs/pt-BR/agents/overview). ## Próximas etapas Analise sua primeira transação, busque histórico de endereços e percorra os resultados. Referência de campo para transações analisadas, transferências e instruções. A mesma decodificação em tempo real via WebSocket, filtrada no lado do servidor. Histórico de transações brutas com suporte a contas de token e filtros no lado do servidor.