Como Obter o Saldo Histórico de Token de uma Carteira Solana

​

Visão Geral

• Tokens (SPL / Token-2022): lido dos saldos de tokens pós-transação, somados nas contas de token da carteira para essa emissão.
• SOL nativo: lido dos saldos pós-transação de lamports. Enderece o SOL nativo com o pseudo-mint So11111111111111111111111111111111111111111.

​

Quando usar isso

• Cálculo de PnL: determine as posições no início e no final de um período.
• Base de custo e lotes fiscais: reconstrua saldos em eventos de aquisição ou disposição.
• Resolução de disputas: comprove o que uma carteira possuía em um momento específico.
• Verificação de instantâneos: verifique o saldo de uma carteira em um lançamento aéreo ou instantâneo de governança.
• Contabilidade e auditorias: reconstrua o estado da carteira em limites de período.

​

Início Rápido

​

Saldo de token em um timestamp

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"

​

Saldo de token em uma data e hora

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

​

Saldo de SOL nativo em um slot

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

​

Parâmetros de consulta

​

Formatos de data e hora

• Apenas data: 2025-01-10 → meia-noite UTC
• Data + hora: 2025-01-10 19:20:00 ou 2025-01-10T19:20:00 (segundos opcionais) → UTC
• Com fuso horário explícito: 2025-01-10T19:20:00Z, 2025-01-10T19:20:00+02:00, 2025-01-10T19:20:00-05:00 → respeitado como fornecido

​

Formato de resposta

{
  "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"
  }
}

​

Anotações de campo

• wallet: eco do endereço da carteira consultada.
• mint: eco da emissão consultada (o pseudo-mint SOL quando nativo).
• isNative: true quando o resultado é SOL nativo.
• balance: quantidade legível em formato decimal string — uma string, não um número, para que saldos grandes não percam precisão. Zeros à direita são aparados ("1.5", não "1.500000").
• balanceRaw: quantidade exata na menor unidade (lamports para SOL), como uma string.
• decimals: decimais do token (9 para SOL).
• requested: eco da consulta. Quando datetime é usado, INLINE_CODE_PLACEHOLDER_bac8af8ba1420fb1_END também é populado com os segundos de época resolvidos, tornando a interpretação UTC visível.
• asOf: a transação da qual o saldo foi lido (slot, blockTime, signature).

​

Casos de uso

​

Mudança de saldo ao longo de um período

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

​

Verificação de elegibilidade para instantâneo

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

​

Melhores práticas

• Use slot para resultados determinísticos. INLINE_CODE_PLACEHOLDER_bac8af8ba1420fb1_END e datetime são resolvidos via tempos de bloco relatados por validadores, que podem ter um desvio de alguns segundos. Quando a reprodutibilidade exata é importante (instantâneos, auditorias), consulte por slot.
• Analise saldos como strings. balance e balanceRaw são strings para preservar a precisão. Use BigInt(balanceRaw) (ou os inteiros de precisão arbitrária da sua linguagem) para aritmética — não converta para float.
• Trate asOf: null como zero. Um null asOf é uma resposta bem-sucedida, significando que a carteira não teve atividade para aquele token no ponto solicitado. Não trate isso como um erro.
• Armazene em cache os resultados históricos. Um saldo em um ponto passado no tempo nunca muda. Armazene os resultados permanentemente para evitar chamadas de API repetidas.

​

Erros comuns

​

Limitações

• Carteiras com várias contas de token podem subcontar. O saldo é lido da transação única mais recente correspondente. O caso comum — uma conta de token associada por emissão — é exato. Uma carteira que possui a mesma emissão em várias contas de token, onde a última transação tocou apenas algumas delas, pode ser subcontada.
• Precisão de SOL nativo para saldos muito grandes. Para saldos de SOL além de ~ 9.007.199 SOL (2⁵³ lamports), a precisão pode ser perdida a montante. Quantidades de token não são afetadas.
• Precisão de INLINE_CODE_PLACEHOLDER_bac8af8ba1420fb1_END/datetime depende dos tempos de bloco relatados pelos validadores, que podem ter um desvio de alguns segundos. Use slot para resultados exatos e determinísticos.
• Um token por solicitação. Não há forma de múltiplas emissões ou “todos os saldos no tempo T” em lote.

​

Próximos passos