> ## 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.
# getTokenAccountsByOwnerV2
> Versão aprimorada do getTokenAccountsByOwner com recursos adicionais, incluindo paginação baseada em cursor e suporte para changedSinceSlot para recuperar eficientemente contas de token SPL pertencentes a um endereço de carteira específico.
## 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
Gerencie carteiras com milhares de contas de tokens sem timeouts ou problemas de memória
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)`.
```json theme={"system"}
// Omitted or false
{ "jsonrpc": "2.0", "id": "1", "result": { "value": [], "paginationKey": null } }
// true
{ "jsonrpc": "2.0", "id": "1", "result": {
"context": { "slot": 411895550, "apiVersion": "3.1.9" },
"value": { "accounts": [], "paginationKey": null }
}}
```
## 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
```typescript theme={"system"}
// Get all SPL Token accounts for a wallet
let allTokenAccounts = [];
let paginationKey = null;
do {
const response = await fetch(`https://mainnet.helius-rpc.com/?api-key=${API_KEY}`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
jsonrpc: '2.0',
id: '1',
method: 'getTokenAccountsByOwnerV2',
params: [
"9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM", // wallet address
{ "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" },
{
encoding: 'jsonParsed',
limit: 1000,
...(paginationKey && { paginationKey })
}
]
})
});
const data = await response.json();
allTokenAccounts.push(...data.result.value);
paginationKey = data.result.paginationKey;
} while (paginationKey);
console.log(`Total token accounts: ${allTokenAccounts.length}`);
```
### Atualizações Incrementais de Portfólio
```typescript theme={"system"}
// Get only token accounts modified since a specific slot
const portfolioUpdates = await fetch(`https://mainnet.helius-rpc.com/?api-key=${API_KEY}`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
jsonrpc: '2.0',
id: '1',
method: 'getTokenAccountsByOwnerV2',
params: [
walletAddress,
{ "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" },
{
encoding: 'jsonParsed',
limit: 1000,
changedSinceSlot: lastUpdateSlot // Only get recent changes
}
]
})
});
```
## 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.
```typescript theme={"system"}
// Query Token-2022 accounts (supports token extensions)
const token2022Response = await fetch(`https://mainnet.helius-rpc.com/?api-key=${API_KEY}`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
jsonrpc: '2.0',
id: '1',
method: 'getTokenAccountsByOwnerV2',
params: [
walletAddress,
{ "programId": "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb" }, // Token-2022
{ encoding: 'jsonParsed', limit: 1000 }
]
})
});
```
## Migração de getTokenAccountsByOwner
A migração é simples - basta adicionar parâmetros de paginação às suas consultas existentes:
```diff theme={"system"}
{
"jsonrpc": "2.0",
"id": "1",
- "method": "getTokenAccountsByOwner",
+ "method": "getTokenAccountsByOwnerV2",
"params": [
"9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
{ "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" },
{
"encoding": "jsonParsed",
+ "limit": 1000
}
]
}
```
## Métodos Relacionados
Método original sem paginação
Método V2 para consultas de contas de programa
## Parâmetros de Solicitação
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.
Endereço de cunhagem de token Solana específico para recuperar apenas contas para um determinado token ou NFT.
ID do programa de token Solana específico (tipicamente programa SPL Token) que criou as contas de token.
O nível de commitment para a solicitação.
* `confirmed`
* `finalized`
* `processed`
O slot mínimo em que a solicitação pode ser avaliada.
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.
Solicite um fragmento dos dados da conta.
Número de bytes a serem retornados.
Byte offset a partir do qual começar a ler.
Formato de codificação para os dados da Conta.
* `base58`
* `base64`
* `base64+zstd`
* `jsonParsed`
Número máximo de contas de tokens a serem retornadas por solicitação (1-10.000).
Cursor de paginação codificado em base-58 para buscar páginas subsequentes. Use o paginationKey da resposta anterior.
Retorne apenas contas de tokens que foram modificadas neste número de slot ou após. Útil para atualizações incrementais de portfólio.
## OpenAPI
````yaml pt-BR/openapi/rpc-http/getTokenAccountsByOwnerV2.yaml POST /
openapi: 3.1.0
info:
title: Solana RPC API
version: 1.0.0
description: >-
API aprimorada de descoberta de conta de token Solana com recursos
adicionais, incluindo paginação baseada em cursor e suporte a
changedSinceSlot para recuperação eficiente de saldos de token SPL, NFTs e
outras propriedades de token associadas a qualquer endereço de carteira.
Suporta atualizações incrementais via filtragem baseada em slot.
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://mainnet.helius-rpc.com
description: Endpoint Mainnet RPC
- url: https://devnet.helius-rpc.com
description: Endpoint Devnet RPC
security: []
paths:
/:
post:
tags:
- RPC
summary: getTokenAccountsByOwnerV2
description: >
Versão aprimorada de getTokenAccountsByOwner com recursos adicionais,
incluindo paginação baseada em cursor e suporte a changedSinceSlot para
recuperação eficiente de grandes conjuntos de contas de token SPL
pertencentes a um endereço de carteira específico. Permite consultas de
portfólio escaláveis com tamanhos de página configuráveis de até
10.000 contas por solicitação. O parâmetro changedSinceSlot permite a
recuperação apenas de contas de token modificadas desde um slot de
blockchain específico, ideal para rastreamento de portfólio em tempo
real e sincronização de saldo de carteira. Essencial para carteiras,
rastreadores de portfólio, aplicativos DeFi e qualquer serviço que
requeira dados abrangentes de propriedades de token para usuários com
extensos portfólios de token.
Nota: O fim da paginação é indicado apenas quando nenhuma conta de token
é retornada. A API pode retornar menos contas do que o limite devido ao
filtro - continue a paginação até que paginationKey seja nulo.
**withContext**: Booleano opcional no objeto de configuração (juntamente
com codificação, limite e assim por diante). Quando `withContext` é
`true`, o RPC retorna o formato padrão encapsulado de Solana:
`result.context` (metadados do instantâneo, incluindo `slot` e
geralmente `apiVersion`) e `result.value` como um objeto contendo
`accounts`, e `paginationKey`. Quando `withContext` é `false` ou
omitido, a lista de contas é `result.value` como um array (mesmo que o
clássico `getTokenAccountsByOwner`), com `paginationKey` em `result`.
Filtros, limites e comportamento de paginação permanecem inalterados;
apenas o formato JSON de `result` difere.
operationId: getTokenAccountsByOwnerV2
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
jsonrpc:
type: string
enum:
- '2.0'
description: A versão do protocolo JSON-RPC.
example: '2.0'
default: '2.0'
id:
type: string
description: Um identificador único para a solicitação.
example: '1'
default: '1'
method:
type: string
enum:
- getTokenAccountsByOwnerV2
description: O nome do método RPC a ser invocado.
example: getTokenAccountsByOwnerV2
default: getTokenAccountsByOwnerV2
params:
type: array
description: >-
Parâmetros para consulta de contas de token paginadas
pertencentes a uma chave pública específica.
default:
- A1TMhSGzQxMr1TboBKtgixKz1sS6REASMxPo1qsyTSJd
- programId: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
- encoding: jsonParsed
limit: 1000
items:
oneOf:
- type: string
description: >-
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.
example: A1TMhSGzQxMr1TboBKtgixKz1sS6REASMxPo1qsyTSJd
- type: object
description: >-
Configuração de filtro para restringir contas de token
por endereço de emissão ou ID do programa.
properties:
mint:
type: string
description: >-
Endereço específico de emissão de token Solana
para recuperar apenas contas de um token ou NFT
específico.
example: 2cHr7QS3xfuSV8wdxo3ztuF4xbiarF6Nrgx3qpx3HzXR
programId:
type: string
description: >-
ID do programa de token Solana específico
(normalmente programa SPL Token) que criou as
contas de token.
example: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
- type: object
description: >-
Objeto de configuração aprimorado com suporte a
paginação e campos opcionais.
properties:
commitment:
type: string
description: O nível de comprometimento para a solicitação.
enum:
- confirmed
- finalized
- processed
example: finalized
minContextSlot:
type: integer
description: >-
O slot mínimo em que a solicitação pode ser
avaliada.
example: 1000
withContext:
type: boolean
description: >
Quando `true`, retorna `result.context` (metadados
do instantâneo: `slot`, `apiVersion`) e aninha
`accounts` e `paginationKey` em `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.
example: true
dataSlice:
type: object
description: Solicitar um fragmento dos dados da conta.
properties:
length:
type: integer
description: Número de bytes a retornar.
example: 10
offset:
type: integer
description: >-
Deslocamento de byte a partir de onde começar
a leitura.
example: 0
encoding:
type: string
description: Formato de codificação para os dados da conta.
enum:
- base58
- base64
- base64+zstd
- jsonParsed
example: jsonParsed
limit:
type: integer
description: >-
Número máximo de contas de token a serem
retornadas por solicitação (1-10.000).
minimum: 1
maximum: 10000
example: 1000
paginationKey:
type: string
description: >-
Cursor de paginação codificado em base-58 para
busca de páginas subsequentes. Utilize a
paginationKey da resposta anterior.
example: 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM
changedSinceSlot:
type: integer
description: >-
Retornar apenas contas de token que foram
modificadas nesse slot ou após ele. Útil para
atualizações incrementais de portfólio.
example: 12345678
responses:
'200':
description: Contas de token paginadas recuperadas com sucesso por proprietário.
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 que corresponde à solicitação.
example: '1'
result:
oneOf:
- $ref: >-
#/components/schemas/TokenAccountsByOwnerV2ResultDirect
title: sem withContext
- type: object
title: com withContext
description: >-
Resultado encapsulado quando `withContext` é `true`
nas opções de solicitação.
required:
- context
- value
properties:
context:
type: object
description: >-
Metadados de instantâneo para a resposta do nó
(consistência do slot, depuração).
properties:
slot:
type: integer
description: Slot no qual o nó construiu esta resposta.
example: 341197933
apiVersion:
type: string
description: Versão da API RPC quando disponível.
example: 2.0.15
value:
$ref: '#/components/schemas/TokenAccountsByOwnerV2Page'
example:
jsonrpc: '2.0'
id: '1'
result:
value:
- pubkey: BGocb4GEpbTFm8UFV2VsDSaBXHELPfAXrvd4vtt8QWrA
account:
lamports: 2039280
owner: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
data:
program: spl-token
parsed:
info:
isNative: false
mint: 2cHr7QS3xfuSV8wdxo3ztuF4xbiarF6Nrgx3qpx3HzXR
owner: A1TMhSGzQxMr1TboBKtgixKz1sS6REASMxPo1qsyTSJd
state: initialized
tokenAmount:
amount: '420000000000000'
decimals: 6
uiAmount: 420000000
uiAmountString: '420000000'
space: 165
executable: false
rentEpoch: 18446744073709552000
space: 165
paginationKey: 8WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM
'400':
description: >-
Solicitação Incorreta - 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 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 de Resposta Excedido - A solicitação excedeu o tempo limite.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
jsonrpc: '2.0'
error:
code: -32003
message: Tempo limite excedido
id: '1'
security:
- ApiKeyQuery: []
components:
schemas:
TokenAccountsByOwnerV2ResultDirect:
type: object
description: >-
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`).
properties:
value:
type: array
description: Contas de token para a página atual.
items:
$ref: '#/components/schemas/TokenAccountByOwnerV2Entry'
paginationKey:
type: string
description: >-
Cursor de paginação para a próxima página. Nulo apenas quando
nenhuma conta de token é retornada (fim da paginação). Note que
menos contas que o limite podem ser retornadas devido ao filtro, mas
isso não indica o fim da paginação.
example: 8WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM
nullable: true
TokenAccountsByOwnerV2Page:
type: object
description: >-
Contas de token paginadas quando `withContext` é verdadeiro. Contém
`accounts` e `paginationKey` em `result.value` juntamente com
`result.context`.
properties:
accounts:
type: array
description: Contas de token para a página atual.
items:
$ref: '#/components/schemas/TokenAccountByOwnerV2Entry'
paginationKey:
type: string
description: >-
Cursor de paginação para a próxima página. Nulo apenas quando
nenhuma conta de token é retornada (fim da paginação). Note que
menos contas que o limite podem ser retornadas devido ao filtro, mas
isso não indica o fim da paginação.
example: 8WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM
nullable: true
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 de 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 que corresponde à solicitação.
example: '1'
TokenAccountByOwnerV2Entry:
type: object
properties:
pubkey:
type: string
description: Chave pública da conta como uma string codificada em base-58.
example: BGocb4GEpbTFm8UFV2VsDSaBXHELPfAXrvd4vtt8QWrA
account:
type: object
description: Detalhes da conta de token.
properties:
lamports:
type: integer
description: Número de lamports atribuídos à conta.
example: 2039280
owner:
type: string
description: Chave pública do programa ao qual esta conta foi atribuída.
example: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
data:
type: object
description: Dados de estado do token associados à conta.
properties:
program:
type: string
description: Nome do programa.
example: spl-token
parsed:
type: object
description: Dados do token analisados.
properties:
info:
type: object
description: Informações da conta de token.
properties:
isNative:
type: boolean
description: Indica se a conta possui SOL nativo.
example: false
mint:
type: string
description: Chave pública da emissão de token.
example: 2cHr7QS3xfuSV8wdxo3ztuF4xbiarF6Nrgx3qpx3HzXR
owner:
type: string
description: Chave pública do proprietário da conta.
example: A1TMhSGzQxMr1TboBKtgixKz1sS6REASMxPo1qsyTSJd
state:
type: string
description: Estado da conta de token.
example: initialized
tokenAmount:
type: object
description: Detalhes da quantidade de token.
properties:
amount:
type: string
description: Saldo bruto sem decimais.
example: '420000000000000'
decimals:
type: integer
description: Número de decimais.
example: 6
uiAmount:
type: number
description: Saldo em formato amigável para o usuário.
example: 420000000
uiAmountString:
type: string
description: Saldo como uma string.
example: '420000000'
space:
type: integer
description: Espaço alocado para a conta.
example: 165
executable:
type: boolean
description: Indica se a conta contém um programa.
example: false
rentEpoch:
type: integer
description: Época na qual a conta deve aluguel novamente.
example: 18446744073709552000
space:
type: integer
description: Tamanho dos dados da conta.
example: 165
securitySchemes:
ApiKeyQuery:
type: apiKey
in: query
name: api-key
description: >-
Sua chave API Helius. Você pode obter uma gratuitamente no
[dashboard](https://dashboard.helius.dev/api-keys).
````