Как получить исторический баланс токенов кошелька Solana

​

Обзор

• Токены (SPL / Token-2022): данные считываются из балансов токенов после транзакции и суммируются по счетам токенов кошелька для данного минта.
• Нативный SOL: данные считываются из балансов лампортов после транзакции. Для нативного SOL укажите псевдоминт So11111111111111111111111111111111111111111.

​

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

• Расчёт PnL: определение активов в начале и конце периода.
• Себестоимость и налоговые лоты: восстановление балансов на момент приобретения или выбытия.
• Разрешение споров: подтверждение активов кошелька в конкретный момент.
• Проверка снимков: проверка баланса кошелька на момент аирдропа или снимка для голосования.
• Бухгалтерский учёт и аудит: восстановление состояния кошелька на границах отчётных периодов.

​

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

​

Баланс токена на момент временной метки

const getBalanceAt = async (wallet, mint, time) => {
  const url = `https://api.helius.xyz/v1/wallet/${wallet}/balance-at?mint=${mint}&time=${time}&api-key=YOUR_API_KEY`;

  const response = await fetch(url);

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  const result = await response.json();

  if (result.asOf === null) {
    console.log('Wallet had no activity for this token by that time — balance is 0');
    return result;
  }

  console.log(`Balance: ${result.balance}`);
  console.log(`Raw amount: ${result.balanceRaw} (${result.decimals} decimals)`);
  console.log(`As of slot ${result.asOf.slot}, signature ${result.asOf.signature}`);

  return result;
};

// USDC balance on 2025-01-10 19:20:00 UTC
getBalanceAt(
  "5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9",
  "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  1736536800
);

import requests

def get_balance_at(wallet: str, mint: str, time: int):
    url = f"https://api.helius.xyz/v1/wallet/{wallet}/balance-at"
    headers = {"X-Api-Key": "YOUR_API_KEY"}
    params = {"mint": mint, "time": time}

    response = requests.get(url, headers=headers, params=params)
    response.raise_for_status()
    result = response.json()

    if result["asOf"] is None:
        print("Wallet had no activity for this token by that time — balance is 0")
        return result

    print(f"Balance: {result['balance']}")
    print(f"Raw amount: {result['balanceRaw']} ({result['decimals']} decimals)")
    print(f"As of slot {result['asOf']['slot']}, signature {result['asOf']['signature']}")

    return result

# USDC balance on 2025-01-10 19:20:00 UTC
get_balance_at(
    "5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9",
    "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    1736536800
)

curl "https://api.helius.xyz/v1/wallet/5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9/balance-at?mint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&time=1736536800&api-key=YOUR_API_KEY"

​

Баланс токена на указанную дату и время

curl "https://api.helius.xyz/v1/wallet/5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9/balance-at?mint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&datetime=2025-01-10%2019:20:00&api-key=YOUR_API_KEY"

​

Баланс нативного SOL на момент слота

curl "https://api.helius.xyz/v1/wallet/5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9/balance-at?mint=So11111111111111111111111111111111111111111&slot=313000000&api-key=YOUR_API_KEY"

​

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

​

Форматы даты и времени

• Только дата: 2025-01-10 → полночь по UTC
• Дата и время: 2025-01-10 19:20:00 или 2025-01-10T19:20:00 (секунды необязательны) → UTC
• С явным часовым поясом: 2025-01-10T19:20:00Z, 2025-01-10T19:20:00+02:00, 2025-01-10T19:20:00-05:00 → учитывается как указано

​

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

{
  "wallet": "5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9",
  "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "isNative": false,
  "balance": "284961463.392936",
  "balanceRaw": "284961463392936",
  "decimals": 6,
  "requested": {
    "time": 1736536800,
    "slot": null,
    "datetime": null
  },
  "asOf": {
    "slot": 313000000,
    "blockTime": 1736536794,
    "signature": "5Cyy7Mh9nVgFq3T8wJp2sKxR4dE6bA1uZoNcLrXmYqUpon"
  }
}

​

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

• wallet: указанный в запросе адрес кошелька.
• mint: указанный в запросе минт (псевдоминт SOL для нативного SOL).
• isNative: значение true, если результат относится к нативному SOL.
• balance: удобочитаемая сумма в виде десятичной строки — именно строки, а не числа, чтобы большие балансы не теряли точность. Конечные нули удаляются ("1.5", а не "1.500000").
• balanceRaw: точная сумма в минимальных единицах (в лампортах для SOL) в виде строки.
• decimals: количество десятичных разрядов токена (9 для SOL).
• requested: данные исходного запроса. При использовании datetime поле time также заполняется вычисленным количеством секунд от начала эпохи, что позволяет увидеть интерпретацию по UTC.
• asOf: транзакция, из которой был считан баланс (slot, blockTime, signature).

​

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

​

Изменение баланса за период

const getBalanceChange = async (wallet, mint, startTime, endTime) => {
  const fetchBalance = (time) =>
    fetch(
      `https://api.helius.xyz/v1/wallet/${wallet}/balance-at?mint=${mint}&time=${time}&api-key=YOUR_API_KEY`
    ).then(r => r.json());

  const [start, end] = await Promise.all([
    fetchBalance(startTime),
    fetchBalance(endTime)
  ]);

  // balanceRaw is an exact integer string — use BigInt for precise arithmetic
  const delta = BigInt(end.balanceRaw) - BigInt(start.balanceRaw);
  const human = Number(delta) / 10 ** end.decimals;

  console.log(`Start: ${start.balance}`);
  console.log(`End: ${end.balance}`);
  console.log(`Change: ${human > 0 ? '+' : ''}${human}`);

  return { start, end, delta };
};

​

Проверка соответствия условиям снимка

const heldAtSnapshot = async (wallet, mint, snapshotSlot, minimumRaw) => {
  const result = await fetch(
    `https://api.helius.xyz/v1/wallet/${wallet}/balance-at?mint=${mint}&slot=${snapshotSlot}&api-key=YOUR_API_KEY`
  ).then(r => r.json());

  const eligible = BigInt(result.balanceRaw) >= BigInt(minimumRaw);
  console.log(`${wallet}: ${result.balance} at slot ${snapshotSlot} — ${eligible ? 'eligible' : 'not eligible'}`);

  return eligible;
};

​

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

• Используйте slot для получения детерминированных результатов. Значения time и datetime вычисляются по времени блоков, сообщаемому валидатором, которое может отклоняться на несколько секунд. Если важна точная воспроизводимость (например, для снимков или аудитов), выполняйте запрос по slot.
• Обрабатывайте балансы как строки. balance и balanceRaw представлены строками для сохранения точности. Для арифметических операций используйте BigInt(balanceRaw) (или целые числа произвольной точности в вашем языке). Не преобразуйте значения в числа с плавающей точкой.
• Считайте asOf: null нулём. null asOf — это успешный ответ, означающий, что до запрошенного момента у кошелька не было активности с этим токеном. Не обрабатывайте его как ошибку.
• Кешируйте исторические результаты. Баланс на момент в прошлом никогда не меняется. Кешируйте результаты без ограничения срока, чтобы избежать повторных вызовов API.

​

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

​

Ограничения

• Баланс кошельков с несколькими счетами токенов может быть занижен. Баланс считывается из одной последней подходящей транзакции. В распространённом случае, когда для каждого минта существует один связанный счёт токена, результат точен. Если один и тот же минт хранится в нескольких счетах токенов кошелька, а последняя транзакция затронула только часть из них, баланс может быть занижен.
• Точность нативного SOL при очень больших балансах. Для балансов SOL свыше примерно 9 007 199 SOL (2⁵³ лампортов) точность может быть потеряна в вышестоящем сервисе. На суммы токенов это не влияет.
• Точность time/datetime зависит от времени блоков, сообщаемого валидатором, которое может отклоняться на несколько секунд. Для точных и детерминированных результатов используйте slot.
• Один токен на запрос. Пакетная форма для нескольких минтов или «всех балансов на момент T» отсутствует.

​

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