Skip to main content

O que é transactionSubscribe?

O método WebSocket transactionSubscribe (uma extensão Helius ao padrão Solana WebSocket API) permite eventos de transações em tempo real. Para utilizá-lo, forneça um TransactionSubscribeFilter e, opcionalmente, inclua TransactionSubscribeOptions para personalização adicional. transactionSubscribe opera nos mesmos wss://mainnet.helius-rpc.com unificados e wss://devnet.helius-rpc.com endpoints que os métodos padrão de assinatura Solana.

TransactionSubscribeFilter

  • vote: flag booleana para incluir/excluir transações relacionadas a votos
  • failed: flag booleana para incluir/excluir transações que falharam
  • signature: filtra atualizações para uma transação específica com base em sua assinatura
  • accountInclude: lista de contas para as quais você deseja receber atualizações de transações. Apenas uma das contas deve ser incluída nas atualizações de transações (por exemplo, Conta 1 OU 2).
  • accountExclude: lista de contas que você deseja excluir das atualizações de transações
  • accountRequired: transações devem incluir todas as contas especificadas para serem incluídas nas atualizações (por exemplo, Conta 1 E 2)
  • tokenAccounts: expansão da conta de token associada (ATA) opcional (balanceChanged, all ou none). Veja Monitorando uma carteira, incluindo transferências de tokens abaixo.
Você pode incluir até 50.000 endereços nas arrays accountInclude, accountExclude e accountRequired.

TransactionSubscribeOptions (Opcional)

  • commitment: nível de compromisso para buscar dados (processed, confirmed ou finalized)
  • encoding: formato de codificação dos dados retornados (base58, base64 ou jsonParsed)
  • transactionDetails: nível de detalhe para os dados retornados (full, signatures, accounts e none)
  • showRewards: flag booleana indicando se os dados de recompensa devem ser incluídos nas atualizações
  • maxSupportedTransactionVersion: especifica a versão mais alta de transações das quais você deseja receber atualizações. Para obter transações tanto legadas quanto v0, defina o valor para 0.
maxSupportedTransactionVersion é necessário para retornar as contas e detalhes de nível completo de uma determinada transação (ou seja, transactionDetails: "accounts" | "full").

Exemplo de Inscrição em Transações

Neste exemplo, estamos nos inscrevendo em transações que contêm a conta Raydium 675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8. Quando ocorre uma transação que contém a conta 675k...1Mp8 no accountKeys da transação, receberemos uma notificação WSS. Com base nas opções de assinatura, a notificação de transação será enviada no nível de compromisso processed, codificação jsonParsed, detalhes da transação full, e mostrará recompensas.

Exemplo de Notificação

Monitorando uma Carteira, Incluindo Transferências de Tokens

Quando você monitora uma carteira com accountInclude, você apenas corresponde a transações onde a chave pública da carteira aparece diretamente nas chaves da conta. Um caso comum escapa disso: quando alguém envia à carteira um token SPL (USDC, por exemplo), a transferência toca na conta de token associada (ATA) da carteira, não na chave pública da carteira — então uma inscrição accountInclude: [wallet] simples nunca a vê. Defina o campo tokenAccounts para expandir a correspondência para que a conta monitorada também corresponda a transações onde ela possui um saldo de token:
  • balanceChanged: corresponde quando a carteira possui um saldo de token cuja quantidade mudou (ou cuja conta de token foi fechada) na transação. Use isso para “me avise quando o dinheiro realmente se mover.” Esta é a escolha mais estreita, de menor volume e mais comum.
  • all: corresponde a qualquer transação que faça referência a um saldo de token que a carteira possui, mesmo se inalterado. Maior volume.
  • none: sem expansão. Igual a omitir o campo (o padrão).
A correspondência é baseada no proprietário: captura qualquer conta de token que a carteira possui, incluindo as não canônicas, não apenas o endereço ATA derivado. Um valor inválido retorna erro JSON-RPC -32602. Assinaturas que omitem tokenAccounts se comportam exatamente como antes. Para uma visão geral agnóstica de protocolo de como a expansão ATA funciona (e o mesmo campo sobre gRPC), veja Filtragem de Conta de Token (ATA).

Monitorando novos Jupiter DCAs

Jupiter DCA, ou Dollar Cost Averaging, é uma forma de agendar negociações recorrentes na Solana. Como essas ordens de compra/venda agendadas são registradas no blockchain, os traders podem usar o método transactionSubscribe e getAsset para escutar novas ordens.

Exemplo de Notificação

Monitorando novos tokens pump.fun

Exemplo de Notificação

Gerenciando Assinaturas

IDs de Assinatura

Quando transactionSubscribe é bem-sucedido, o servidor retorna um ID de assinatura no campo result. Este é o mesmo número que aparece em params.subscription em cada notificação dessa assinatura:
Armazene o ID de assinatura da resposta. Você precisará dele para cancelar a assinatura.

Cancelando a Assinatura

Para parar de receber notificações, chame transactionUnsubscribe com o ID de assinatura. Cada chamada transactionSubscribe na mesma conexão cria uma assinatura separada com seu próprio ID, então certifique-se de cancelar a assinatura antes de reinscrever-se para evitar receber notificações duplicadas.
Neste exemplo, nos inscrevemos em transações Raydium, capturamos o ID de assinatura da resposta do servidor e, em seguida, cancelamos a assinatura usando esse ID. Algumas mensagens em tráfego ainda podem chegar brevemente após chamar transactionUnsubscribe. Este é um comportamento esperado.