Как использовать getTokenAccountBalance

​

Распространенные сценарии использования

• Отображение балансов токенов пользователя: Показывайте пользователям, сколько определенного токена хранится в их кошельке (связанных токен-аккаунтах).
• Проверка доступности токенов: Проверяйте, достаточно ли средств на токен-аккаунте перед попыткой перевода или выполнения другой операции.
• Отслеживание портфеля: Объединяйте балансы токенов пользователя в разных токен-аккаунтах.
• Взаимодействие со смарт-контрактами: Смарт-контракты могут запрашивать балансы токенов в рамках своей логики, хотя ончейн-программы обычно получают эти данные непосредственно из информации об аккаунте.

​

Параметры запроса

1. Публичный ключ токен-аккаунта (строка, обязательный): Публичный ключ аккаунта SPL-токена в кодировке base58, который требуется запросить.
2. Объект конфигурации (объект, необязательный): Необязательный объект, который может содержать следующее поле:
   • commitment (строка, необязательный): Задает уровень подтверждения для запроса. Если параметр не указан, используется уровень подтверждения RPC-узла по умолчанию (обычно finalized).

​

Структура ответа

• amount (строка): Необработанный баланс токен-аккаунта в виде строки. Это целое число, представляющее минимальную единицу токена (например, если у токена 6 знаков после запятой, значение «1000000» означает 1 токен).
• decimals (u8): Количество знаков после запятой, заданное для этого типа токена его минтом.
• uiAmount (число | null): Баланс, отформатированный как число с плавающей запятой с учетом decimals. В некоторых случаях это поле может иметь значение null или быть устаревшим в пользу uiAmountString.
• uiAmountString (строка): Баланс, отформатированный как строка с учетом decimals. Этот вариант часто предпочтительнее для отображения, поскольку позволяет избежать возможных неточностей вычислений с плавающей запятой.

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

​

Примеры кода

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

​

Рекомендации разработчикам

• Токен-аккаунт, аккаунт минта и аккаунт владельца: Убедитесь, что вы указываете публичный ключ аккаунта SPL-токена, а не адрес минта токена или адрес кошелька владельца. Обычно токен-аккаунты владельца получают с помощью getTokenAccountsByOwner.
• Знаки после запятой: Всегда используйте поле decimals, чтобы правильно интерпретировать amount. Для отображения обычно безопаснее использовать uiAmountString вместо uiAmount, чтобы избежать проблем с точностью чисел с плавающей запятой.
• Несуществующие аккаунты: Если указанный публичный ключ не соответствует существующему токен-аккаунту, поведение может немного различаться в зависимости от поставщика RPC или библиотеки. Однако часто значение value в ответе будет равно null либо возникнет ошибка. Пример на JavaScript содержит базовую проверку balance.value.
• Уровни подтверждения: Использование разных уровней подтверждения может влиять на скорость отображения изменений баланса, особенно для совсем недавних транзакций. finalized — самый безопасный вариант, но он обеспечивает наибольшую задержку.

​

Связанные методы