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

# Как получить балансы кошелька

> Получайте балансы всех токенов и NFT для любого кошелька Solana вместе со стоимостью в USD, логотипами и метаданными. Результаты сортируются по стоимости для удобного отслеживания портфеля.

<Note>
  Wallet API находится на стадии бета-тестирования. Конечные точки и форматы ответов могут измениться.
</Note>

## Обзор

Конечная точка Wallet Balances возвращает все токены и NFT в кошельке Solana — SOL, токены SPL, Token-2022 и NFT — вместе с ценами в USD, логотипами и метаданными. Результаты сортируются по стоимости в USD в порядке убывания: сначала отображаются токены, для которых доступны данные о цене, а затем токены без цены.

Конечная точка возвращает до 100 токенов за запрос, поэтому разбивку на страницы нужно реализовать вручную. Используйте параметр `page` для получения дополнительных страниц и проверяйте `pagination.hasMore`, чтобы узнать, доступны ли другие результаты. Каждый запрос представляет собой один вызов API и расходует 100 кредитов.

<Note>
  Цены в USD поступают из DAS и обновляются ежечасно. Они охватывают 10 000 крупнейших токенов по рыночной капитализации. Для неподдерживаемых токенов значения `pricePerToken` и `usdValue` равны `null`. Цены являются оценочными, а не рыночными ценами в реальном времени.
</Note>

## Когда это использовать

Используйте Wallet Balances API, если вам нужно:

* **Отображать содержимое портфеля**: показывайте пользователям все принадлежащие им токены и NFT.
* **Рассчитывать стоимость в USD**: получайте оценку портфеля на основе цен, обновляемых ежечасно.
* **Создавать интерфейсы кошельков**: реализуйте панели управления кошельками и списки активов.
* **Отслеживать токены**: контролируйте балансы определенных токенов в разных кошельках.
* **Анализировать портфель**: анализируйте распределение и концентрацию активов.
* **Готовить налоговую отчетность**: создавайте снимки активов для налоговой отчетности.

## Быстрый старт

### Базовый запрос баланса

Получите балансы всех токенов в кошельке вместе со стоимостью в USD:

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={"system"}
    const getWalletBalances = async (address) => {
      const url = `https://api.helius.xyz/v1/wallet/${address}/balances?api-key=YOUR_API_KEY`;

      const response = await fetch(url);
      if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
      }

      const data = await response.json();

      const solBalance = data.balances[0]; // SOL is always first when showNative=true
      console.log(`SOL Balance: ${solBalance.balance} SOL ($${solBalance.usdValue})`);
      console.log(`Page ${data.pagination.page} Total Value: $${data.totalUsdValue}`);
      console.log(`Token Count (this page): ${data.balances.length}`);

      // Display top holdings
      data.balances.slice(0, 5).forEach(token => {
        console.log(`${token.symbol}: ${token.balance} ($${token.usdValue || 'N/A'})`);
      });

      return data;
    };

    getWalletBalances("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY");
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    import requests

    def get_wallet_balances(address: str):
        url = f"https://api.helius.xyz/v1/wallet/{address}/balances"
        headers = {"X-Api-Key": "YOUR_API_KEY"}

        response = requests.get(url, headers=headers)
        response.raise_for_status()

        data = response.json()

        sol_balance = data['balances'][0]  # SOL is always first when showNative=true
        print(f"SOL Balance: {sol_balance['balance']} SOL (${sol_balance['usdValue']})")
        print(f"Page {data['pagination']['page']} Total Value: ${data['totalUsdValue']}")
        print(f"Token Count (this page): {len(data['balances'])}")

        # Display top holdings
        for token in data['balances'][:5]:
            usd_value = token.get('usdValue', 'N/A')
            print(f"{token['symbol']}: {token['balance']} (${usd_value})")

        return data

    get_wallet_balances("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY")
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={"system"}
    curl "https://api.helius.xyz/v1/wallet/86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY/balances?api-key=YOUR_API_KEY"
    ```
  </Tab>
</Tabs>

### Добавление NFT в результаты

Получите токены и NFT в одном запросе с помощью `showNfts=true`:

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={"system"}
    const getWalletWithNfts = async (address) => {
      const url = `https://api.helius.xyz/v1/wallet/${address}/balances?api-key=YOUR_API_KEY&showNfts=true`;

      const response = await fetch(url);
      const data = await response.json();

      console.log(`Tokens: ${data.balances.length}`);
      console.log(`NFTs: ${data.nfts?.length || 0}`);

      // Display NFTs
      data.nfts?.forEach(nft => {
        console.log(`NFT: ${nft.name || 'Unnamed'} (${nft.collectionName || 'Unknown Collection'})`);
      });

      return data;
    };

    getWalletWithNfts("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY");
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    def get_wallet_with_nfts(address: str):
        url = f"https://api.helius.xyz/v1/wallet/{address}/balances"
        params = {
            "api-key": "YOUR_API_KEY",
            "showNfts": "true"
        }

        response = requests.get(url, params=params)
        response.raise_for_status()

        data = response.json()

        print(f"Tokens: {len(data['balances'])}")
        print(f"NFTs: {len(data.get('nfts', []))}")

        # Display NFTs
        for nft in data.get('nfts', []):
            name = nft.get('name', 'Unnamed')
            collection = nft.get('collectionName', 'Unknown Collection')
            print(f"NFT: {name} ({collection})")

        return data

    get_wallet_with_nfts("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY")
    ```
  </Tab>
</Tabs>

### Фильтрация результатов

Используйте параметры запроса, чтобы ограничить возвращаемые данные:

```javascript theme={"system"}
// Only show tokens with non-zero balances
const url = `https://api.helius.xyz/v1/wallet/${address}/balances?api-key=YOUR_API_KEY&showZeroBalance=false`;

// Exclude native SOL from results
const url = `https://api.helius.xyz/v1/wallet/${address}/balances?api-key=YOUR_API_KEY&showNative=false`;

// Get only the top 50 tokens by value
const url = `https://api.helius.xyz/v1/wallet/${address}/balances?api-key=YOUR_API_KEY&limit=50`;
```

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

| Параметр | Тип | Значение по умолчанию | Описание |
| - | - | - | - |
| `page` | целое число | 1 | Номер страницы для разбивки на страницы (нумерация начинается с 1) |
| `limit` | целое число | 100 | Максимальное количество токенов на странице (1–100) |
| `showZeroBalance` | логическое значение | false | Включать токены с нулевым балансом |
| `showNative` | логическое значение | true | Включать нативный SOL в результаты |
| `showNfts` | логическое значение | false | Включать NFT в результаты (не более 100, только на первой странице) |

## Формат ответа

```json theme={"system"}
{
  "balances": [
    {
      "mint": "So11111111111111111111111111111111111111111",
      "symbol": "SOL",
      "name": "Solana",
      "balance": 1.5,
      "decimals": 9,
      "pricePerToken": 145.32,
      "usdValue": 217.98,
      "logoUri": "https://raw.githubusercontent.com/solana-labs/token-list/main/assets/mainnet/So11111111111111111111111111111111111111112/logo.png",
      "tokenProgram": "spl-token"
    },
    {
      "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "symbol": "USDC",
      "name": "USD Coin",
      "balance": 1000.5,
      "decimals": 6,
      "pricePerToken": 1.0,
      "usdValue": 1000.5,
      "logoUri": "https://example.com/usdc-logo.png",
      "tokenProgram": "spl-token"
    }
  ],
  "nfts": [
    {
      "mint": "7Xq8wXyXVqfBPPqVJjPDwG9zN5wCVxBYZ6z7vPYBzr6F",
      "name": "Degen Ape #1234",
      "imageUri": "https://example.com/nft.png",
      "collectionName": "Degen Ape Academy",
      "collectionAddress": "DegN1dXmU2uYa4n7U9qTh7YNYpK4u8L9qXx7XqYqJfGH",
      "compressed": false
    }
  ],
  "totalUsdValue": 1218.48,
  "pagination": {
    "page": 1,
    "limit": 100,
    "hasMore": true
  }
}
```

### Примечания к полям

* **`balance`**: удобочитаемое количество, уже скорректированное с учетом десятичных знаков — `1.5` означает 1,5 SOL, а `1000.5` — 1000,5 USDC. Преобразование лампортов не требуется. Эта конечная точка не предоставляет необработанное поле `amountRaw`. Если вам нужно точное целочисленное значение, вычислите его как `Math.round(balance * 10 ** decimals)`.
* **`decimals`**: предоставляется только для справки.
* **`pricePerToken` / `usdValue`**: значение `null` для токенов без данных о цене из DAS (см. примечание о ценах выше).
* **`totalUsdValue`**: общая стоимость в USD только для текущей страницы ответа. Чтобы получить стоимость всего портфеля, запросите все страницы и сложите значения `usdValue` для каждого баланса.
* **`tokenProgram`**: стандарт, используемый каждым токеном — `spl-token` (устаревший SPL Token) или `token-2022` (Token Extensions). Оба стандарта полностью поддерживаются.

## Сценарии использования

### Создание панели управления портфелем

Отображайте активы пользователя вместе со стоимостью в USD:

```javascript theme={"system"}
const renderPortfolio = async (address) => {
  const { balances, totalUsdValue } = await getWalletBalances(address);

  console.log(`Current Page Value: $${totalUsdValue.toLocaleString()}`);
  console.log(`\nTop Holdings:`);

  // totalUsdValue is page-scoped; paginate before computing full portfolio value.
  balances.slice(0, 10).forEach((token, i) => {
    if (token.usdValue) {
      console.log(`${i + 1}. ${token.symbol}: ${token.balance.toFixed(4)} ($${token.usdValue.toFixed(2)})`);
    }
  });
};
```

### Расчет концентрации токенов

Анализируйте диверсификацию портфеля:

```javascript theme={"system"}
const analyzeConcentration = async (address) => {
  const { balances, totalUsdValue } = await getWalletBalances(address);

  const tokensWithValue = balances.filter(t => t.usdValue);

  if (tokensWithValue.length === 0) {
    console.log('No tokens with USD pricing data available');
    return null;
  }

  const topToken = tokensWithValue[0];
  const pageConcentration = (topToken.usdValue / totalUsdValue) * 100;

  console.log(`Largest Position on Current Page: ${topToken.symbol} (${pageConcentration.toFixed(1)}%)`);

  if (pageConcentration > 50) {
    console.log(`Warning: Current page is highly concentrated in ${topToken.symbol}`);
  }

  return { topToken, pageConcentration };
};
```

### Отслеживание баланса определенного токена

Отслеживайте определенный токен в нескольких кошельках:

```javascript theme={"system"}
const getTokenBalance = async (address, tokenMint) => {
  const { balances } = await getWalletBalances(address);

  const token = balances.find(t => t.mint === tokenMint);

  if (!token) {
    console.log(`Token not found in wallet`);
    return null;
  }

  console.log(`${token.symbol} Balance: ${token.balance}`);
  console.log(`USD Value: $${token.usdValue || 'N/A'}`);

  return token;
};

// Example: Check USDC balance
getTokenBalance(
  "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY",
  "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" // USDC mint
);
```

### Экспорт активов для налоговой отчетности

Создайте снимок активов:

```javascript theme={"system"}
const exportHoldingsSnapshot = async (address) => {
  const { balances, totalUsdValue } = await getWalletBalances(address);

  const snapshot = {
    date: new Date().toISOString(),
    address,
    pageValueUSD: totalUsdValue,
    holdings: balances
      .filter(t => t.usdValue)
      .map(t => ({
        symbol: t.symbol,
        mint: t.mint,
        balance: t.balance,
        pricePerToken: t.pricePerToken,
        usdValue: t.usdValue
      }))
  };

  console.log(JSON.stringify(snapshot, null, 2));
  return snapshot;
};
```

## Разбивка на страницы

Для кошельков, содержащих более 100 токенов, перебирайте страницы результатов с помощью параметра `page` и `pagination.hasMore`:

```javascript theme={"system"}
const getAllBalances = async (address) => {
  let allBalances = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const url = `https://api.helius.xyz/v1/wallet/${address}/balances?api-key=YOUR_API_KEY&page=${page}&limit=100`;

    const response = await fetch(url);
    const data = await response.json();

    allBalances = allBalances.concat(data.balances);
    hasMore = data.pagination.hasMore;
    page++;

    console.log(`Fetched page ${data.pagination.page}, total tokens so far: ${allBalances.length}`);
  }

  console.log(`Total tokens: ${allBalances.length}`);
  return allBalances;
};
```

NFT возвращаются только на первой странице (не более 100) независимо от разбивки токенов на страницы.

## Рекомендации

* **Отфильтровывайте нулевые балансы, чтобы сделать интерфейс понятнее.** Используйте `showZeroBalance=false`, чтобы скрыть токены, которых больше нет в кошельке.
* **Включайте NFT только при необходимости.** По умолчанию NFT исключены для повышения производительности. Задавайте `showNfts=true` только при необходимости их отображения.
* **Обрабатывайте отсутствие данных о цене.** Перед отображением всегда проверяйте, равны ли `pricePerToken` и `usdValue` значению `null`. Это ежечасные оценки от DAS, а не рыночные цены в реальном времени.
* **Кешируйте ответы.** Данные о балансах можно кешировать на несколько секунд, чтобы сократить количество вызовов API.
* **Используйте разбивку на страницы для крупных кошельков.** Некоторые кошельки содержат тысячи токенов. Реализуйте разбивку на страницы для их эффективной обработки.

## Распространенные ошибки

| Код ошибки | Описание | Решение |
| - | - | - |
| 400 | Недопустимый формат адреса кошелька | Убедитесь, что указан допустимый адрес Solana в формате base58 |
| 401 | Ключ API отсутствует или недействителен | Убедитесь, что ключ API включен в запрос |
| 429 | Превышен лимит запросов | Сократите частоту запросов или перейдите на более высокий тарифный план |

## Дальнейшие действия

<CardGroup cols={3}>
  <Card title="Historical Balance" icon="clock" href="/docs/ru/wallet-api/balance-at">
    Получите баланс токена или SOL для прошлой метки времени, даты и времени либо слота.
  </Card>

  <Card title="Wallet API Overview" icon="wallet" href="/docs/ru/wallet-api/overview">
    Все конечные точки Wallet API и общие соглашения.
  </Card>

  <Card title="API Reference" icon="code" href="/docs/ru/api-reference/wallet-api/balances">
    Схемы запросов и ответов для балансов кошелька.
  </Card>
</CardGroup>


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