> ## 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 est une version améliorée de getTokenAccountsByOwner avec pagination par curseur et mises à jour changedSinceSlot pour les grands portefeuilles de tokens Solana.
## Vue d'ensemble
`getTokenAccountsByOwnerV2` est une version améliorée de la méthode standard `getTokenAccountsByOwner`, spécifiquement conçue pour interroger efficacement les portefeuilles de tokens et gérer les portefeuilles avec de vastes avoirs en tokens. Cette méthode introduit la pagination basée sur des curseurs et des capacités de mise à jour incrémentielle.
**Nouvelles fonctionnalités dans V2 :**
* **Pagination basée sur des curseurs** : Configurez des limites de 1 à 10 000 comptes de tokens par requête
* **Mises à jour incrémentielles** : Utilisez `changedSinceSlot` pour récupérer uniquement les comptes de tokens récemment modifiés
* **Évolutivité des portefeuilles** : Gérez efficacement les portefeuilles avec des milliers de comptes de tokens
* **Compatibilité ascendante** : Prend en charge tous les paramètres et filtres existants de `getTokenAccountsByOwner`
* **`withContext` facultatif** : `true` ajoute `slot` et `apiVersion` sous `result.context`; omettre ou `false` et ils ne sont pas inclus
**Exigence de filtre** : Vous devez fournir soit un `mint` (token spécifique) soit un `programId` (programme SPL Token ou Token-2022) dans votre requête. Interroger tous les types de tokens pour un propriétaire sans filtre n'est pas pris en charge.
## Principaux avantages
Gérez les portefeuilles avec des milliers de comptes de tokens sans délais ou problèmes de mémoire
Surveillez les changements de portefeuille en temps réel en utilisant `changedSinceSlot` pour les mises à jour incrémentielles
## `withContext` (facultatif)
Booléen sur l'objet de configuration (`params[2]`). Seule la structure de `result` change, pas les filtres, limites ou pagination. Omit ou `false` : `result.value` est le **tableau** des comptes de tokens. `true` : `result.context` plus `result.value` en tant qu'**objet** (`accounts`, `paginationKey`). Si vous gérez les deux, branchez-vous sur `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 }
}}
```
## Meilleures pratiques de pagination
**Comportement important de la pagination** : La fin de la pagination est uniquement indiquée lorsque **aucun compte de token n'est retourné**. L'API peut renvoyer moins de comptes que votre limite en raison du filtrage - continuez toujours la pagination jusqu'à ce que `paginationKey` soit `null`.
### Requête de portefeuille de base
```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}`);
```
### Mises à jour incrémentielles du portefeuille
```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
}
]
})
});
```
## Support de programme de token
**Support Token-2022** : Utilisez `TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb` comme `programId` pour interroger les comptes Token-2022 avec des extensions comme les frais de transfert, les tokens rapportant des intérêts, et plus.
```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 }
]
})
});
```
## Migration depuis getTokenAccountsByOwner
La migration est simple - ajoutez simplement des paramètres de pagination à vos requêtes existantes :
```diff theme={"system"}
{
"jsonrpc": "2.0",
"id": "1",
- "method": "getTokenAccountsByOwner",
+ "method": "getTokenAccountsByOwnerV2",
"params": [
"9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
{ "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" },
{
"encoding": "jsonParsed",
+ "limit": 1000
}
]
}
```
## Méthodes associées
Méthode originale sans pagination
Méthode V2 pour les requêtes de comptes de programme
## Paramètres de requête
Adresse du portefeuille Solana (pubkey) du propriétaire du compte pour interroger les avoirs en tokens, sous forme de chaîne encodée en base-58.
Adresse de frappage de token Solana spécifique pour récupérer uniquement les comptes pour un token ou NFT particulier.
ID de programme de token Solana spécifique (typiquement programme SPL Token) qui a créé les comptes de tokens.
Le niveau d'engagement pour la requête.
* `confirmed`
* `finalized`
* `processed`
Le slot minimum où la requête peut être évaluée.
Quand `true`, retourne `result.context` (métadonnées de snapshot : `slot`, `apiVersion`) et imbrique
`accounts` et `paginationKey` sous `result.value` comme un objet. Quand `false`
ou omis, `result.value` est le tableau de comptes de tokens pour cette page, avec `paginationKey`
sur `result`. Les mêmes filtres et limites s'appliquent.
Demander une tranche des données du compte.
Nombre d'octets à retourner.
Décalage d'octet à partir duquel commencer la lecture.
Format d'encodage pour les données du compte.
* `base58`
* `base64`
* `base64+zstd`
* `jsonParsed`
Nombre maximal de comptes de tokens à retourner par requête (1-10 000).
Curseur de pagination encodé en base-58 pour récupérer les pages suivantes. Utilisez la paginationKey de la réponse précédente.
Ne retourner que les comptes de tokens qui ont été modifiés à ou après ce numéro de slot. Utile pour les mises à jour incrémentielles du portefeuille.
## OpenAPI
````yaml fr/openapi/rpc-http/getTokenAccountsByOwnerV2.yaml POST /
openapi: 3.1.0
info:
title: Solana RPC API
version: 1.0.0
description: >-
API de découverte de compte de jeton Solana améliorée avec des
fonctionnalités supplémentaires, y compris la pagination basée sur un
curseur et la prise en charge de changedSinceSlot pour récupérer
efficacement les soldes de jetons SPL, les NFTs et d'autres avoirs en jetons
associés à toute adresse de portefeuille. Prend en charge les mises à jour
incrémentielles via le filtrage basé sur les slots.
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://mainnet.helius-rpc.com
description: Point de terminaison RPC du Mainnet
- url: https://devnet.helius-rpc.com
description: Point de terminaison RPC du Devnet
security: []
paths:
/:
post:
tags:
- RPC
summary: getTokenAccountsByOwnerV2
description: >-
Version améliorée de getTokenAccountsByOwner avec des fonctionnalités
supplémentaires, y compris la pagination basée sur un curseur et la
prise en charge de changedSinceSlot pour récupérer efficacement de
grands ensembles de comptes de jetons SPL possédés par une adresse de
portefeuille spécifique. Permet des requêtes de portefeuille évolutives
avec des tailles de page configurables jusqu'à 10 000 comptes par
demande. Le paramètre changedSinceSlot permet de récupérer uniquement
les comptes de jetons modifiés depuis un slot de blockchain spécifique,
parfait pour le suivi en temps réel des portefeuilles et la
synchronisation des soldes de portefeuilles. Essentiel pour les
portefeuilles, les traqueurs de portefeuille, les applications DeFi, et
tout service nécessitant des données complètes d'avoirs en jetons pour
les utilisateurs avec des portefeuilles de grande envergure.
Note : La fin de la pagination est uniquement indiquée lorsque aucun
compte de jeton n'est renvoyé. L'API peut retourner moins de comptes que
la limite en raison du filtrage - continuez la pagination jusqu'à ce que
paginationKey soit nul.
**withContext** : Booléen optionnel sur l'objet de configuration (aux
côtés de encoding, limit, etc.). Quand `withContext` est `true`, le RPC
renvoie la forme classique de Solana enveloppée : `result.context`
(métadonnées de l'instantané, y compris `slot` et généralement
`apiVersion`) et `result.value` en tant qu'objet contenant `accounts`,
et `paginationKey`. Quand `withContext` est `false` ou omis, la liste
des comptes est
`result.value` sous forme de tableau (même que le classique
`getTokenAccountsByOwner`), avec `paginationKey`
sur `result`. Les filtres, limites et comportement de pagination sont
inchangés ; seul le format JSON
de `result` diffère.
operationId: getTokenAccountsByOwnerV2
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
jsonrpc:
type: string
enum:
- '2.0'
description: La version du protocole JSON-RPC.
example: '2.0'
default: '2.0'
id:
type: string
description: Un identifiant unique pour la demande.
example: '1'
default: '1'
method:
type: string
enum:
- getTokenAccountsByOwnerV2
description: Le nom de la méthode RPC à invoquer.
example: getTokenAccountsByOwnerV2
default: getTokenAccountsByOwnerV2
params:
type: array
description: >-
Paramètres pour interroger les comptes de jetons paginés
détenus par une clé publique spécifique.
default:
- A1TMhSGzQxMr1TboBKtgixKz1sS6REASMxPo1qsyTSJd
- programId: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
- encoding: jsonParsed
limit: 1000
items:
oneOf:
- type: string
description: >-
Adresse du portefeuille Solana (clé publique) du
propriétaire du compte pour interroger les avoirs en
jetons, sous forme de chaîne encodée en base-58.
example: A1TMhSGzQxMr1TboBKtgixKz1sS6REASMxPo1qsyTSJd
- type: object
description: >-
Configuration du filtre pour réduire les comptes de
jetons par adresse de monnaie ou ID de programme.
properties:
mint:
type: string
description: >-
Adresse spécifique de la monnaie de jeton Solana
pour récupérer uniquement les comptes pour un
jeton ou NFT particulier.
example: 2cHr7QS3xfuSV8wdxo3ztuF4xbiarF6Nrgx3qpx3HzXR
programId:
type: string
description: >-
ID de programme de jeton Solana spécifique
(généralement le programme de jeton SPL) qui a
créé les comptes de jetons.
example: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
- type: object
description: >-
Objet de configuration améliorée avec prise en charge
de la pagination et champs optionnels.
properties:
commitment:
type: string
description: Le niveau d'engagement pour la demande.
enum:
- confirmed
- finalized
- processed
example: finalized
minContextSlot:
type: integer
description: >-
Le slot minimum auquel la demande peut être
évaluée.
example: 1000
withContext:
type: boolean
description: >
Lorsque `true`, renvoie `result.context`
(métadonnées de l'instantané : `slot`,
`apiVersion`) et imbrique `accounts` et
`paginationKey` sous `result.value` en tant
qu'objet. Lorsque `false` ou omis, `result.value`
est le tableau de comptes de jetons pour cette
page, avec `paginationKey` sur `result`. Les mêmes
filtres et limites s'appliquent.
example: true
dataSlice:
type: object
description: Demander une tranche des données du compte.
properties:
length:
type: integer
description: Nombre d'octets à renvoyer.
example: 10
offset:
type: integer
description: >-
Décalage d'octet à partir duquel commencer la
lecture.
example: 0
encoding:
type: string
description: Format d'encodage pour les données du compte.
enum:
- base58
- base64
- base64+zstd
- jsonParsed
example: jsonParsed
limit:
type: integer
description: >-
Nombre maximum de comptes de jetons à renvoyer par
demande (1-10 000).
minimum: 1
maximum: 10000
example: 1000
paginationKey:
type: string
description: >-
Curseur de pagination encodé en base-58 pour
récupérer les pages suivantes. Utilisez
paginationKey de la réponse précédente.
example: 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM
changedSinceSlot:
type: integer
description: >-
Ne renvoie que les comptes de jetons qui ont été
modifiés à partir de ce numéro de slot. Utile pour
les mises à jour incrémentielles des
portefeuilles.
example: 12345678
responses:
'200':
description: Récupération réussie des comptes de jetons paginés par propriétaire.
content:
application/json:
schema:
type: object
properties:
jsonrpc:
type: string
description: La version du protocole JSON-RPC.
enum:
- '2.0'
example: '2.0'
id:
type: string
description: Identifiant correspondant à la demande.
example: '1'
result:
oneOf:
- $ref: >-
#/components/schemas/TokenAccountsByOwnerV2ResultDirect
title: without withContext
- type: object
title: with withContext
description: >-
Résultat enveloppé lorsque `withContext` est `true`
dans les options de la demande.
required:
- context
- value
properties:
context:
type: object
description: >-
Métadonnées de l'instantané pour la réponse du
nœud (cohérence du slot, débogage).
properties:
slot:
type: integer
description: Slot auquel le nœud a construit cette réponse.
example: 341197933
apiVersion:
type: string
description: Version de l'API RPC lorsque 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: >-
Requête incorrecte - Paramètres de demande invalides ou requête mal
formée.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
jsonrpc: '2.0'
error:
code: -32602
message: Paramètres invalides
id: '1'
'401':
description: Non autorisé - Clé API invalide ou manquante.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
jsonrpc: '2.0'
error:
code: -32001
message: Non autorisé
id: '1'
'429':
description: Trop de demandes - Limite de taux dépassée.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
jsonrpc: '2.0'
error:
code: -32005
message: Trop de demandes
id: '1'
'500':
description: >-
Erreur interne du serveur - Une erreur s'est produite sur le
serveur.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
jsonrpc: '2.0'
error:
code: -32603
message: Erreur interne
id: '1'
'503':
description: Service indisponible - Le service est temporairement indisponible.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
jsonrpc: '2.0'
error:
code: -32002
message: Service indisponible
id: '1'
'504':
description: >-
Délai d'attente de la passerelle - Le délai d'attente de la demande
a expiré.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
jsonrpc: '2.0'
error:
code: -32003
message: Délai d'attente de la passerelle
id: '1'
security:
- ApiKeyQuery: []
components:
schemas:
TokenAccountsByOwnerV2ResultDirect:
type: object
description: >-
Comptes de jetons paginés lorsque `withContext` est faux ou omis.
Correspond à la forme familière où la liste des comptes est
`result.value` sous forme de tableau (non imbriqué sous `accounts`).
properties:
value:
type: array
description: Comptes de jetons pour la page actuelle.
items:
$ref: '#/components/schemas/TokenAccountByOwnerV2Entry'
paginationKey:
type: string
description: >-
Curseur de pagination pour la page suivante. Null uniquement lorsque
aucun compte de jeton n'est renvoyé (fin de la pagination). Notez
que moins de comptes que la limite peuvent être renvoyés en raison
du filtrage, mais cela n'indique pas la fin de la pagination.
example: 8WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM
nullable: true
TokenAccountsByOwnerV2Page:
type: object
description: >-
Comptes de jetons paginés lorsque `withContext` est vrai. Contient
`accounts` et `paginationKey` sous `result.value` avec `result.context`.
properties:
accounts:
type: array
description: Comptes de jetons pour la page actuelle.
items:
$ref: '#/components/schemas/TokenAccountByOwnerV2Entry'
paginationKey:
type: string
description: >-
Curseur de pagination pour la page suivante. Null uniquement lorsque
aucun compte de jeton n'est renvoyé (fin de la pagination). Notez
que moins de comptes que la limite peuvent être renvoyés en raison
du filtrage, mais cela n'indique pas la fin de la pagination.
example: 8WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM
nullable: true
ErrorResponse:
type: object
properties:
jsonrpc:
type: string
description: La version du protocole JSON-RPC.
enum:
- '2.0'
example: '2.0'
error:
type: object
properties:
code:
type: integer
description: Le code d'erreur.
example: -32602
message:
type: string
description: Le message d'erreur.
data:
type: object
description: Informations supplémentaires sur l'erreur.
id:
type: string
description: Identifiant correspondant à la demande.
example: '1'
TokenAccountByOwnerV2Entry:
type: object
properties:
pubkey:
type: string
description: Clé publique du compte sous forme de chaîne encodée en base-58.
example: BGocb4GEpbTFm8UFV2VsDSaBXHELPfAXrvd4vtt8QWrA
account:
type: object
description: Détails du compte de jeton.
properties:
lamports:
type: integer
description: Nombre de lamports attribués au compte.
example: 2039280
owner:
type: string
description: Clé publique du programme auquel ce compte a été attribué.
example: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
data:
type: object
description: Données d'état du jeton associées au compte.
properties:
program:
type: string
description: Nom du programme.
example: spl-token
parsed:
type: object
description: Données de jeton analysées.
properties:
info:
type: object
description: Informations sur le compte de jeton.
properties:
isNative:
type: boolean
description: Indique si le compte détient du SOL natif.
example: false
mint:
type: string
description: Clé publique de la monnaie de jeton.
example: 2cHr7QS3xfuSV8wdxo3ztuF4xbiarF6Nrgx3qpx3HzXR
owner:
type: string
description: Clé publique du propriétaire du compte.
example: A1TMhSGzQxMr1TboBKtgixKz1sS6REASMxPo1qsyTSJd
state:
type: string
description: État du compte de jeton.
example: initialized
tokenAmount:
type: object
description: Détails du montant du jeton.
properties:
amount:
type: string
description: Solde brut sans décimales.
example: '420000000000000'
decimals:
type: integer
description: Nombre de décimales.
example: 6
uiAmount:
type: number
description: Solde au format convivial.
example: 420000000
uiAmountString:
type: string
description: Solde sous forme de chaîne.
example: '420000000'
space:
type: integer
description: Espace alloué pour le compte.
example: 165
executable:
type: boolean
description: Indique si le compte contient un programme.
example: false
rentEpoch:
type: integer
description: Époque à laquelle le compte devra la prochaine fois un loyer.
example: 18446744073709552000
space:
type: integer
description: Taille des données du compte.
example: 165
securitySchemes:
ApiKeyQuery:
type: apiKey
in: query
name: api-key
description: >-
Votre clé API Helius. Vous pouvez en obtenir une gratuitement sur le
[tableau de bord](https://dashboard.helius.dev/api-keys).
````