> ## 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. # Comment obtenir le solde historique d'un portefeuille Solana > Interrogez le solde d'un portefeuille pour un jeton ou SOL natif à un moment, une date ou un slot passés. Idéal pour PnL, base de coût, déclarations fiscales et reconstitution de l'état du portefeuille. L'API Wallet est en version bêta. Les points de terminaison et les formats de réponse peuvent changer. ## Aperçu Le point de terminaison de solde historique répond : **quel était le solde de ce portefeuille pour un jeton spécifique (ou SOL natif) à un moment précis dans le passé ?** Tandis que le point de terminaison [Balances](/docs/fr/wallet-api/balances) rapporte les avoirs *actuels*, `balance-at` rapporte les avoirs à tout moment, date ou slot. Il trouve la **transaction unique la plus récente à ou avant le moment demandé** qui impliquait le portefeuille et le jeton, puis lit le **solde post-transaction** du portefeuille à partir de cette transaction. Le solde post-transaction est le solde détenu après cette transaction jusqu'à la suivante, donc "solde à l'heure T" est le solde post-transaction de la dernière transaction pertinente avec un bloc horaire (ou slot) à ou avant T. Pour un portefeuille typique, il s'agit d'une valeur exacte, pas une estimation. * **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 Utilisez l'API de solde historique pour : * **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é Obtenez le solde USDC d'un portefeuille à un horodatage 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" ``` ### Solde de jetons à une date/heure Passez une date/heure lisible au lieu d'un horodatage. N'oubliez pas d'encoder l'espace en URL comme `%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" ``` ### Solde de SOL natif à un slot Pour SOL natif, utilisez le pseudo-frappe `So11111111111111111111111111111111111111111`. Les requêtes basées sur les slots sont exactes et déterministes : ```bash theme={"system"} curl "https://api.helius.xyz/v1/wallet/5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9/balance-at?mint=So11111111111111111111111111111111111111111&slot=313000000&api-key=YOUR_API_KEY" ``` ## Paramètres de requête | Param | Requis | Type | Description | | ---------- | ------ | ------ | --------------------------------------------------------------------------------------------------- | | `mint` | Oui | string | Adresse de frappe du jeton. Pour SOL natif, utilisez `So11111111111111111111111111111111111111111`. | | `time` | Un de | int | Horodatage Unix en **secondes**. Solde à ce moment. | | `datetime` | Un de | string | Chaîne de date/heure, par ex. `2025-01-10 19:20:00`. UTC par défaut. | | `slot` | Un de | int | Numéro de slot. Solde à ce slot. Exact et déterministe. | Exactement **un** de `time`, `datetime`, ou `slot` doit être fourni. Fournir zéro ou plus d'un retourne une erreur `400`. ### Formats de date/heure Formats acceptés : * 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é Les formats non valides ou non pris en charge (`01/10/2025`, `2025-13-10`, `2025-02-30`) renvoient une erreur `400`. Les dates/ heures sont interprétées par défaut en UTC. Une date/heure simple comme `2025-01-10 19:20:00` est traitée en UTC, pas votre heure locale. Incluez un décalage de fuseau horaire explicite si vous souhaitez autre chose. Le champ `requested.time` de la réponse montre les secondes d'époque résolues pour que vous puissiez vérifier l'interprétation. ## Format de réponse ```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" } } ``` ### 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`). `asOf: null` signifie zéro, pas une erreur. Lorsque le portefeuille n'avait aucune transaction correspondante à ou avant le moment demandé, le point de terminaison renvoie `200` avec `balance: "0"` et `asOf: null` — le portefeuille n'avait tout simplement pas détenu le jeton à ce moment-là. ## Cas d'utilisation ### Changement de solde sur une période Comparer les avoirs à deux moments différents : ```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 }; }; ``` ### Vérification d'éligibilité à une capture instantanée Vérifiez qu'un portefeuille détenait un jeton à un slot de capture instantanée : ```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; }; ``` ## 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 | Code d'erreur | Description | Solution | | ------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | 400 | Manque `mint`, mauvaise frappe, zéro ou plusieurs de `time`/`datetime`/`slot`, ou `datetime` inanalysable | Fournissez une frappe valide et exactement un paramètre de point temporel | | 401 | Clé API manquante ou invalide | Vérifiez que votre clé API est incluse dans la requête | | 404 | Adresse du portefeuille invalide dans le chemin | Vérifiez que l'adresse est une adresse Solana base58 valide | | 429 | Limite de débit dépassée | Réduisez la fréquence des requêtes ou améliorez votre plan | | 502 | Erreur ou expiration RPC en amont | Réessayez avec un backoff exponentiel | ## 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 Obtenez les avoirs actuels en jetons et NFT d'un portefeuille avec des valeurs en USD. Tous les points de terminaison de l'API Wallet et conventions partagées. Schémas de requête et de réponse pour le solde historique.