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

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

> Изучите сценарии использования getTokenAccountBalance, примеры кода, параметры запроса, структуру ответа и рекомендации.

Метод RPC [`getTokenAccountBalance`](https://www.helius.dev/docs/api-reference/rpc/http/gettokenaccountbalance) возвращает баланс токенов указанного аккаунта SPL-токена. Это необходимо приложениям, которым требуется отображать или проверять количество определенного токена в токен-аккаунте.

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

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

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

1. **Публичный ключ токен-аккаунта** (строка, обязательный): Публичный ключ аккаунта SPL-токена в кодировке base58, который требуется запросить.
2. **Объект конфигурации** (объект, необязательный): Необязательный объект, который может содержать следующее поле:
   * **`commitment`** (строка, необязательный): Задает [уровень подтверждения](https://www.helius.dev/blog/solana-commitment-levels) для запроса. Если параметр не указан, используется уровень подтверждения RPC-узла по умолчанию (обычно `finalized`).

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

Поле `result` в ответе JSON-RPC содержит объект с полями `context` и `value`. Объект `value` содержит информацию о балансе:

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

**Пример ответа:**

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

## Примеры кода

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

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

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

Это руководство поможет вам точно получать и интерпретировать балансы SPL-токенов с помощью метода `getTokenAccountBalance`.

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

<CardGroup cols={2}>
  <Card title="getTokenAccountsByOwner" href="/docs/ru/api-reference/rpc/http/gettokenaccountsbyowner">
    Получить все токен-аккаунты владельца
  </Card>

  <Card title="getTokenSupply" href="/docs/ru/api-reference/rpc/http/gettokensupply">
    Получить общий объем предложения минта токена
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.