Skip to main content
POST
getTokenAccountsByOwnerV2

Visão Geral

getTokenAccountsByOwnerV2 é uma versão aprimorada do método padrão getTokenAccountsByOwner, especificamente projetada para consultar com eficiência portfólios de tokens e gerenciar carteiras com extensas participações de tokens. Este método introduz paginação baseada em cursor e capacidades de atualização incremental.
Novos Recursos no V2:
  • Paginação baseada em cursor: Configure limites de 1 a 10.000 contas de tokens por solicitação
  • Atualizações incrementais: Use changedSinceSlot para buscar apenas contas de tokens recentemente modificadas
  • Escalabilidade de portfólio: Gerencie carteiras com milhares de contas de tokens de forma eficiente
  • Compatibilidade retroativa: Suporta todos os parâmetros e filtros existentes do getTokenAccountsByOwner
  • Opcional withContext: true adiciona slot e apiVersion sob result.context; omitir ou false e eles não são incluídos
Requisito de Filtro: Você deve fornecer um mint (token específico) ou programId (programa SPL Token ou Token-2022) na sua consulta. Consultar todos os tipos de tokens para um proprietário sem um filtro não é suportado.

Principais Benefícios

Grandes Portfólios

Gerencie carteiras com milhares de contas de tokens sem timeouts ou problemas de memória

Monitoramento em Tempo Real

Monitore mudanças de portfólio em tempo real usando changedSinceSlot para atualizações incrementais

withContext (opcional)

Booleano no objeto de configuração (params[2]). Somente a forma de result muda, não filtros, limites ou paginação. Omitido ou false: result.value é o array de contas de token. true: result.context mais result.value como um objeto (accounts, paginationKey). Se você lidar com ambos, faça um branch em Array.isArray(result.value).

Melhores Práticas de Paginação

Comportamento Importante de Paginação: O fim da paginação é indicado apenas quando nenhuma conta de token é retornada. A API pode retornar menos contas que seu limite devido a filtragem - sempre continue a paginação até que paginationKey seja null.

Consulta Básica de Portfólio

Atualizações Incrementais de Portfólio

Suporte ao Programa de Tokens

Suporte a Token-2022: Use TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb como programId para consultar contas Token-2022 com extensões como taxas de transferência, tokens com juros e mais.

Migração de getTokenAccountsByOwner

A migração é simples - basta adicionar parâmetros de paginação às suas consultas existentes:

Métodos Relacionados

getTokenAccountsByOwner

Método original sem paginação

getProgramAccountsV2

Método V2 para consultas de contas de programa

Parâmetros de Solicitação

string
obrigatório
Endereço da carteira Solana (pubkey) do proprietário da conta para consultar as participações de tokens, como uma string codificada em base-58.
string
Endereço de cunhagem de token Solana específico para recuperar apenas contas para um determinado token ou NFT.
string
ID do programa de token Solana específico (tipicamente programa SPL Token) que criou as contas de token.
string
O nível de commitment para a solicitação.
  • confirmed
  • finalized
  • processed
number
O slot mínimo em que a solicitação pode ser avaliada.
boolean
Quando true, retorna result.context (metadados do snapshot: slot, apiVersion) e aninha accounts e paginationKey sob result.value como um objeto. Quando false ou omitido, result.value é o array de contas de token para esta página, com paginationKey em result. Mesmos filtros e limites se aplicam.
object
Solicite um fragmento dos dados da conta.
number
Número de bytes a serem retornados.
number
Byte offset a partir do qual começar a ler.
string
Formato de codificação para os dados da Conta.
  • base58
  • base64
  • base64+zstd
  • jsonParsed
number
Número máximo de contas de tokens a serem retornadas por solicitação (1-10.000).
string
Cursor de paginação codificado em base-58 para buscar páginas subsequentes. Use o paginationKey da resposta anterior.
number
Retorne apenas contas de tokens que foram modificadas neste número de slot ou após. Útil para atualizações incrementais de portfólio.

Autorizações

api-key
string
query
obrigatório

Sua chave API Helius. Você pode obter uma gratuitamente no dashboard.

Corpo

application/json
jsonrpc
enum<string>
padrão:2.0

A versão do protocolo JSON-RPC.

Opções disponíveis:
2.0
Exemplo:

"2.0"

id
string
padrão:1

Um identificador único para a solicitação.

Exemplo:

"1"

method
enum<string>
padrão:getTokenAccountsByOwnerV2

O nome do método RPC a ser invocado.

Opções disponíveis:
getTokenAccountsByOwnerV2
Exemplo:

"getTokenAccountsByOwnerV2"

params
string · object · object[]

Parâmetros para consulta de contas de token paginadas pertencentes a uma chave pública específica.

Endereço da carteira Solana (chave pública) do proprietário da conta para consultar propriedades de token, como uma string codificada em base-58.

Exemplo:

"A1TMhSGzQxMr1TboBKtgixKz1sS6REASMxPo1qsyTSJd"

Resposta

Contas de token paginadas recuperadas com sucesso por proprietário.

jsonrpc
enum<string>

A versão do protocolo JSON-RPC.

Opções disponíveis:
2.0
Exemplo:

"2.0"

id
string

Identificador que corresponde à solicitação.

Exemplo:

"1"

result
sem withContext · object

Contas de token paginadas quando withContext é falso ou omitido. Corresponde ao formato conhecido onde a lista de contas é result.value como um array (não aninhado em accounts).