> ## 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. # Cómo obtener el saldo histórico de tokens de una billetera de Solana > Consulta el saldo de cualquier token o SOL nativo de una billetera en una marca de tiempo, fecha y hora o slot del pasado. Ideal para PnL, base de costo, informes fiscales y reconstrucción del estado de una billetera. La Wallet API está en fase beta. Los endpoints y formatos de respuesta pueden cambiar. ## Descripción general El endpoint Historical Balance responde: **¿cuál era el saldo de un token específico (o SOL nativo) de esta billetera en un momento específico del pasado?** Mientras que el endpoint [Balances](/docs/es/wallet-api/balances) informa las tenencias *actuales*, `balance-at` informa las tenencias correspondientes a cualquier marca de tiempo, fecha y hora o slot. Busca la **transacción más reciente, en el momento solicitado o antes de este,** que involucró a la billetera y al token. Luego, obtiene de esa transacción el **saldo de la billetera posterior a la transacción**. El saldo posterior de una transacción es el que se mantuvo desde esa transacción hasta la siguiente. Por lo tanto, el «saldo en el momento T» es el saldo posterior de la última transacción relevante cuya hora de bloque (o slot) sea igual o anterior a T. Para una billetera típica, este es un valor exacto, no una estimación. * **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 Usa la API Historical Balance para lo siguiente: * **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 Obtén el saldo de USDC de una billetera en una marca de tiempo Unix: ```javascript theme={"system"} 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 ); ``` ```python theme={"system"} 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 ) ``` ```bash theme={"system"} 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 Envía una fecha y hora legible en lugar de una marca de tiempo. Recuerda codificar el espacio en la URL como `%20`: ```bash theme={"system"} 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 Para SOL nativo, usa el pseudomint `So11111111111111111111111111111111111111111`. Las consultas basadas en slots son exactas y deterministas: ```bash theme={"system"} curl "https://api.helius.xyz/v1/wallet/5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9/balance-at?mint=So11111111111111111111111111111111111111111&slot=313000000&api-key=YOUR_API_KEY" ``` ## Parámetros de consulta | Parámetro | Obligatorio | Tipo | Descripción | | ---------- | ------------ | ------ | ------------------------------------------------------------------------------------------------ | | `mint` | Sí | string | Dirección de mint del token. Para SOL nativo, usa `So11111111111111111111111111111111111111111`. | | `time` | Uno de ellos | int | Marca de tiempo Unix en **segundos**. Saldo en ese momento. | | `datetime` | Uno de ellos | string | Cadena de fecha y hora, p. ej., `2025-01-10 19:20:00`. UTC de forma predeterminada. | | `slot` | Uno de ellos | int | Número de slot. Saldo en ese slot. Exacto y determinista. | Debes proporcionar exactamente **uno** de los siguientes: `time`, `datetime` o `slot`. Si no proporcionas ninguno o proporcionas más de uno, se devuelve un error `400`. ### Formatos de fecha y hora Formatos aceptados: * 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 Los formatos no válidos o no compatibles (`01/10/2025`, `2025-13-10`, `2025-02-30`) devuelven un error `400`. De forma predeterminada, las fechas y horas se interpretan como UTC. Una fecha y hora sin zona horaria, como `2025-01-10 19:20:00`, se considera UTC, no tu hora local. Incluye un desfase de zona horaria explícito si quieres indicar otra cosa. El campo `requested.time` de la respuesta muestra los segundos de época calculados para que puedas verificar la interpretación. ## Formato de respuesta ```json theme={"system"} { "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`). `asOf: null` significa cero, no un error. Cuando la billetera no tenía ninguna transacción coincidente en el momento solicitado o antes, el endpoint devuelve `200` con `balance: "0"` e `asOf: null`. Esto simplemente significa que la billetera aún no tenía el token en ese momento. ## Casos de uso ### Cambio de saldo durante un período Compara las tenencias en dos momentos: ```javascript theme={"system"} 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 Verifica que una billetera tenía un token en el slot del snapshot: ```javascript theme={"system"} 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 | Código de error | Descripción | Solución | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | 400 | Falta `mint`, el mint no es válido, se proporcionaron cero o varios de `time`/`datetime`/`slot`, o `datetime` no se puede analizar | Proporciona un mint válido y exactamente un parámetro de momento específico | | 401 | La clave de API no está presente o no es válida | Comprueba que tu clave de API esté incluida en la solicitud | | 404 | La dirección de billetera de la ruta no es válida | Verifica que la dirección sea una dirección de Solana base58 válida | | 429 | Se superó el límite de solicitudes | Reduce la frecuencia de las solicitudes o mejora tu plan | | 502 | Error de RPC ascendente o tiempo de espera agotado | Reintenta con espera exponencial | ## 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 Obtén las tenencias actuales de tokens y NFT de una billetera con sus valores en USD. Todos los endpoints de Wallet API y sus convenciones compartidas. Esquemas de solicitud y respuesta para el saldo histórico.