Cómo obtener el saldo histórico de tokens de una billetera de Solana

​

Descripción general

• Tokens (SPL / Token-2022): se obtiene de los saldos de tokens posteriores a la transacción, sumados entre las cuentas de tokens de la billetera para ese mint.
• SOL nativo: se obtiene de los saldos de lamports posteriores a la transacción. Especifica SOL nativo con el pseudomint So11111111111111111111111111111111111111111.

​

Cuándo usarlo

• Cálculo de PnL: determina las tenencias al inicio y al final de un período.
• Base de costo y lotes fiscales: reconstruye los saldos en eventos de adquisición o disposición.
• Resolución de disputas: demuestra qué tenía una billetera en un momento específico.
• Verificación de snapshots: comprueba el saldo de una billetera durante un airdrop o snapshot de gobernanza.
• Contabilidad y auditorías: reconstruye el estado de una billetera en los límites de un período.

​

Inicio rápido

​

Saldo de un token en una marca de tiempo

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 un token en una fecha y 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 en un 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 fecha y hora

• Solo fecha: 2025-01-10 → medianoche UTC
• Fecha y hora: 2025-01-10 19:20:00 o 2025-01-10T19:20:00 (los segundos son opcionales) → UTC
• Con zona horaria explícita: 2025-01-10T19:20:00Z, 2025-01-10T19:20:00+02:00, 2025-01-10T19:20:00-05:00 → se respeta tal como se indica

​

Formato de respuesta

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

​

Notas sobre los campos

• wallet: copia de la dirección de billetera consultada.
• mint: copia del mint consultado (el pseudomint de SOL cuando es nativo).
• isNative: true cuando el resultado es SOL nativo.
• balance: cantidad legible como cadena decimal; es una cadena, no un número, para que los saldos grandes no pierdan precisión. Se eliminan los ceros finales ("1.5", no "1.500000").
• balanceRaw: cantidad exacta en la unidad más pequeña (lamports para SOL), como cadena.
• decimals: decimales del token (9 para SOL).
• requested: copia de la consulta. Cuando se usa datetime, time también se completa con los segundos de época calculados, lo que hace visible la interpretación UTC.
• asOf: la transacción de la que se obtuvo el saldo (slot, blockTime, signature).

​

Casos de uso

​

Cambio de saldo durante un 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 };
};

​

Verificación de elegibilidad para un snapshot

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

​

Prácticas recomendadas

• Usa slot para obtener resultados deterministas. time e datetime se resuelven mediante las horas de bloque informadas por los validadores, que pueden desviarse unos segundos. Cuando sea importante poder reproducir los resultados de forma exacta (snapshots, auditorías), consulta mediante slot.
• Analiza los saldos como cadenas. balance e balanceRaw son cadenas para conservar la precisión. Usa BigInt(balanceRaw) (o los enteros de precisión arbitraria de tu lenguaje) para las operaciones aritméticas; no los conviertas a números de punto flotante.
• Interpreta asOf: null como cero. Un null asOf es una respuesta correcta que indica que la billetera no tenía actividad para ese token en el momento solicitado. No lo trates como un error.
• Almacena en caché los resultados históricos. Un saldo en un momento del pasado nunca cambia. Almacena los resultados en caché de forma permanente para evitar llamadas repetidas a la API.

​

Errores comunes

​

Limitaciones

• Las billeteras con varias cuentas de tokens pueden mostrar un saldo inferior al real. El saldo se obtiene de la transacción coincidente más reciente. El caso habitual, una cuenta de token asociada por mint, es exacto. Si una billetera tiene el mismo mint en varias cuentas de tokens y la transacción más reciente solo afectó a algunas, el saldo puede ser inferior al real.
• Precisión de SOL nativo para saldos muy grandes. En los saldos de SOL superiores a ~9,007,199 SOL (2⁵³ lamports), podría perderse precisión en los servicios ascendentes. Esto no afecta a las cantidades de tokens.
• La precisión de time/datetime depende de las horas de bloque informadas por los validadores, que pueden desviarse unos segundos. Usa slot para obtener resultados exactos y deterministas.
• Un solo token por solicitud. No existe una forma por lotes para varios mints ni para «todos los saldos en el momento T».

​

Próximos pasos