Como Usar getTokenAccountBalance

​

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 para a consulta. Se omitido, o comprometimento padrão do nó RPC é usado (geralmente finalized).

​

Estrutura da Resposta

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

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

​

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

​

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.

​

Métodos Relacionados