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

# Cómo usar getTokenAccountBalance

> Conoce los casos de uso, ejemplos de código, parámetros de solicitud, estructura de respuesta y consejos de getTokenAccountBalance.

El método RPC [`getTokenAccountBalance`](https://www.helius.dev/docs/api-reference/rpc/http/gettokenaccountbalance) devuelve el saldo de tokens de una cuenta de tokens SPL específica. Esto es esencial para las aplicaciones que necesitan mostrar o verificar la cantidad de un token específico que tiene una cuenta de tokens.

## 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** (string, obligatorio): La clave pública codificada en base 58 de la cuenta de tokens SPL que quieres consultar.
2. **Objeto de configuración** (object, opcional): Un objeto opcional que puede contener el siguiente campo:
   * **`commitment`** (string, opcional): Especifica el [nivel de compromiso](https://www.helius.dev/blog/solana-commitment-levels) de la consulta. Si se omite, se usa el compromiso predeterminado del nodo RPC (normalmente `finalized`).

## Estructura de la respuesta

El campo `result` de la respuesta JSON-RPC contiene un objeto con los campos `context` e `value`. El objeto `value` contiene la información del saldo:

* **`amount`** (string): El saldo bruto 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`** (number | null): El saldo formateado como un número de punto flotante, teniendo en cuenta `decimals`. Este campo puede ser `null` o estar obsoleto en algunos contextos en favor de `uiAmountString`.
* **`uiAmountString`** (string): El saldo formateado como una cadena, teniendo en cuenta `decimals`. Suele preferirse para mostrar el saldo y evitar posibles imprecisiones de punto flotante.

**Ejemplo de respuesta:**

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

## Ejemplos de código

<CodeGroup>
  ```bash cURL theme={"system"}
  # 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>
  ```

  ```javascript JavaScript (using @solana/web3.js) theme={"system"}
  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);
  ```
</CodeGroup>

## 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*. Por lo general, 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 que `uiAmount` para mostrar el saldo y evitar 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, pero 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 compromiso:** Usar diferentes niveles de compromiso puede afectar la rapidez con la que ves los cambios de saldo, especialmente en transacciones muy recientes. `finalized` es el más seguro, pero tiene la mayor latencia.

Esta guía te ayudará a recuperar e interpretar con precisión los saldos de tokens SPL mediante el método `getTokenAccountBalance`.

## Métodos relacionados

<CardGroup cols={2}>
  <Card title="getTokenAccountsByOwner" href="/docs/es/api-reference/rpc/http/gettokenaccountsbyowner">
    Obtén todas las cuentas de tokens de un propietario
  </Card>

  <Card title="getTokenSupply" href="/docs/es/api-reference/rpc/http/gettokensupply">
    Obtén el suministro total de una cuenta de acuñación de tokens
  </Card>
</CardGroup>