Comment utiliser getTokenAccountsByOwner

​

Cas d’utilisation courants

• Affichage du portefeuille utilisateur : Récupérer tous les comptes de tokens (et donc les soldes) pour l’adresse de portefeuille d’un utilisateur donné afin d’afficher leur portefeuille complet de tokens.
• Logique applicative : Identifier un compte de token spécifique d’un utilisateur pour une frappe particulière avant d’initier un transfert ou une autre interaction.
• Vérification : Vérifier quels comptes de tokens un propriétaire possède pour un certain type de token.
• Indexation des détenteurs de tokens : Bien que moins efficace pour l’indexation globale que d’autres méthodes, elle peut être utilisée pour trouver des comptes pour un ensemble connu de propriétaires.

​

Paramètres de requête

1. ownerPubkey (chaîne, requis) : La clé publique encodée en base-58 du propriétaire du compte dont vous souhaitez récupérer les comptes de tokens.
2. filter (objet, requis) : Un objet JSON qui doit spécifier soit mint soit programId :
   • mint (chaîne) : La clé publique encodée en base-58 d’une frappe de token spécifique. Si fourni, seuls les comptes de tokens pour cette frappe détenus par ownerPubkey seront retournés.
   • programId (chaîne) : La clé publique encodée en base-58 du programme de token qui gouverne les comptes. Valeurs communes :
     • SPL Token Program : TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
     • Token-2022 Program : TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb
3. options (objet, facultatif) : Un objet de configuration optionnel qui peut inclure :
   • commitment (chaîne, facultatif) : Spécifie le niveau d’engagement.
   • encoding (chaîne, facultatif) : L’encodage des données du compte. "jsonParsed" est fortement recommandé. Autres options : "base64", "base64+zstd". Par défaut à "base64".
   • dataSlice (objet, facultatif) : Pour récupérer une tranche spécifique des données du compte (offset: usize, length: usize). Uniquement pour les encodages base58, base64, ou base64+zstd.
   • minContextSlot (u64, facultatif) : Le slot minimum pour la requête.

​

Structure de la réponse

• pubkey (chaîne) : La clé publique encodée en base-58 du compte de tokens lui-même.
• account (objet) : Informations détaillées sur le compte de tokens :
  • lamports (u64) : Solde en Lamports pour l’exemption de loyer.
  • owner (chaîne) : Le programme propriétaire (par exemple, la clé publique du Token Program).
  • data: Données du compte. Si l’encodage "jsonParsed" est utilisé, cela contient :
    • program (chaîne) : par exemple, "spl-token".
    • parsed : Un objet avec des informations structurées :
      • info : Détails tels que :
        • mint (chaîne) : L’adresse de frappe du token.
        • owner (chaîne) : Le propriétaire du compte de tokens (cela devrait correspondre à ownerPubkey de la requête).
        • tokenAmount (objet) : Le solde des tokens (amount, decimals, uiAmount, uiAmountString).
        • state (chaîne) : État du compte de tokens (par exemple, "initialized").
        • isNative (booléen) : Si le compte possède des SOL enveloppés.
        • delegate (chaîne, facultatif) : L’adresse de délégation si elle est définie.
        • delegatedAmount (objet, facultatif) : La quantité déléguée si un délégué est défini.
      • type (chaîne) : par exemple, "account".
  • executable (booléen) : Si le compte est exécutable.
  • rentEpoch (u64) : Prochain loyer dû à l’époque suivante.
  • space (u64, si ce n’est pas jsonParsed) : Longueur des données brutes du compte en octets.

{
  "jsonrpc": "2.0",
  "result": {
    "context": {
      "slot": 183459000
    },
    "value": [
      {
        "pubkey": "AssociatedTokenAccountPubkey1...",
        "account": {
          "data": {
            "program": "spl-token",
            "parsed": {
              "info": {
                "isNative": false,
                "mint": "SomeTokenMintPubkey...",
                "owner": "OwnerPubkeyProvidedInRequest...",
                "state": "initialized",
                "tokenAmount": {
                  "amount": "1000000000", // 1 token if decimals is 9
                  "decimals": 9,
                  "uiAmount": 1.0,
                  "uiAmountString": "1.0"
                }
              },
              "type": "account"
            },
            "space": 165
          },
          "executable": false,
          "lamports": 2039280,
          "owner": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
          "rentEpoch": 380
        }
      },
      {
        "pubkey": "AnotherAssociatedTokenAccountPubkey...",
        "account": {
          // ... similar structure for another token owned by the same owner
        }
      }
    ]
  },
  "id": 1
}

​

Exemples de code

# Replace <OWNER_PUBKEY> and <TOKEN_MINT_PUBKEY> or <TOKEN_PROGRAM_ID>

# Example filtering by programId (SPL Token Program)
curl -X POST -H "Content-Type: application/json" -d \
  '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getTokenAccountsByOwner",
    "params": [
      "<OWNER_PUBKEY>",
      { "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" },
      { "encoding": "jsonParsed" }
    ]
  }' \
  <YOUR_RPC_URL>

# Example filtering by a specific mint
curl -X POST -H "Content-Type: application/json" -d \
  '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getTokenAccountsByOwner",
    "params": [
      "<OWNER_PUBKEY>",
      { "mint": "<SPECIFIC_TOKEN_MINT_PUBKEY>" },
      { "encoding": "jsonParsed", "commitment": "confirmed" }
    ]
  }' \
  <YOUR_RPC_URL>

const { Connection, PublicKey } = require('@solana/web3.js');

async function findOwnerTokenAccounts(ownerAddress, filter, encoding = 'jsonParsed') {
  // Replace with your RPC endpoint
  const connection = new Connection('https://mainnet.helius-rpc.com/?api-key=<api-key>');
  const ownerPubKey = new PublicKey(ownerAddress);

  try {
    let actualFilter;
    if (filter.mint) {
      actualFilter = { mint: new PublicKey(filter.mint) };
    } else if (filter.programId) {
      actualFilter = { programId: new PublicKey(filter.programId) };
    } else {
      console.error("Filter must contain either 'mint' or 'programId'");
      return;
    }

    const accounts = await connection.getTokenAccountsByOwner(
      ownerPubKey,
      actualFilter,
      { encoding }
    );

    console.log(`Found ${accounts.value.length} token accounts for owner ${ownerAddress}:`);
    accounts.value.forEach(accInfo => {
      console.log(`  Token Account: ${accInfo.pubkey.toBase58()}`);
      if (encoding === 'jsonParsed' && accInfo.account.data.parsed) {
        console.log(`    Mint: ${accInfo.account.data.parsed.info.mint}`);
        console.log(`    Balance: ${accInfo.account.data.parsed.info.tokenAmount.uiAmountString}`);
      }
      // console.log(JSON.stringify(accInfo, null, 2)); // For full details
    });

  } catch (error) {
    console.error(`Error fetching token accounts for owner ${ownerAddress}:`, error);
  }
}

// Replace with an actual owner's public key
const exampleOwner = 'HXtBm8XZbxaTt41uqaKhwUAa6Z1aPyvJdsZVENiWsetg'; // Example wallet address

// Example 1: Find all SPL Token Program accounts owned by `exampleOwner`
findOwnerTokenAccounts(exampleOwner, { programId: 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA' });

// Example 2: Find USDC token accounts owned by `exampleOwner`
// const usdcMint = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
// findOwnerTokenAccounts(exampleOwner, { mint: usdcMint });

// Example 3: Find Token-2022 Program accounts owned by `exampleOwner`
// findOwnerTokenAccounts(exampleOwner, { programId: 'TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb' });

​

Astuces pour les développeurs

• Exigence de filtre : Vous devez fournir soit un mint soit un programId dans le filtre. Il n’est pas possible de requêter tous les comptes de tokens pour un propriétaire à travers tous les types de tokens sans l’un de ces filtres principaux.
• Comptes de tokens associés : Cette méthode retournera tous les comptes de tokens détenus par la clé publique, y compris les comptes de tokens associés standard (ATAs) et tous les autres comptes de tokens SPL qu’ils pourraient posséder (par exemple, à partir d’anciennes implémentations de portefeuilles ou de configurations personnalisées).
• Encodage : Utiliser "jsonParsed" pour l’option encoding est fortement recommandé. Cela décode les données binaires du compte en une structure JSON plus utilisable.
• Performance : Si un propriétaire a un très grand nombre de comptes de tokens (surtout lors du filtrage uniquement par programId), la réponse peut être volumineuse. Pour de tels cas, utilisez getTokenAccountsByOwnerV2 qui fournit un support de pagination intégré.
• Token-2022 (Extensions de Token) : Si vous travaillez avec des tokens créés en utilisant le programme Token-2022 (qui prend en charge les extensions comme les frais de transfert, les intérêts, etc.), assurez-vous d’utiliser le bon programId : TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb.

​

Pagination pour les grands portefeuilles de tokens

• Pagination basée sur des curseurs : Définissez limit (1-10 000) et utilisez paginationKey pour naviguer dans les résultats
• Mises à jour incrémentielles : Utilisez changedSinceSlot pour récupérer uniquement les comptes de tokens modifiés depuis un slot spécifique
• Meilleure performance : Évite les dépassements de délais et permet un suivi en temps réel du portefeuille
• Comportement de la pagination : La fin de la pagination n’est indiquée que lorsqu’aucun compte de tokens n’est retourné. Moins de comptes que la limite peuvent être retournés en raison du filtrage - continuez la pagination jusqu’à ce que paginationKey soit nul

// Example: Paginated query for all token accounts
const response = await fetch("https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: "1",
    method: "getTokenAccountsByOwnerV2",
    params: [
      "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
      { "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" },
      {
        encoding: "jsonParsed",
        limit: 1000
      }
    ]
  })
});

const data = await response.json();
console.log(`Found ${data.result.value.length} token accounts`);
if (data.result.paginationKey) {
  console.log("More results available, use paginationKey for next page");
  // Continue pagination even if fewer than limit accounts were returned
} else {
  console.log("End of pagination - no more token accounts available");
}

​

Méthodes associées