> ## 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. # Migrar de getSignaturesForAddress + getTransaction para getTransactionsForAddress > Substitua o loop getSignaturesForAddress + getTransaction por uma única chamada getTransactionsForAddress. Inclui mapeamento de parâmetros, código antes/depois, mudanças de paginação e um prompt para agente de IA que automatiza a migração. ## Por que migrar? A maneira padrão de buscar o histórico de transações de um endereço no Solana envolve duas etapas: chamar `getSignaturesForAddress` para listar assinaturas e depois chamar `getTransaction` uma vez por assinatura para buscar os detalhes. Para 1.000 transações, isso resulta em 1.001 requisições HTTP. [`getTransactionsForAddress`](/docs/pt-BR/rpc/gettransactionsforaddress) é um método RPC exclusivo da Helius que colapsa ambas as etapas em uma única chamada. Ele retorna até 1.000 transações completas por requisição, com filtragem, ordenação bidirecional e suporte a contas de token que os métodos padrão não possuem. | | `getSignaturesForAddress` + `getTransaction` | `getTransactionsForAddress` | | ------------------------------------------- | -------------------------------------------- | ------------------------------------ | | Requisições para 1.000 transações | 1.001 | 1 | | Créditos para 1.000 transações completas | \~1.001 (1 crédito por chamada) | 100 (10 créditos por 100 transações) | | Histórico de conta de token associada (ATA) | Não incluído | Incluído via `filters.tokenAccounts` | | Filtros de intervalo de tempo e slot | Não | Sim | | Filtro de status (sucesso/falha) | Não | Sim | | Ordem de classificação | Mais recente primeiro apenas | Mais recente ou mais antigo primeiro | | Paginação | `before`/`until` assinaturas | `paginationToken` | O resultado: aproximadamente 10x menos créditos, 1.000x menos viagens de ida e volta, e sem necessidade de loteamento no lado do cliente, manipulação de limites de taxa, ou lógica de repetição para o fan-out `getTransaction`. ## Antes e depois Aqui está a mesma tarefa — buscar as últimas 1.000 transações de um endereço com todos os detalhes — em ambos os padrões: ```javascript Before (two methods) theme={"system"} const rpcUrl = 'https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY'; // Step 1: Get signatures (1 request) const sigResponse = await fetch(rpcUrl, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'getSignaturesForAddress', params: ['YOUR_ADDRESS_HERE', { limit: 1000 }] }) }); const { result: signatures } = await sigResponse.json(); // Step 2: Get transaction details (1,000 additional requests) const transactions = await Promise.all( signatures.map(async (sig) => { const txResponse = await fetch(rpcUrl, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'getTransaction', params: [sig.signature, { maxSupportedTransactionVersion: 0 }] }) }); const { result } = await txResponse.json(); return result; }) ); ``` ```javascript After (one method) theme={"system"} const response = await fetch('https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'getTransactionsForAddress', params: [ 'YOUR_ADDRESS_HERE', { transactionDetails: 'full', maxSupportedTransactionVersion: 0, limit: 1000 } ] }) }); const { result } = await response.json(); const transactions = result.data; // Full transactions, same shape as getTransaction ``` `getTransactionsForAddress` não faz parte do RPC padrão do Solana, então `@solana/web3.js` não tem `Connection` auxiliar para isso. Chame-o com uma solicitação JSON-RPC bruta como mostrado acima — funciona no mesmo endpoint Helius que o resto do seu tráfego RPC. ## Mapeamento de parâmetros Cada opção do fluxo antigo de duas etapas tem um equivalente direto. A maioria dos nomes permanece inalterada — apenas a paginação funciona de forma diferente. ### De getSignaturesForAddress | Opção antiga | Novo equivalente | | ---------------- | ----------------------------------------------------------------------------- | | `limit` | `limit` — mesmo máximo de 1.000 | | `before` | `paginationToken` da resposta anterior | | `until` | `filters.signature.gt` | | `commitment` | `commitment` — `confirmed` ou `finalized` apenas; `processed` não é suportado | | `minContextSlot` | `minContextSlot` — inalterado | ### De getTransaction | Opção antiga | Novo equivalente | | -------------------------------- | ------------------------------------------------------------- | | `encoding` | `encoding` — aplica-se quando `transactionDetails` é `"full"` | | `maxSupportedTransactionVersion` | `maxSupportedTransactionVersion` — inalterado | | `commitment` | `commitment` — mesma regra de cima | Duas capacidades não têm equivalente antigo: * `filters` — resultados mais estreitos por `blockTime`, `slot`, `status`, `tokenTransfer`, ou `tokenAccounts` no servidor em vez de buscar tudo e filtrar no seu código. * `sortOrder: "asc"` — resultados cronológicos (mais antigos primeiro), que os métodos padrão não podem retornar sem buscar todo o histórico e revertê-lo. ## Passos para migração `getTransactionsForAddress` é exclusivo da Helius. Funciona em `https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY` (e devnet) — o mesmo endpoint que suas chamadas existentes já utilizam se você for cliente Helius. Nenhuma mudança de chave de API ou plano é necessária. Exclua a chamada `getSignaturesForAddress` e o loop `getTransaction`. Faça uma única requisição `getTransactionsForAddress` com `transactionDetails: "full"`, mantendo seus valores `encoding`, `maxSupportedTransactionVersion`, e `commitment` como mostrado no [mapeamento de parâmetros](#mapeamento-de-parâmetros). Se você só precisar de assinaturas (por exemplo, para alimentar um pipeline existente), use `transactionDetails: "signatures"` em vez disso — custa 10 créditos fixos por chamada. O envelope de resposta muda de três maneiras: * Resultados vivem em `result.data` (um array), não diretamente em `result`. * Cada entrada em modo completo é `{ slot, transactionIndex, blockTime, transaction, meta }`. Os objetos `transaction` e `meta` são idênticos em formato ao que `getTransaction` retorna, portanto seu código de análise se mantém. * Entradas em modo de assinaturas correspondem à saída `getSignaturesForAddress` (`signature`, `slot`, `err`, `memo`, `blockTime`, `confirmationStatus`) mais um novo campo `transactionIndex`. Uma diferença comportamental a manter: com o padrão antigo, uma chamada `getTransaction` poderia retornar `null` para uma assinatura. Com `getTransactionsForAddress`, cada entrada em `result.data` é uma transação completa — remova qualquer tratamento de nulidade para detalhes ausentes. Troque o loop de cursor `before` por `paginationToken`: ```javascript theme={"system"} let paginationToken = null; const allTransactions = []; do { const response = await fetch('https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'getTransactionsForAddress', params: [ 'YOUR_ADDRESS_HERE', { transactionDetails: 'full', maxSupportedTransactionVersion: 0, limit: 1000, ...(paginationToken && { paginationToken }) } ] }) }); const { result } = await response.json(); allTransactions.push(...result.data); paginationToken = result.paginationToken; } while (paginationToken); ``` O loop termina quando `paginationToken` é `null` — não há mais comparação de listas de assinaturas ou acompanhamento manual da última assinatura. Se você usou `until` para parar em uma assinatura conhecida, substitua-o por `filters.signature: { gt: "KNOWN_SIGNATURE" }`. Se você o usou para parar em um ponto no tempo, `filters.blockTime` ou `filters.slot` geralmente são mais adequados. O padrão antigo ignora completamente a atividade da conta de token associada (ATA) a menos que você também tenha chamado `getTokenAccountsByOwner` e buscado assinaturas para cada conta de token. Para incluí-lo, adicione um filtro: ```json theme={"system"} { "filters": { "tokenAccounts": "balanceChanged" } } ``` `balanceChanged` retorna transações que referenciam a carteira ou mudam o saldo de qualquer conta de token que ela possua, filtrando spam. Veja [contas de token associadas](/docs/pt-BR/rpc/gettransactionsforaddress#associated-token-accounts) para as opções `none`/`balanceChanged`/`all` e o aviso pré-2022. Para um endereço de amostra, busque o histórico de ambas as maneiras e compare os conjuntos de assinaturas. Com `filters.tokenAccounts` desativado (o padrão `none`), `getTransactionsForAddress` retorna as mesmas transações que `getSignaturesForAddress` para o mesmo intervalo. Em seguida, implante e remova o caminho de código antigo. ## Diferenças de comportamento a revisar A maioria das migrações é uma substituição direta, mas verifique estes pontos antes de implementar: * **Compromisso.** `processed` não é suportado; use `confirmed` ou `finalized`. Se seu código antigo pesquisava o histórico recente em `processed`, mude para `confirmed`. * **Medição.** Respostas de transações completas custam 10 créditos por 100 transações retornadas (mínimo de 10 créditos); respostas apenas de assinaturas custam 10 créditos fixos. O padrão antigo custava 1 crédito por chamada — mais barato por requisição, mas muito mais caro por transação buscada. Respostas falhas são gratuitas. Veja [medição](/docs/pt-BR/rpc/gettransactionsforaddress#metering). * **Suporte de rede.** Mainnet tem retenção ilimitada. Devnet é suportado com 2 semanas de retenção. Testnet não é suportado. * **Endereços reservados.** Um pequeno conjunto de endereços do sistema (Vote Program, System Program, sysvars) roteia para caminhos arquivados de fallback ou retorna vazio. Se você indexar esses, reveja [limitações e casos extremos](/docs/pt-BR/rpc/gettransactionsforaddress#limitations-and-edge-cases). * **Múltiplos endereços.** Assim como o fluxo antigo, uma requisição cobre um endereço. Consulte endereços em paralelo e mescle; veja [múltiplos endereços](/docs/pt-BR/rpc/gettransactionsforaddress#multiple-addresses). ## Perguntas frequentes ### O getTransactionsForAddress é um método padrão de RPC do Solana? Não. É um método exclusivo da Helius disponível nos endpoints RPC da Helius. O RPC padrão do Solana e outros provedores oferecem apenas `getSignaturesForAddress` e `getTransaction`. Suas outras chamadas RPC não são afetadas — o método vive no mesmo endpoint junto com toda a superfície padrão do RPC. ### Ainda preciso de getTransaction após a migração? Apenas para consultas pontuais onde você já tem uma assinatura e nenhum contexto de endereço, como verificar uma transação específica que um usuário colou. Para qualquer histórico baseado em endereço — preenchimento, indexação, feeds de atividade de carteira — `getTransactionsForAddress` substitui ambos os métodos. ### Funciona com @solana/web3.js? O método não está na classe `Connection`, mas funciona com qualquer cliente HTTP contra seu URL RPC da Helius. Use `fetch` (ou o equivalente na sua linguagem) com um corpo JSON-RPC padrão, como mostrado nos exemplos acima. Você pode continuar usando `Connection` para todo o resto. ### Ele retornará as mesmas transações que getSignaturesForAddress? Sim. Com as configurações padrão (`filters.tokenAccounts: "none"`), ele retorna transações que referenciam o endereço consultado — o mesmo conjunto de `getSignaturesForAddress`. Definir `tokenAccounts` para `balanceChanged` ou `all` retorna mais: adiciona atividade das contas de token associadas à carteira, que o método padrão não consegue ver. ### Quanto custa em comparação com o padrão antigo? Buscar 1.000 transações completas custa 100 créditos com `getTransactionsForAddress` versus aproximadamente 1.001 créditos (e 1.001 requisições) com `getSignaturesForAddress` + `getTransaction`. Respostas apenas de assinaturas custam 10 créditos fixos por chamada. Veja [créditos da Helius](/docs/pt-BR/billing/credits) para preços completos. ## 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 o padrão antigo no seu código e o reescreve. ````markdown theme={"system"} Migrate this codebase from the two-step Solana transaction history pattern (getSignaturesForAddress followed by getTransaction) to the single Helius RPC method getTransactionsForAddress. ## Background getTransactionsForAddress is a Helius-exclusive JSON-RPC method served on standard Helius RPC endpoints (https://mainnet.helius-rpc.com/?api-key=...). It returns up to 1,000 full transactions per call, replacing one getSignaturesForAddress call plus one getTransaction call per signature. Docs: https://www.helius.dev/docs/rpc/gettransactionsforaddress.md ## Step 1: Find the old pattern Search for: - getSignaturesForAddress calls (via @solana/web3.js Connection, raw JSON-RPC, or another SDK) whose signatures are then passed to getTransaction / getParsedTransaction / getTransactions - Pagination loops using `before` or `until` signature cursors - getTokenAccountsByOwner calls used only to fetch per-token-account signature history Leave standalone getTransaction calls (single-signature lookups with no address context) unchanged. ## Step 2: Rewrite each call site Replace the two-step flow with one raw JSON-RPC request (web3.js has no Connection helper for this method): ```javascript const response = await fetch(HELIUS_RPC_URL, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'getTransactionsForAddress', params: [ address, // base-58 string { transactionDetails: 'full', // or 'signatures' if only signatures were used maxSupportedTransactionVersion: 0, // carry over from the old getTransaction options encoding: 'json', // carry over ('json', 'jsonParsed', 'base64', 'base58') limit: 1000, // up to 1,000 // paginationToken: '...', // from the previous response, for page 2+ // sortOrder: 'desc', // 'desc' (default, newest first) or 'asc' // filters: { ... } // optional, see mapping below } ] }) }); const { result } = await response.json(); // result.data -> array of transactions // result.paginationToken -> string cursor, or null when done ``` Parameter mapping: - limit -> limit - before: -> paginationToken (preferred) or filters: { signature: { lt: } } - until: -> filters: { signature: { gt: } } - commitment -> commitment ('confirmed' or 'finalized' only; if the old code used 'processed', use 'confirmed') - minContextSlot -> minContextSlot - encoding / maxSupportedTransactionVersion (from getTransaction) -> same names, top level of the config object Response shape: - Full mode: each entry is { slot, transactionIndex, blockTime, transaction, meta }. transaction and meta are identical in shape to getTransaction results, so existing parsing code carries over. Entries are never null - remove null-handling that existed for missing getTransaction results. - Signatures mode: entries match getSignaturesForAddress output ({ signature, slot, err, memo, blockTime, confirmationStatus }) plus transactionIndex. Pagination: loop while result.paginationToken is non-null, passing it back as paginationToken. Remove manual last-signature tracking. If the old code fetched signatures for the wallet's token accounts too (getTokenAccountsByOwner + per-account getSignaturesForAddress), replace all of it with one call using filters: { tokenAccounts: 'balanceChanged' } and delete the merge/dedupe logic. ## Step 3: Constraints and cleanup - The endpoint must be a Helius RPC URL; other providers do not serve this method. Do not change endpoints for other RPC calls. - Remove now-unused batching, throttling, and retry helpers that existed only for the getTransaction fan-out. - One request covers one address; keep parallel queries for multi-address code. - Preserve the surrounding code style and error handling conventions. ## Step 4: Verify - Run the project's type checks and tests. - Do NOT make any RPC calls yourself. Instead, write a standalone script (e.g. scripts/verify-gtfa-migration.mjs) that fetches history for one address both ways - the old getSignaturesForAddress + getTransaction flow and the new getTransactionsForAddress call with default filters - and prints whether the signature sets match, listing any differences. Read the RPC URL from an environment variable and the address from a CLI argument; never hardcode an API key. - Tell the user how to run it, for example: HELIUS_RPC_URL="https://mainnet.helius-rpc.com/?api-key=..." \ node scripts/verify-gtfa-migration.mjs
- Summarize every call site changed and flag any you were unsure about. ```` O prompt é autossuficiente — o agente não precisa acessar esta página. Para documentação pronta para agentes, pesquisa MCP, e habilidades, veja [Helius para agentes de IA](/docs/pt-BR/agents/overview). ## Próximos passos Tutorial completo cobrindo filtros, ordenação, paginação e contas de token. Esquema completo de requisição e resposta. Use getTransactionsForAddress para preencher e sincronizar um índice Solana. Compare todos os métodos de dados históricos do Solana.