Pular para o conteúdo principal
POST
getHistoricalTokenAccountsByOwner
getHistoricalTokenAccountsByOwner está em Beta. Os parâmetros, preços, formatos de resposta e cobertura de dados podem mudar.

Visão geral

getHistoricalTokenAccountsByOwner retorna as contas SPL Token e Token-2022 que pertenciam a uma carteira em um slot anterior ou imediatamente após uma transação específica nesse slot. É um método RPC exclusivo da Helius. O método getTokenAccountsByOwner padrão retorna apenas o estado atual. Com a codificação jsonParsed, os valores dos tokens usam as casas decimais de cada mint na posição solicitada. Assim, os saldos refletem o que a carteira mantinha naquele momento. O histórico está disponível a partir do slot 444.959.999 (7 de setembro de 2026), que corresponde ao estado no início da época 1030. getHistoricalTokenAccountsByOwner está disponível na mainnet para planos Business ou superiores e custa 0 créditos por chamada durante o período beta. Os preços estão sujeitos a alterações.

Diferenças em relação a getTokenAccountsByOwner

  • O filtro de mint ou programa é opcional. Sem um filtro, você recebe todas as contas de token que pertenciam à carteira. Para restringir os resultados, defina mint ou programId no objeto de configuração (o terceiro parâmetro), mas não ambos.
  • O segundo parâmetro é o objeto de consulta que seleciona a posição no histórico, e não um filtro de mint ou programa.
  • result.value é um objeto com accounts e paginationKey, e não um array.

Escolha uma posição no histórico

O segundo parâmetro é um objeto de consulta:
  • Omitido ou {}: o slot indexado mais recente, limitado pelo nível de confirmação solicitado.
  • { "slot": 445000000 }: o final do slot 445.000.000.
  • { "slot": 445000000, "transactionIndex": 10 }: imediatamente após a execução da transação no índice 10 desse slot.
Consulte o Guia de contas históricas para entender como as posições funcionam.

Exemplo de solicitação

Esta solicitação retorna as contas de token USDC da carteira no final do slot 445.000.000:

Percorra todas as contas de token com paginação

Os resultados são ordenados primeiro por mint e depois pelo endereço da conta de token. Cada resposta retorna value.accounts e value.paginationKey, um cursor no formato <mint>:<tokenAccount>. Envie-o novamente na próxima solicitação até que seja null.
Uma página pode ter poucos resultados ou até estar vazia e ainda incluir um paginationKey. Somente um paginationKey com valor null significa que você chegou ao fim.
Sempre informe um slot explícito ao paginar. Se você o omitir, cada página lerá o slot indexado mais recente. Portanto, as páginas poderão vir de momentos diferentes.

Leia a resposta

Cada entrada em value.accounts contém o pubkey da conta de token e um objeto account. O objeto da conta tem os mesmos campos que getAccountInfo, além de lastUpdatedAt:
  • lastUpdatedAt.slot e lastUpdatedAt.transactionIndex identificam a gravação que produziu esse estado.
  • Um lastUpdatedAt.slot de 444.959.999 com um transactionIndex de valor null significa que a conta de token não mudou desde o início da cobertura do histórico.
  • context.slot é o slot mais recente que a Helius havia indexado quando processou a solicitação, e não o slot consultado.

Erros

Métodos relacionados

Historical Accounts Guide

Entenda como posições, cobertura e lastUpdatedAt funcionam nos métodos de contas históricas

getHistoricalAccountInfo

Leia uma única conta em um slot anterior

getTransactionsForAddress

Encontre o slot e o transactionIndex das transações que você deseja inspecionar

getTokenAccountsByOwnerV2

Percorra as contas de token atuais de uma carteira com paginação

Parâmetros da solicitação

string
obrigatório
Endereço codificado em Base-58 da carteira à qual pertenciam as contas de token. Informe a carteira do proprietário, e não uma conta de token.
number
Slot no qual o estado deve ser lido. Retorna a conta como estava no final desse slot. O primeiro slot compatível é 444959999, que corresponde ao estado no início da época 1030. Quando omitido, lê o slot indexado mais recente, limitado pelo nível de confirmação solicitado.
number
Posição de uma transação dentro do slot. Retorna o estado da conta imediatamente após a execução dessa transação, em vez do estado no final do slot. Requer slot.
string
Retorna apenas contas de token deste mint. Não pode ser combinado com programId.
string
Retorna apenas contas de token pertencentes a este programa de token. Não pode ser combinado com mint.
  • TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
  • TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb
string
padrão:"base64"
Formato de codificação dos dados da conta. Com jsonParsed, os valores dos tokens usam as casas decimais do mint na posição solicitada. base58 e binary não são compatíveis.
  • base64
  • base64+zstd
  • jsonParsed
object
Retorna apenas uma parte dos dados de cada conta. Aplica-se às codificações base64 e base64+zstd.
number
obrigatório
Deslocamento em bytes a partir do qual a leitura deve começar.
number
obrigatório
Número de bytes a retornar.
number
padrão:"5000"
Número máximo de contas de token a retornar (1–5.000).
string
Cursor do paginationKey da resposta anterior, no formato &lt;mint&gt;:&lt;tokenAccount&gt;. Quando você também define mint, o mint do cursor deve corresponder a ele.
string
padrão:"finalized"
Nível de confirmação. processed não é compatível.
  • finalized
  • confirmed
number
O slot mínimo no qual a solicitação pode ser avaliada.

Autorizações

api-key
string
query
obrigatório

Sua chave de API da Helius. Você pode obter uma gratuitamente no painel.

Corpo

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

A versão do protocolo JSON-RPC.

Opções disponíveis:
2.0
Exemplo:

"2.0"

id
string
padrão:1
obrigatório

Um identificador exclusivo para a solicitação.

Exemplo:

"1"

method
enum<string>
padrão:getHistoricalTokenAccountsByOwner
obrigatório

O nome do método RPC a ser invocado.

Opções disponíveis:
getHistoricalTokenAccountsByOwner
Exemplo:

"getHistoricalTokenAccountsByOwner"

params
(string | Consulta · object | Configuração · object)[]
obrigatório

Matriz que contém o endereço da carteira proprietária, um objeto de consulta opcional que seleciona a posição no histórico e um objeto de configuração opcional.

Required array length: 1 - 3 elements

Endereço codificado em base 58 da carteira que possuía as contas de token. Informe a carteira proprietária, não uma conta de token.

Exemplo:

"86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY"

Resposta

Uma página de contas de token históricas foi recuperada com sucesso.

jsonrpc
enum<string>

A versão do protocolo JSON-RPC.

Opções disponíveis:
2.0
Exemplo:

"2.0"

id
string

Identificador correspondente à solicitação.

Exemplo:

"1"

result
object