Comment utiliser getTokenAccountBalance

​

Cas d’utilisation courants

• Affichage des soldes de jetons utilisateur : Montrer aux utilisateurs combien d’un jeton spécifique ils possèdent dans leur portefeuille (comptes de jetons associés).
• Vérification de la disponibilité des jetons : S’assurer qu’un compte de jetons a un solde suffisant avant d’essayer un transfert ou une autre opération.
• Suivi de portefeuille : Agréger les soldes de jetons pour un utilisateur à travers différents comptes de jetons.
• Interactions avec les contrats intelligents : Les contrats intelligents peuvent interroger les soldes de jetons dans le cadre de leur logique (bien que les programmes en chaîne accèdent généralement à ces données directement à partir des informations du compte).

​

Paramètres de requête

1. Clé publique du compte de jetons (chaîne, requis) : La clé publique encodée en base-58 du compte SPL Token que vous souhaitez interroger.
2. Objet de configuration (objet, optionnel) : Un objet optionnel qui peut contenir le champ suivant :
   • commitment (chaîne, optionnel) : Spécifie le niveau d’engagement pour la requête. Si omis, l’engagement par défaut du nœud RPC est utilisé (généralement finalized).

​

Structure de la réponse

• amount (chaîne) : Le solde brut du compte de jetons en tant que chaîne. C’est un entier représentant la plus petite unité du jeton (par exemple, si un jeton a 6 décimales, un montant de “1000000” signifie 1 jeton).
• decimals (u8) : Le nombre de décimales défini pour ce type de jeton (par sa frappe).
• uiAmount (nombre | null) : Le solde formaté en nombre à virgule flottante, en tenant compte de l’decimals. Ce champ peut être null ou déprécié dans certains contextes en faveur de l’uiAmountString.
• uiAmountString (chaîne) : Le solde formaté en tant que chaîne, en tenant compte de l’decimals. Cela est souvent préféré pour l’affichage afin d’éviter d’éventuelles inexactitudes de la virgule flottante.

{
  "jsonrpc": "2.0",
  "result": {
    "context": {
      "slot": 183457201
    },
    "value": {
      "amount": "500000000",
      "decimals": 9,
      "uiAmount": 0.5,
      "uiAmountString": "0.5"
    }
  },
  "id": 1
}

​

Exemples de code

# Basic Request (replace <TOKEN_ACCOUNT_PUBKEY>):
curl -X POST -H "Content-Type: application/json" -d \
  '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getTokenAccountBalance",
    "params": [
      "<TOKEN_ACCOUNT_PUBKEY>"
    ]
  }' \
  <YOUR_RPC_URL>

# Request with commitment (replace <TOKEN_ACCOUNT_PUBKEY>):
curl -X POST -H "Content-Type: application/json" -d \
  '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getTokenAccountBalance",
    "params": [
      "<TOKEN_ACCOUNT_PUBKEY>",
      {
        "commitment": "confirmed"
      }
    ]
  }' \
  <YOUR_RPC_URL>

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

async function checkTokenBalance(tokenAccountPublicKey) {
  // Replace with your RPC endpoint
  const connection = new Connection('https://mainnet.helius-rpc.com/?api-key=<api-key>');
  
  try {
    const tokenAccountPubKey = new PublicKey(tokenAccountPublicKey);
    const balance = await connection.getTokenAccountBalance(tokenAccountPubKey);

    if (!balance.value) {
        console.log(`Could not find token account: ${tokenAccountPublicKey}`);
        return;
    }

    console.log(`Token Account: ${tokenAccountPublicKey}`);
    console.log(`Raw Amount: ${balance.value.amount}`);
    console.log(`Decimals: ${balance.value.decimals}`);
    console.log(`UI Amount (string): ${balance.value.uiAmountString}`);
    // console.log(JSON.stringify(balance, null, 2)); // For full response details

  } catch (error) {
    console.error(`Error fetching token account balance for ${tokenAccountPublicKey}:`, error);
  }
}

// Replace with an actual SPL Token Account Public Key
const exampleTokenAccount = 'HHisAGTT6ADDd52jY1g65Akn3N2f4jSdQS2rTiyDEw5c'; // Example: An account holding some USDC on mainnet
checkTokenBalance(exampleTokenAccount);

// Example for a token account that might not exist or have 0 balance
// const nonExistentAccount = '11111111111111111111111111111111'; 
// checkTokenBalance(nonExistentAccount);

​

Conseils pour les développeurs

• Compte de jetons vs Compte de frappe vs Compte du propriétaire : Assurez-vous de fournir la clé publique du compte SPL Token, pas l’adresse de frappe du jeton ou l’adresse du portefeuille du propriétaire. Vous obtenez généralement les comptes de jetons pour un propriétaire en utilisant getTokenAccountsByOwner.
• Décimales : Utilisez toujours le champ decimals pour interpréter correctement l’amount. L’uiAmountString est généralement plus sûr pour l’affichage que l’uiAmount pour éviter les problèmes de précision à virgule flottante.
• Comptes inexistants : Si la clé publique fournie ne correspond pas à un compte de jetons existant, le comportement peut légèrement varier selon le fournisseur RPC ou la bibliothèque, mais souvent l’value dans la réponse sera null ou une erreur sera déclenchée. L’exemple JavaScript inclut une vérification de base pour balance.value.
• Niveaux d’engagement : L’utilisation de différents niveaux d’engagement peut affecter la rapidité avec laquelle vous voyez les changements de solde, surtout pour les transactions très récentes. L’finalized est le plus sûr mais a le plus de latence.

​

Méthodes associées