Cómo usar getTokenAccountBalance

​

Casos de uso comunes

• Mostrar los saldos de tokens de los usuarios: Muestra a los usuarios cuánto poseen de un token específico en su billetera (cuentas de tokens asociadas).
• Verificar la disponibilidad de tokens: Comprueba si una cuenta de tokens tiene saldo suficiente antes de intentar una transferencia u otra operación.
• Seguimiento de portafolios: Agrega los saldos de tokens de un usuario en diferentes cuentas de tokens.
• Interacciones con contratos inteligentes: Los contratos inteligentes pueden consultar los saldos de tokens como parte de su lógica (aunque los programas en cadena suelen acceder a estos datos directamente desde la información de la cuenta).

​

Parámetros de la solicitud

1. Clave pública de la cuenta de tokens (cadena, obligatoria): La clave pública codificada en base 58 de la cuenta de tokens SPL que quieres consultar.
2. Objeto de configuración (objeto, opcional): Un objeto opcional que puede contener el siguiente campo:
   • commitment (cadena, opcional): Especifica el nivel de confirmación de la consulta. Si se omite, se usa el nivel de confirmación predeterminado del nodo RPC (normalmente finalized).

​

Estructura de la respuesta

• amount (cadena): El saldo sin procesar de la cuenta de tokens como una cadena. Es un número entero que representa la unidad más pequeña del token (por ejemplo, si un token tiene 6 decimales, una cantidad de “1000000” equivale a 1 token).
• decimals (u8): La cantidad de posiciones decimales definidas para este tipo de token (por su cuenta de acuñación).
• uiAmount (número | null): El saldo formateado como un número de punto flotante, teniendo en cuenta decimals. En algunos contextos, este campo podría ser null o estar obsoleto en favor de uiAmountString.
• uiAmountString (cadena): El saldo formateado como una cadena, teniendo en cuenta decimals. Suele preferirse para mostrar el saldo y evitar posibles imprecisiones de punto flotante.

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

​

Ejemplos de código

# 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);

​

Consejos para desarrolladores

• Cuenta de tokens frente a cuenta de acuñación frente a cuenta del propietario: Asegúrate de proporcionar la clave pública de la cuenta de tokens SPL, no la dirección de acuñación del token ni la dirección de la billetera del propietario. Normalmente, puedes obtener las cuentas de tokens de un propietario mediante getTokenAccountsByOwner.
• Decimales: Usa siempre el campo decimals para interpretar correctamente amount. Por lo general, uiAmountString es más seguro para mostrar el saldo que uiAmount, ya que evita problemas de precisión de punto flotante.
• Cuentas inexistentes: Si la clave pública proporcionada no corresponde a una cuenta de tokens existente, el comportamiento puede variar ligeramente según el proveedor de RPC o la biblioteca. Sin embargo, a menudo value en la respuesta será null o se generará un error. El ejemplo de JavaScript incluye una comprobación básica de balance.value.
• Niveles de confirmación: processed puede mostrar un cambio de saldo que posteriormente se revierte. Con Alpenglow, confirmed e finalized tienen la misma latencia y garantía de finalidad permanente. Para el código nuevo, usa preferentemente finalized.

​

Métodos relacionados