> ## 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
> getTokenAccountsByOwnerV2 es una versión mejorada de getTokenAccountsByOwner con paginación por cursor y actualizaciones mediante changedSinceSlot para grandes carteras de tokens de Solana.
## Descripción general
`getTokenAccountsByOwnerV2` es una versión mejorada del método estándar `getTokenAccountsByOwner`, diseñada específicamente para consultar carteras de tokens de forma eficiente y gestionar carteras con una gran cantidad de tokens. Este método incorpora paginación basada en cursor y actualizaciones incrementales.
**Nuevas funciones de V2:**
* **Paginación basada en cursor**: Configura límites de 1 a 10,000 cuentas de tokens por solicitud
* **Actualizaciones incrementales**: Usa `changedSinceSlot` para obtener solo las cuentas de tokens modificadas recientemente
* **Escalabilidad de las carteras**: Gestiona de forma eficiente carteras con miles de cuentas de tokens
* **Compatibilidad con versiones anteriores**: Admite todos los parámetros y filtros existentes de `getTokenAccountsByOwner`
* **`withContext` opcional**: `true` agrega `slot` y `apiVersion` dentro de `result.context`; omítelo o usa `false` para que no se incluyan
**Requisito de filtro**: Debes proporcionar un `mint` (token específico) o un `programId` (programa SPL Token o Token-2022) en tu consulta. No se admite consultar todos los tipos de tokens de un propietario sin un filtro.
## Beneficios principales
Gestiona carteras con miles de cuentas de tokens sin tiempos de espera agotados ni problemas de memoria
Supervisa los cambios de la cartera en tiempo real mediante `changedSinceSlot` para obtener actualizaciones incrementales
## `withContext` (opcional)
Valor booleano en el objeto de configuración (`params[2]`). Solo cambia la estructura de `result`, no los filtros, los límites ni la paginación. Si se omite o se usa `false`: `result.value` es el **arreglo** de cuentas de tokens. Con `true`: `result.context` más `result.value` como **objeto** (`accounts`, `paginationKey`). Si gestionas ambos casos, crea una bifurcación según `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 }
}}
```
## Prácticas recomendadas de paginación
**Comportamiento importante de la paginación**: El final de la paginación solo se indica cuando **no se devuelve ninguna cuenta de tokens**. La API puede devolver menos cuentas que el límite debido al filtrado. Continúa siempre la paginación hasta que `paginationKey` sea `null`.
### Consulta básica de una cartera
```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}`);
```
### Actualizaciones incrementales de una cartera
```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
}
]
})
});
```
## Compatibilidad con programas de tokens
**Compatibilidad con Token-2022**: Usa `TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb` como `programId` para consultar cuentas de Token-2022 con extensiones como comisiones de transferencia, tokens que devengan intereses y más.
```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 }
]
})
});
```
## Migración desde getTokenAccountsByOwner
La migración es sencilla: solo agrega parámetros de paginación a tus 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 sin paginación
Método V2 para consultas de cuentas de programas
## Parámetros de la solicitud
Dirección de la cartera de Solana (clave pública) del propietario de la cuenta cuyas tenencias de tokens quieres consultar, como una cadena codificada en base 58.
Dirección específica de acuñación de un token de Solana para obtener solo las cuentas de un token o NFT determinado.
ID específico del programa de tokens de Solana (normalmente, el programa SPL Token) que creó las cuentas de tokens.
Nivel de confirmación de la solicitud.
* `confirmed`
* `finalized`
* `processed`
El slot mínimo en el que se puede evaluar la solicitud.
Cuando es `true`, devuelve `result.context` (metadatos de la instantánea: `slot`, `apiVersion`) y anida
`accounts` e `paginationKey` dentro de `result.value` como un objeto. Cuando es `false`
o se omite, `result.value` es el arreglo de cuentas de tokens de esta página, con `paginationKey`
en `result`. Se aplican los mismos filtros y límites.
Solicita una porción de los datos de la cuenta.
Número de bytes que se devolverán.
Desplazamiento en bytes desde el que se empezará a leer.
Formato de codificación de los datos de la cuenta.
* `base58`
* `base64`
* `base64+zstd`
* `jsonParsed`
Número máximo de cuentas de tokens que se devolverán por solicitud (1-10,000).
Cursor de paginación codificado en base 58 para obtener las páginas siguientes. Usa el paginationKey de la respuesta anterior.
Devuelve solo las cuentas de tokens que se modificaron en este número de slot o después. Resulta útil para las actualizaciones incrementales de una cartera.
## OpenAPI
````yaml es/openapi/rpc-http/getTokenAccountsByOwnerV2.yaml POST /
openapi: 3.1.0
info:
title: API RPC de Solana
version: 1.0.0
description: >-
API mejorada para descubrir cuentas de tokens de Solana, con funciones
adicionales como paginación basada en cursor y compatibilidad con
changedSinceSlot para recuperar de forma eficiente saldos de tokens SPL, NFT
y otras tenencias de tokens asociadas con cualquier dirección de billetera.
Admite actualizaciones incrementales mediante filtrado basado en slots.
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 de Mainnet
- url: https://devnet.helius-rpc.com
description: Endpoint RPC de Devnet
security: []
paths:
/:
post:
tags:
- RPC
summary: getTokenAccountsByOwnerV2
description: >
Versión mejorada de getTokenAccountsByOwner con funciones adicionales,
como paginación basada en cursor
y compatibilidad con changedSinceSlot, para recuperar de forma eficiente
grandes conjuntos de cuentas de tokens SPL que pertenecen a una
dirección de billetera específica. Permite consultas escalables de
portafolios con tamaños de página configurables de hasta 10,000
cuentas por solicitud. El parámetro changedSinceSlot permite recuperar
solo las cuentas de tokens modificadas
desde un slot específico de la cadena de bloques, lo que resulta ideal
para el seguimiento de portafolios en tiempo real y la
sincronización de saldos de billeteras. Esencial para billeteras,
herramientas de seguimiento de portafolios, aplicaciones DeFi y
cualquier servicio
que requiera datos completos de tenencias de tokens para usuarios con
portafolios extensos.
Nota: El fin de la paginación solo se indica cuando no se devuelven
cuentas de tokens. La API puede devolver menos
cuentas que el límite debido al filtrado. Continúa la paginación hasta
que paginationKey sea nulo.
**withContext**: Booleano opcional en el objeto de configuración (junto
con encoding, limit, etc.). Cuando
`withContext` es `true`, el RPC devuelve la estructura estándar envuelta
de Solana: `result.context` (metadatos de la instantánea,
incluidos `slot` y normalmente `apiVersion`) y `result.value` como un
objeto que contiene `accounts`
y `paginationKey`. Cuando `withContext` es `false` o se omite, la lista
de cuentas es
`result.value` como arreglo (igual que en `getTokenAccountsByOwner`
clásico), con `paginationKey`
en `result`. Los filtros, los límites y el comportamiento de paginación
no cambian; solo difiere la estructura JSON
de `result`.
operationId: getTokenAccountsByOwnerV2
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
jsonrpc:
type: string
enum:
- '2.0'
description: La versión del protocolo JSON-RPC.
example: '2.0'
default: '2.0'
id:
type: string
description: Un identificador único para la solicitud.
example: '1'
default: '1'
method:
type: string
enum:
- getTokenAccountsByOwnerV2
description: El nombre del método RPC que se invocará.
example: getTokenAccountsByOwnerV2
default: getTokenAccountsByOwnerV2
params:
type: array
description: >-
Parámetros para consultar cuentas de tokens paginadas que
pertenecen a una clave pública específica.
default:
- A1TMhSGzQxMr1TboBKtgixKz1sS6REASMxPo1qsyTSJd
- programId: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
- encoding: jsonParsed
limit: 1000
items:
oneOf:
- type: string
description: >-
Dirección de billetera de Solana (clave pública) del
propietario de la cuenta cuyas tenencias de tokens se
consultarán, como cadena codificada en base 58.
example: A1TMhSGzQxMr1TboBKtgixKz1sS6REASMxPo1qsyTSJd
- type: object
description: >-
Configuración de filtros para limitar las cuentas de
tokens por dirección de mint o ID de programa.
properties:
mint:
type: string
description: >-
Dirección de mint específica de un token de Solana
para recuperar solo las cuentas de un token o NFT
determinado.
example: 2cHr7QS3xfuSV8wdxo3ztuF4xbiarF6Nrgx3qpx3HzXR
programId:
type: string
description: >-
ID específico del programa de tokens de Solana
(normalmente el programa SPL Token) que creó las
cuentas de tokens.
example: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
- type: object
description: >-
Objeto de configuración mejorado con compatibilidad
con paginación y campos opcionales.
properties:
commitment:
type: string
description: El nivel de compromiso de la solicitud.
enum:
- confirmed
- finalized
- processed
example: finalized
minContextSlot:
type: integer
description: >-
El slot mínimo en el que se puede evaluar la
solicitud.
example: 1000
withContext:
type: boolean
description: >
Cuando es `true`, devuelve `result.context`
(metadatos de la instantánea: `slot`,
`apiVersion`) y anida
`accounts` y `paginationKey` en `result.value`
como un objeto. Cuando es `false`
o se omite, `result.value` es el arreglo de
cuentas de tokens de esta página, con
`paginationKey`
en `result`. Se aplican los mismos filtros y
límites.
example: true
dataSlice:
type: object
description: Solicita una porción de los datos de la cuenta.
properties:
length:
type: integer
description: Número de bytes que se devolverán.
example: 10
offset:
type: integer
description: >-
Desplazamiento en bytes desde el que se
comenzará a leer.
example: 0
encoding:
type: string
description: Formato de codificación de los datos de la cuenta.
enum:
- base58
- base64
- base64+zstd
- jsonParsed
example: jsonParsed
limit:
type: integer
description: >-
Número máximo de cuentas de tokens que se
devolverán por solicitud (1-10,000).
minimum: 1
maximum: 10000
example: 1000
paginationKey:
type: string
description: >-
Cursor de paginación codificado en base 58 para
obtener páginas posteriores. Usa el paginationKey
de la respuesta anterior.
example: 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM
changedSinceSlot:
type: integer
description: >-
Devuelve solo las cuentas de tokens que se
modificaron en este número de slot o después. Es
útil para actualizaciones incrementales del
portafolio.
example: 12345678
responses:
'200':
description: >-
Se recuperaron correctamente las cuentas de tokens paginadas por
propietario.
content:
application/json:
schema:
type: object
properties:
jsonrpc:
type: string
description: La versión del protocolo JSON-RPC.
enum:
- '2.0'
example: '2.0'
id:
type: string
description: Identificador que coincide con la solicitud.
example: '1'
result:
oneOf:
- $ref: >-
#/components/schemas/TokenAccountsByOwnerV2ResultDirect
title: sin withContext
- type: object
title: con withContext
description: >-
Resultado envuelto cuando `withContext` es `true` en
las opciones de la solicitud.
required:
- context
- value
properties:
context:
type: object
description: >-
Metadatos de la instantánea para la respuesta del
nodo (coherencia del slot y depuración).
properties:
slot:
type: integer
description: Slot en el que el nodo generó esta respuesta.
example: 341197933
apiVersion:
type: string
description: Versión de la API RPC cuando esté disponible.
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: >-
Solicitud incorrecta: parámetros de solicitud no válidos o solicitud
con formato incorrecto.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
jsonrpc: '2.0'
error:
code: -32602
message: Invalid params
id: '1'
'401':
description: 'No autorizado: la clave de API no es válida o no se proporcionó.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
jsonrpc: '2.0'
error:
code: -32001
message: Unauthorized
id: '1'
'429':
description: 'Demasiadas solicitudes: se superó el límite de frecuencia.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
jsonrpc: '2.0'
error:
code: -32005
message: Too many requests
id: '1'
'500':
description: 'Error interno del servidor: se produjo un error en el servidor.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
jsonrpc: '2.0'
error:
code: -32603
message: Internal error
id: '1'
'503':
description: >-
Servicio no disponible: el servicio no está disponible
temporalmente.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
jsonrpc: '2.0'
error:
code: -32002
message: Service unavailable
id: '1'
'504':
description: >-
Tiempo de espera de la puerta de enlace agotado: se agotó el tiempo
de espera de la solicitud.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
jsonrpc: '2.0'
error:
code: -32003
message: Gateway timeout
id: '1'
security:
- ApiKeyQuery: []
components:
schemas:
TokenAccountsByOwnerV2ResultDirect:
type: object
description: >-
Cuentas de tokens paginadas cuando `withContext` es false o se omite.
Coincide con la estructura conocida en la que la lista de cuentas es
`result.value` como arreglo (no anidada en `accounts`).
properties:
value:
type: array
description: Cuentas de tokens de la página actual.
items:
$ref: '#/components/schemas/TokenAccountByOwnerV2Entry'
paginationKey:
type: string
description: >-
Cursor de paginación para la página siguiente. Es nulo solo cuando
no se devuelven cuentas de tokens (fin de la paginación). Ten en
cuenta que el filtrado puede hacer que se devuelvan menos cuentas
que el límite, pero esto no indica el fin de la paginación.
example: 8WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM
nullable: true
TokenAccountsByOwnerV2Page:
type: object
description: >-
Cuentas de tokens paginadas cuando `withContext` es true. Contiene
`accounts` y `paginationKey` en `result.value`, junto con
`result.context`.
properties:
accounts:
type: array
description: Cuentas de tokens de la página actual.
items:
$ref: '#/components/schemas/TokenAccountByOwnerV2Entry'
paginationKey:
type: string
description: >-
Cursor de paginación para la página siguiente. Es nulo solo cuando
no se devuelven cuentas de tokens (fin de la paginación). Ten en
cuenta que el filtrado puede hacer que se devuelvan menos cuentas
que el límite, pero esto no indica el fin de la paginación.
example: 8WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM
nullable: true
ErrorResponse:
type: object
properties:
jsonrpc:
type: string
description: La versión del protocolo JSON-RPC.
enum:
- '2.0'
example: '2.0'
error:
type: object
properties:
code:
type: integer
description: El código de error.
example: -32602
message:
type: string
description: El mensaje de error.
data:
type: object
description: Datos adicionales sobre el error.
id:
type: string
description: Identificador que coincide con la solicitud.
example: '1'
TokenAccountByOwnerV2Entry:
type: object
properties:
pubkey:
type: string
description: Clave pública de la cuenta como cadena codificada en base 58.
example: BGocb4GEpbTFm8UFV2VsDSaBXHELPfAXrvd4vtt8QWrA
account:
type: object
description: Detalles de la cuenta de tokens.
properties:
lamports:
type: integer
description: Cantidad de lamports asignados a la cuenta.
example: 2039280
owner:
type: string
description: Clave pública del programa al que se asignó esta cuenta.
example: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
data:
type: object
description: Datos de estado del token asociados con la cuenta.
properties:
program:
type: string
description: Nombre del programa.
example: spl-token
parsed:
type: object
description: Datos analizados del token.
properties:
info:
type: object
description: Información de la cuenta de tokens.
properties:
isNative:
type: boolean
description: Indica si la cuenta contiene SOL nativo.
example: false
mint:
type: string
description: Clave pública del mint del token.
example: 2cHr7QS3xfuSV8wdxo3ztuF4xbiarF6Nrgx3qpx3HzXR
owner:
type: string
description: Clave pública del propietario de la cuenta.
example: A1TMhSGzQxMr1TboBKtgixKz1sS6REASMxPo1qsyTSJd
state:
type: string
description: Estado de la cuenta de tokens.
example: initialized
tokenAmount:
type: object
description: Detalles de la cantidad de tokens.
properties:
amount:
type: string
description: Saldo bruto sin decimales.
example: '420000000000000'
decimals:
type: integer
description: Número de decimales.
example: 6
uiAmount:
type: number
description: Saldo en un formato fácil de leer.
example: 420000000
uiAmountString:
type: string
description: Saldo como cadena.
example: '420000000'
space:
type: integer
description: Espacio asignado a la cuenta.
example: 165
executable:
type: boolean
description: Indica si la cuenta contiene un programa.
example: false
rentEpoch:
type: integer
description: Época en la que la cuenta deberá pagar el próximo alquiler.
example: 18446744073709552000
space:
type: integer
description: Tamaño de los datos de la cuenta.
example: 165
securitySchemes:
ApiKeyQuery:
type: apiKey
in: query
name: api-key
description: >-
Tu clave de API de Helius. Puedes obtener una gratis en el
[panel](https://dashboard.helius.dev/api-keys).
````