Skip to main content
POST
getTokenAccountsByOwnerV2

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

Large Portfolios

Gestiona carteras con miles de cuentas de tokens sin tiempos de espera agotados ni problemas de memoria

Real-time Tracking

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).

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

Actualizaciones incrementales de una cartera

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.

Migración desde getTokenAccountsByOwner

La migración es sencilla: solo agrega parámetros de paginación a tus consultas existentes:

Métodos relacionados

getTokenAccountsByOwner

Método original sin paginación

getProgramAccountsV2

Método V2 para consultas de cuentas de programas

Parámetros de la solicitud

string
requerido
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.
string
Dirección específica de acuñación de un token de Solana para obtener solo las cuentas de un token o NFT determinado.
string
ID específico del programa de tokens de Solana (normalmente, el programa SPL Token) que creó las cuentas de tokens.
string
Nivel de confirmación de la solicitud.
  • confirmed
  • finalized
  • processed
number
El slot mínimo en el que se puede evaluar la solicitud.
boolean
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.
object
Solicita una porción de los datos de la cuenta.
number
Número de bytes que se devolverán.
number
Desplazamiento en bytes desde el que se empezará a leer.
string
Formato de codificación de los datos de la cuenta.
  • base58
  • base64
  • base64+zstd
  • jsonParsed
number
Número máximo de cuentas de tokens que se devolverán por solicitud (1-10,000).
string
Cursor de paginación codificado en base 58 para obtener las páginas siguientes. Usa el paginationKey de la respuesta anterior.
number
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.

Autorizaciones

api-key
string
query
requerido

Tu clave de API de Helius. Puedes obtener una gratis en el panel.

Cuerpo

application/json
jsonrpc
enum<string>
predeterminado:2.0

La versión del protocolo JSON-RPC.

Opciones disponibles:
2.0
Ejemplo:

"2.0"

id
string
predeterminado:1

Un identificador único para la solicitud.

Ejemplo:

"1"

method
enum<string>
predeterminado:getTokenAccountsByOwnerV2

El nombre del método RPC que se invocará.

Opciones disponibles:
getTokenAccountsByOwnerV2
Ejemplo:

"getTokenAccountsByOwnerV2"

params
string · object · object[]

Parámetros para consultar cuentas de tokens paginadas que pertenecen a una clave pública específica.

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.

Ejemplo:

"A1TMhSGzQxMr1TboBKtgixKz1sS6REASMxPo1qsyTSJd"

Respuesta

Se recuperaron correctamente las cuentas de tokens paginadas por propietario.

jsonrpc
enum<string>

La versión del protocolo JSON-RPC.

Opciones disponibles:
2.0
Ejemplo:

"2.0"

id
string

Identificador que coincide con la solicitud.

Ejemplo:

"1"

result
sin withContext · object

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).