Comment obtenir le solde historique d'un portefeuille Solana

​

Aperçu

• Jetons (SPL / Token-2022) : lu à partir des soldes post-transaction des jetons, sommé sur les comptes de jetons du portefeuille pour cette frappe.
• SOL natif : lu à partir des soldes post-transaction des lamports. Adressez SOL natif avec le pseudo-frappe So11111111111111111111111111111111111111111.

​

Quand l’utiliser

• Calcul PnL : déterminer les avoirs au début et à la fin d’une période.
• Base de coût et lots fiscaux : reconstruire les soldes lors d’événements d’acquisition ou de cession.
• Résolution de litige : prouver ce qu’un portefeuille détenait à un moment précis.
• Vérification de capture instantanée : vérifier le solde d’un portefeuille lors d’un largage ou d’une capture de gouvernance.
• Comptabilité et audits : reconstruire l’état du portefeuille aux limites de période.

​

Démarrage rapide

​

Solde de jetons à un moment donné

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"

​

Solde de jetons à une date/heure

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

​

Solde de SOL natif à un slot

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

​

Paramètres de requête

​

Formats de date/heure

• Date uniquement : 2025-01-10 → UTC minuit
• Date + heure : 2025-01-10 19:20:00 ou 2025-01-10T19:20:00 (secondes optionnelles) → UTC
• Avec fuseau horaire explicite : 2025-01-10T19:20:00Z, 2025-01-10T19:20:00+02:00, 2025-01-10T19:20:00-05:00 → respecté tel que donné

​

Format de réponse

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

​

Notes sur les champs

• wallet : écho de l’adresse du portefeuille interrogée.
• mint : écho de la frappe interrogée (la pseudo-frappe SOL lorsque natif).
• isNative : true lorsque le résultat est SOL natif.
• balance : montant lisible par l’homme comme une chaîne décimale — une chaîne, pas un nombre, pour que les grands soldes ne perdent pas en précision. Les zéros finaux sont supprimés ("1.5", pas "1.500000").
• balanceRaw : montant exact dans l’unité la plus petite (lamports pour SOL), sous forme de chaîne.
• decimals : décimales du jeton (9 pour SOL).
• requested : écho de la requête. Lorsque datetime est utilisé, time est également rempli avec les secondes d’époque résolues, rendant visible l’interprétation UTC.
• asOf : la transaction à partir de laquelle le solde a été lu (slot, blockTime, signature).

​

Cas d’utilisation

​

Changement de solde sur une période

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

​

Vérification d’éligibilité à une capture instantanée

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

​

Bonnes pratiques

• Utilisez slot pour des résultats déterministes. time et datetime se résolvent par les temps de bloc signalés par le validateur, qui peuvent dériver de quelques secondes. Lorsque la reproductibilité exacte est importante (captures, audits), interrogez par slot.
• Analysez les soldes en tant que chaînes. balance et balanceRaw sont des chaînes pour préserver la précision. Utilisez BigInt(balanceRaw) (ou les entiers à précision arbitraire de votre langage) pour l’arithmétique — ne convertissez pas en float.
• Traitez asOf: null comme un zéro. Un null asOf est une réponse réussie signifiant que le portefeuille n’avait aucune activité pour ce jeton à la date demandée. Ne le traitez pas comme une erreur.
• Mettre en cache les résultats historiques. Un solde à un moment passé ne change jamais. Mettez en cache les résultats en permanence pour éviter des appels API répétés.

​

Erreurs courantes

​

Limitations

• Les portefeuilles multi-comptes de jetons peuvent être sous-comptés. Le solde est lu à partir de la transaction unique correspondante la plus récente. Le cas commun — un compte de jetons associé par frappe — est exact. Un portefeuille détenant la même frappe sur plusieurs comptes de jetons, où la dernière transaction n’en touchait que certains, peut être sous-compté.
• Précision du SOL natif pour les très grands soldes. Pour les soldes SOL au-delà de ~9 007 199 SOL (2⁵³ lamports), la précision peut être perdue en amont. Les montants des jetons ne sont pas affectés.
• La précision de time/datetime dépend des temps de bloc signalés par le validateur, qui peuvent dériver de quelques secondes. Utilisez slot pour des résultats exacts et déterministes.
• Un seul jeton par requête. Il n’y a pas de formulaire batch multi-frappes ou “tous les soldes à l’heure T”.

​

Prochaines étapes