> ## 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. # getHistoricalTokenAccountsByOwner > Liste as contas SPL Token e Token-2022 que pertenciam a uma carteira Solana em um slot anterior ou logo após uma transação específica, com filtros de mint e paginação. > [!NOTE] > > `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](https://www.helius.dev/docs/pt-BR/rpc/historical-accounts.md) 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: ```bash theme={"system"} curl https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": "1", "method": "getHistoricalTokenAccountsByOwner", "params": [ "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY", { "slot": 445000000 }, { "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "encoding": "jsonParsed" } ] }' ``` ## 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 `:`. Envie-o novamente na próxima solicitação até que seja `null`. > [!WARNING] > > 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. ```typescript theme={"system"} const url = `https://mainnet.helius-rpc.com/?api-key=${process.env.HELIUS_API_KEY}`; async function getTokenAccountsAt(owner: string, slot: number) { const accounts = []; let paginationKey: string | null = null; do { const response = await fetch(url, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ jsonrpc: "2.0", id: "1", method: "getHistoricalTokenAccountsByOwner", params: [ owner, { slot }, { encoding: "jsonParsed", limit: 1000, ...(paginationKey && { paginationKey }) }, ], }), }); const { result, error } = await response.json(); if (error) throw new Error(`${error.code}: ${error.message}`); accounts.push(...result.value.accounts); paginationKey = result.value.paginationKey; } while (paginationKey); return accounts; } const tokenAccounts = await getTokenAccountsAt("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY", 445000000); ``` ## 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 | Código | Significado | | - | - | | `-32018` | O slot é anterior ao início da cobertura do histórico (slot 444.959.999) | | `-32004` | O slot é mais recente do que o nível de confirmação solicitado permite. Use `confirmed` ou consulte um slot mais antigo | | `-32602` | Parâmetros inválidos, como usar `mint` e `programId` ao mesmo tempo, informar um `programId` que não seja um programa de token ou usar um `paginationKey` cujo mint não corresponda a `mint` | | `-32601` | Método não encontrado. Chame seu endpoint da Helius na mainnet ou do Gatekeeper; o método não está disponível na devnet | ## Métodos relacionados > [card] [Historical Accounts Guide](https://www.helius.dev/docs/pt-BR/rpc/historical-accounts.md) > > Entenda como posições, cobertura e lastUpdatedAt funcionam nos métodos de contas históricas > [card] [getHistoricalAccountInfo](https://www.helius.dev/docs/pt-BR/api-reference/rpc/http/gethistoricalaccountinfo.md) > > Leia uma única conta em um slot anterior > [card] [getTransactionsForAddress](https://www.helius.dev/docs/pt-BR/rpc/gettransactionsforaddress.md) > > Encontre o slot e o transactionIndex das transações que você deseja inspecionar > [card] [getTokenAccountsByOwnerV2](https://www.helius.dev/docs/pt-BR/api-reference/rpc/http/gettokenaccountsbyownerv2.md) > > Percorra as contas de token atuais de uma carteira com paginação ## Parâmetros da solicitação **owner** `string` *required* 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. **slot** `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. **transactionIndex** `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. **mint** `string` Retorna apenas contas de token deste mint. Não pode ser combinado com programId. **programId** `string` Retorna apenas contas de token pertencentes a este programa de token. Não pode ser combinado com mint. * `TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA` * `TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb` **encoding** `string` (default: 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` **dataSlice** `object` Retorna apenas uma parte dos dados de cada conta. Aplica-se às codificações base64 e base64+zstd. **dataSlice.offset** `number` *required* Deslocamento em bytes a partir do qual a leitura deve começar. **dataSlice.length** `number` *required* Número de bytes a retornar. **limit** `number` (default: 5000) Número máximo de contas de token a retornar (1–5.000). **paginationKey** `string` Cursor do paginationKey da resposta anterior, no formato `<mint>:<tokenAccount>`. Quando você também define mint, o mint do cursor deve corresponder a ele. **commitment** `string` (default: finalized) Nível de confirmação. processed não é compatível. * `finalized` * `confirmed` **minContextSlot** `number` O slot mínimo no qual a solicitação pode ser avaliada. ## OpenAPI ````yaml pt-BR/openapi/rpc-http/getHistoricalTokenAccountsByOwner.yaml POST / openapi: 3.1.0 info: title: Solana RPC API version: 1.0.0 description: >- API histórica de contas de token da Solana para listar as contas SPL Token e Token-2022 que uma carteira possuía em um slot anterior, com filtros opcionais por mint ou programa de token e paginação baseada em cursor. license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - url: https://mainnet.helius-rpc.com description: Endpoint RPC da Mainnet security: [] paths: /: post: tags: - RPC summary: getHistoricalTokenAccountsByOwner description: > **Beta.** Os parâmetros, os formatos de resposta e a cobertura dos dados podem mudar. Retorna as contas SPL Token e Token-2022 que uma carteira possuía em um slot anterior ou imediatamente após uma transação específica nesse slot. Por padrão, este método RPC da Helius retorna todas as contas de token. Restrinja os resultados com um mint ou um programId de token no objeto de configuração. Os resultados são ordenados por mint e, em seguida, pelo endereço da conta de token. Uma página pode ser curta ou estar vazia e ainda assim retornar uma paginationKey; continue avançando pelas páginas até que paginationKey seja nulo. operationId: getHistoricalTokenAccountsByOwner requestBody: required: true content: application/json: schema: type: object required: - jsonrpc - id - method - params properties: jsonrpc: type: string enum: - '2.0' example: '2.0' description: A versão do protocolo JSON-RPC. default: '2.0' id: type: string example: '1' description: Um identificador exclusivo para a solicitação. default: '1' method: type: string enum: - getHistoricalTokenAccountsByOwner example: getHistoricalTokenAccountsByOwner description: O nome do método RPC a ser invocado. default: getHistoricalTokenAccountsByOwner params: type: array description: >- 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. minItems: 1 maxItems: 3 default: - 86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY - slot: 445000000 - encoding: jsonParsed limit: 2 items: oneOf: - type: string title: Proprietário description: >- 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. example: 86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY - $ref: '#/components/schemas/HistoricalAccountQuery' title: Consulta - type: object title: Configuração description: >- Objeto de configuração opcional. Defina no máximo um entre mint e programId. properties: mint: type: string description: >- Retorna apenas contas de token deste mint. Não pode ser combinado com programId. example: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v programId: type: string description: >- Retorna apenas contas de token pertencentes a este programa de token. Não pode ser combinado com mint. enum: - TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA - TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb example: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA encoding: type: string description: >- 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. enum: - base64 - base64+zstd - jsonParsed default: base64 example: jsonParsed dataSlice: $ref: '#/components/schemas/DataSliceConfig' limit: type: integer description: >- Número máximo de contas de token a serem retornadas (1-5.000). minimum: 1 maximum: 5000 default: 5000 example: 1000 paginationKey: type: string description: >- Cursor da paginationKey da resposta anterior, no formato `:`. Quando você também define mint, o mint do cursor deve corresponder a ele. example: >- 11112zAgXhc6hGfdfr5anSY91mq7Cs4HHpSVEQc4ASG:EKyGnXReqmmXyqBHmMjV2CKCLafJS47xyhXXZ5WuFMxD commitment: type: string description: Nível de compromisso. processed não é compatível. enum: - finalized - confirmed default: finalized example: finalized minContextSlot: type: integer description: >- O slot mínimo no qual a solicitação pode ser avaliada. example: 445000000 additionalProperties: false responses: '200': description: Uma página de contas de token históricas foi recuperada com sucesso. content: application/json: schema: type: object properties: jsonrpc: type: string description: A versão do protocolo JSON-RPC. enum: - '2.0' example: '2.0' id: type: string description: Identificador correspondente à solicitação. example: '1' result: type: object properties: context: $ref: '#/components/schemas/HistoricalContext' value: type: object properties: accounts: type: array description: >- Contas de token nesta página, ordenadas por mint e, em seguida, pelo endereço da conta de token. items: $ref: '#/components/schemas/HistoricalKeyedAccount' paginationKey: oneOf: - type: string - type: 'null' description: >- Cursor da próxima página, no formato `:`, ou nulo depois que todas as contas forem retornadas. Uma página curta ou vazia com uma paginationKey significa que a varredura foi interrompida antecipadamente, não que você chegou ao final. example: >- 11112zAgXhc6hGfdfr5anSY91mq7Cs4HHpSVEQc4ASG:EKyGnXReqmmXyqBHmMjV2CKCLafJS47xyhXXZ5WuFMxD '400': description: >- Solicitação inválida - Parâmetros de solicitação inválidos ou solicitação malformada. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: jsonrpc: '2.0' error: code: -32602 message: Parâmetros inválidos id: '1' '401': description: Não autorizado - Chave de API inválida ou ausente. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: jsonrpc: '2.0' error: code: -32001 message: Não autorizado id: '1' '429': description: Muitas solicitações - Limite de taxa excedido. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: jsonrpc: '2.0' error: code: -32005 message: Muitas solicitações id: '1' '500': description: Erro interno do servidor - Ocorreu um erro no servidor. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: jsonrpc: '2.0' error: code: -32603 message: Erro interno id: '1' '503': description: Serviço indisponível - O serviço está temporariamente indisponível. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: jsonrpc: '2.0' error: code: -32002 message: Serviço indisponível id: '1' '504': description: >- Tempo limite do gateway - O tempo limite da solicitação foi excedido. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: jsonrpc: '2.0' error: code: -32003 message: Tempo limite do gateway id: '1' security: - ApiKeyQuery: [] components: schemas: HistoricalAccountQuery: type: object description: >- A posição no histórico a ser lida. Omita-a ou envie um objeto vazio para ler o slot indexado mais recente. properties: slot: type: integer description: >- Slot no qual o estado será lido. Retorna a conta no final desse slot. O primeiro slot compatível é 444959999, o estado no início da época 1030. Quando omitido, lê o slot indexado mais recente, limitado ao nível de compromisso solicitado. minimum: 444959999 example: 445000000 transactionIndex: type: integer description: >- Posição de uma transação no 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. minimum: 0 maximum: 16777214 example: 10 additionalProperties: false DataSliceConfig: type: object description: >- Retorna apenas uma parte dos dados de cada conta. Aplica-se às codificações base64 e base64+zstd. properties: offset: type: integer description: Deslocamento em bytes a partir do qual a leitura deve começar. example: 0 length: type: integer description: Número de bytes a serem retornados. example: 8 required: - offset - length HistoricalContext: type: object description: Metadados da resposta. properties: slot: type: integer description: >- O slot mais recente que o armazenamento de histórico havia indexado quando processou a solicitação. Este não é o slot que você consultou. example: 468129571 HistoricalKeyedAccount: type: object properties: pubkey: type: string description: Endereço codificado em base 58 da conta de token. example: EKyGnXReqmmXyqBHmMjV2CKCLafJS47xyhXXZ5WuFMxD account: $ref: '#/components/schemas/HistoricalAccount' required: - pubkey - account ErrorResponse: type: object properties: jsonrpc: type: string description: A versão do protocolo JSON-RPC. enum: - '2.0' example: '2.0' error: type: object properties: code: type: integer description: O código do erro. example: -32602 message: type: string description: A mensagem de erro. data: type: object description: Dados adicionais sobre o erro. id: type: string description: Identificador correspondente à solicitação. example: '1' HistoricalAccount: type: object description: >- A conta como estava na posição solicitada, além do local onde esse estado foi gravado pela última vez. properties: lamports: type: integer description: Número de lamports atribuídos a esta conta. example: 531589475273 owner: type: string description: >- Chave pública codificada em base 58 do programa ao qual esta conta foi atribuída. example: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA data: description: >- Dados da conta. Com base64 ou base64+zstd, uma matriz de dois itens contendo os dados codificados e a codificação. Com jsonParsed, um objeto com program, parsed e space. Contas que não podem ser analisadas usam a matriz base64 como alternativa. oneOf: - type: array items: type: string - type: object properties: program: type: string description: Nome do programa proprietário da conta. example: spl-token parsed: type: object description: Estado analisado da conta específico do programa. space: type: integer description: Tamanho dos dados da conta. example: 82 executable: type: boolean description: Indica se a conta contém um programa. example: false rentEpoch: type: integer description: >- A época na qual esta conta deverá pagar aluguel novamente. Contas isentas de aluguel informam o valor máximo de u64. space: type: integer description: Tamanho dos dados da conta em bytes. example: 82 lastUpdatedAt: $ref: '#/components/schemas/AccountWritePosition' required: - lamports - owner - data - executable - rentEpoch - space - lastUpdatedAt AccountWritePosition: type: object description: >- Onde o estado retornado foi gravado pela última vez, na posição solicitada ou antes dela. properties: slot: type: integer description: >- Slot da última gravação. Um valor de 444959999 com transactionIndex nulo significa que a conta não mudou desde o início da cobertura do histórico. example: 444999837 transactionIndex: oneOf: - type: integer - type: 'null' description: >- Posição da transação que fez a última gravação. É nulo quando a gravação ocorreu fora de uma transação (por exemplo, recompensas de época) ou quando a conta não mudou desde o início da cobertura do histórico. example: 700 required: - slot - transactionIndex securitySchemes: ApiKeyQuery: type: apiKey in: query name: api-key description: >- Sua chave de API da Helius. Você pode obter uma gratuitamente no [painel](https://dashboard.helius.dev/api-keys). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.