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

# Como Usar getTokenAccountBalance

> Aprenda sobre casos de uso de getTokenAccountBalance, exemplos de código, parâmetros de solicitação, estrutura de resposta e dicas.

O método RPC [`getTokenAccountBalance`](https://www.helius.dev/docs/api-reference/rpc/http/gettokenaccountbalance) retorna o saldo do token de uma conta SPL Token específica. Isso é essencial para aplicações que precisam exibir ou verificar a quantidade de um token específico mantido por uma conta de token.

## Casos de Uso Comuns

* **Exibindo Saldos de Tokens de Usuário:** Mostrando aos usuários quanto de um token específico eles possuem em sua carteira (contas de token associadas).
* **Verificando Disponibilidade de Token:** Verificando se uma conta de token tem saldo suficiente antes de tentar uma transferência ou outra operação.
* **Acompanhamento de Portfólio:** Agregando saldos de tokens para um usuário em contas de token diferentes.
* **Interações com Contratos Inteligentes:** Contratos inteligentes podem consultar saldos de tokens como parte de sua lógica (embora programas on-chain geralmente acessem esses dados diretamente a partir das informações da conta).

## Parâmetros de Solicitação

1. **Chave Pública da Conta de Token** (string, obrigatório): A chave pública codificada em base-58 da conta SPL Token que você deseja consultar.
2. **Objeto de Configuração** (objeto, opcional): Um objeto opcional que pode conter o seguinte campo:
   * **`commitment`** (string, opcional): Especifica o [nível de comprometimento](https://www.helius.dev/blog/solana-commitment-levels) para a consulta. Se omitido, o comprometimento padrão do nó RPC é usado (geralmente `finalized`).

## Estrutura da Resposta

O campo `result` na resposta JSON-RPC contém um objeto com um campo `context` e um campo `value`. O objeto `value` contém as informações do saldo:

* **`amount`** (string): O saldo bruto da conta de token como uma string. Este é um número inteiro representando a menor unidade do token (por exemplo, se um token tiver 6 decimais, um valor de "1000000" significa 1 token).
* **`decimals`** (u8): O número de casas decimais definidas para este tipo de token (por sua mint).
* **`uiAmount`** (number | null): O saldo formatado como um número de ponto flutuante, levando em conta o `decimals`. Este campo pode ser `null` ou descontinuado em alguns contextos em favor de `uiAmountString`.
* **`uiAmountString`** (string): O saldo formatado como uma string, levando em conta o `decimals`. Isso é frequentemente preferido para exibição para evitar potenciais imprecisões de ponto flutuante.

**Exemplo de Resposta:**

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

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

## Dicas para Desenvolvedores

* **Conta de Token vs. Conta de Mint vs. Conta do Proprietário:** Certifique-se de fornecer a chave pública da *Conta SPL Token*, não o endereço de mint do token ou o endereço da carteira do proprietário. Você normalmente obtém contas de token para um proprietário usando `getTokenAccountsByOwner`.
* **Decimais:** Sempre use o campo `decimals` para interpretar corretamente o `amount`. O `uiAmountString` é geralmente mais seguro para exibição do que `uiAmount` para evitar problemas de precisão de ponto flutuante.
* **Contas Inexistentes:** Se a chave pública fornecida não corresponder a uma conta de token existente, o comportamento pode variar ligeiramente por provedor de RPC ou biblioteca, mas muitas vezes o `value` na resposta será `null` ou um erro será lançado. O exemplo em JavaScript inclui uma verificação básica para `balance.value`.
* **Níveis de Comprometimento:** Usar diferentes níveis de comprometimento pode afetar a rapidez com que você vê as alterações de saldo, especialmente para transações muito recentes. `finalized` é o mais seguro, mas tem a maior latência.

Este guia deve ajudá-lo a recuperar e interpretar com precisão saldos de tokens SPL usando o método `getTokenAccountBalance`.

## Métodos Relacionados

<CardGroup cols={2}>
  <Card title="getTokenAccountsByOwner" href="/docs/pt-BR/api-reference/rpc/http/gettokenaccountsbyowner">
    Obtenha todas as contas de token para um proprietário
  </Card>

  <Card title="getTokenSupply" href="/docs/pt-BR/api-reference/rpc/http/gettokensupply">
    Obtenha a oferta total de um mint de token
  </Card>
</CardGroup>