Skip to main content

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 é 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. 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:
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

De getTransaction

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

1

Confirme que você está em um endpoint Helius

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.
2

Substitua a busca de duas etapas por uma chamada

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.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.
3

Atualize o tratamento de resposta

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.
4

Substitua a paginação baseada em assinatura

Troque o loop de cursor before por 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.
5

Opcional: habilite o histórico completo de tokens

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:
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 para as opções none/balanceChanged/all e o aviso pré-2022.
6

Verifique em relação ao resultado antigo

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.
  • 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.
  • 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.

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 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.
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.

Próximos passos

Guia getTransactionsForAddress

Tutorial completo cobrindo filtros, ordenação, paginação e contas de token.

Referência de API

Esquema completo de requisição e resposta.

Guia de indexação

Use getTransactionsForAddress para preencher e sincronizar um índice Solana.

Visão geral de dados históricos

Compare todos os métodos de dados históricos do Solana.