> ## 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. # So ermitteln Sie den historischen Token-Bestand eines Solana-Wallets > Abfrage des Guthabens eines Wallets für jeden Token oder nativen SOL zu einem vergangenen Zeitpunkt, Datum oder Slot. Ideal für PnL, Kostenbasis, Steuerberichte und die Rekonstruktion des Wallet-Zustands. Die Wallet API ist in der Beta-Phase. Endpunkte und Antwortformate können sich ändern. ## Übersicht Der Endpunkt für den historischen Bestand beantwortet: **Wie war der Kontostand dieses Wallets eines bestimmten Tokens (oder nativen SOL) zu einem bestimmten Zeitpunkt in der Vergangenheit?** Während der [Balances](/docs/de/wallet-api/balances) Endpunkt *aktuelle* Bestände meldet, meldet `balance-at` Bestände zu jedem beliebigen Zeitpunkt, Datum oder Slot. Er findet die **einzige neueste Transaktion zum oder vor dem angeforderten Zeitpunkt**, die das Wallet und den Token betrifft, und liest dann den **Post-Transaktionsbestand** des Wallets aus dieser Transaktion aus. Der Post-Bestand einer Transaktion ist der Bestand, der von dieser Transaktion bis zur nächsten gehalten wurde. Der „Kontostand zum Zeitpunkt T“ ist also der Post-Bestand der letzten relevanten Transaktion mit einem Blockzeitpunkt (oder Slot) zum oder vor T. Für das typische Wallet ist dies ein exakter Wert, keine Schätzung. * **Tokens (SPL / Token-2022)**: Von den Post-Token-Beständen der Transaktion gelesen, summiert über die Token-Konten des Wallets für diesen Mint. * **Nativer SOL**: Aus den Lamport-Post-Beständen der Transaktion gelesen. Adresse nativer SOL mit dem Pseudo-Mint `So11111111111111111111111111111111111111111`. ## Wann man das verwenden soll Verwenden Sie die Historical Balance API für: * **PnL-Berechnung**: Bestimmung der Bestände zu Beginn und Ende eines Zeitraums. * **Kostenbasis und Steuerlots**: Rekonstruktion von Beständen bei Erwerbs- oder Veräußerungsereignissen. * **Konfliktlösung**: Nachweis, was ein Wallet zu einem bestimmten Zeitpunkt gehalten hat. * **Snapshot-Verifizierung**: Überprüfung des Guthabens eines Wallets bei einem Airdrop- oder Governance-Snapshot. * **Buchhaltung und Prüfungen**: Rekonstruktion des Wallet-Zustands an Periodengrenzen. ## Schnellstart ### Tokenbestand zu einem Zeitpunkt Ermitteln Sie den USDC-Bestand eines Wallets zu einem Unix-Zeitstempel: ```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" ``` ### Tokenbestand zu einem Datum Geben Sie ein menschenlesbares Datum anstelle eines Zeitstempels an. Denken Sie daran, den Leerraum als `%20` zu URL-kodieren: ```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" ``` ### Nativer SOL-Bestand zu einem Slot Verwenden Sie für nativen SOL den Pseudo-Mint `So11111111111111111111111111111111111111111`. Slot-basierte Abfragen sind exakt und deterministisch: ```bash theme={"system"} curl "https://api.helius.xyz/v1/wallet/5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9/balance-at?mint=So11111111111111111111111111111111111111111&slot=313000000&api-key=YOUR_API_KEY" ``` ## Abfrageparameter | Param | Erforderlich | Typ | Beschreibung | | ---------- | ------------ | ------ | ------------------------------------------------------------------------------------------------ | | `mint` | Ja | string | Token-Mint-Adresse. Für nativen SOL verwenden Sie `So11111111111111111111111111111111111111111`. | | `time` | Eines von | int | Unix-Zeitstempel in **Sekunden**. Bestand zu diesem Zeitpunkt. | | `datetime` | Eines von | string | Datumszeit-String, z.B. `2025-01-10 19:20:00`. Standardmäßig UTC. | | `slot` | Eines von | int | Slot-Nummer. Bestand zu diesem Slot. Genau und deterministisch. | Genau **eines** von `time`, `datetime` oder `slot` muss angegeben werden. Das Angeben von null oder mehr als einem erfolgt ein `400` Fehler. ### Datumszeitformate Akzeptierte Formate: * Nur Datum: `2025-01-10` → UTC Mitternacht * Datum + Uhrzeit: `2025-01-10 19:20:00` oder `2025-01-10T19:20:00` (Sekunden optional) → UTC * Mit expliziter Zeitzone: `2025-01-10T19:20:00Z`, `2025-01-10T19:20:00+02:00`, `2025-01-10T19:20:00-05:00` → wie angegeben berücksichtigt Ungültige oder nicht unterstützte Formate (`01/10/2025`, `2025-13-10`, `2025-02-30`) geben einen `400` Fehler zurück. Datumszeiten werden standardmäßig als UTC interpretiert. Ein bloßes Datum wie `2025-01-10 19:20:00` wird als UTC und nicht als Ihre lokale Zeit behandelt. Fügen Sie eine explizite Zeitzonenverschiebung hinzu, wenn Sie etwas anderes meinen. Das `requested.time` Feld der Antwort zeigt die gelösten Epochensekunden, damit Sie die Interpretation überprüfen können. ## Antwortformat ```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" } } ``` ### Feldhinweise * **`wallet`**: Echo der abgefragten Wallet-Adresse. * **`mint`**: Echo des abgefragten Mints (der SOL Pseudo-Mint, wenn nativ). * **`isNative`**: `true`, wenn das Ergebnis nativer SOL ist. * **`balance`**: Menschlich lesbare Menge als **Dezimalzeichenkette** — eine Zeichenkette, keine Zahl, damit große Bestände keine Genauigkeit verlieren. Nachkommende Nullen werden abgeschnitten (`"1.5"`, nicht `"1.500000"`). * **`balanceRaw`**: Exakte Menge in der kleinsten Einheit (Lamports für SOL), als Zeichenkette. * **`decimals`**: Token Dezimalstellen (9 für SOL). * **`requested`**: Echo der Abfrage. Wenn `datetime` verwendet wird, wird auch `time` mit den gelösten Epochensekunden befüllt, wodurch die UTC-Interpretation sichtbar wird. * **`asOf`**: Die Transaktion, von der der Bestand gelesen wurde (`slot`, `blockTime`, `signature`). `asOf: null` bedeutet Null, nicht ein Fehler. Wenn das Wallet keine Übereinstimmende Transaktion zum oder vor dem angeforderten Zeitpunkt hatte, gibt der Endpunkt `200` mit `balance: "0"` und `asOf: null` zurück — das Wallet hatte den Token bis dahin einfach nicht gehalten. ## Anwendungsfälle ### Bestandsänderung über einen Zeitraum Vergleichen Sie Bestände zu zwei Zeitpunkten: ```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 }; }; ``` ### Prüfen der Snapshot-Berechtigung Verifizieren Sie, dass ein Wallet einen Token zu einem Snapshot-Slot gehalten hat: ```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; }; ``` ## Best Practices * **Verwenden Sie `slot` für deterministische Ergebnisse.** `time` und `datetime` werden über von Validatoren gemeldete Blockzeiten aufgelöst, die um einige Sekunden abweichen können. Wenn eine genaue Reproduzierbarkeit wichtig ist (Snapshots, Prüfungen), fragen Sie nach `slot`. * **Parsen Sie Bestände als Zeichenketten.** `balance` und `balanceRaw` sind Zeichenketten, um die Genauigkeit zu bewahren. Verwenden Sie `BigInt(balanceRaw)` (oder die willkürliche Ganzzahlen Ihrer Sprache) für Berechnungen — nicht in eine Fließkommazahl umwandeln. * **Behandeln Sie `asOf: null` als Null.** Ein `null` `asOf` ist eine erfolgreiche Antwort, die bedeutet, dass das Wallet bis zum angeforderten Zeitpunkt keine Aktivität für diesen Token hatte. Behandeln Sie es nicht als Fehler. * **Cache historische Ergebnisse.** Ein Bestand zu einem vergangenen Zeitpunkt ändert sich nie. Speichern Sie Ergebnisse dauerhaft im Cache, um wiederholte API-Aufrufe zu vermeiden. ## Häufige Fehler | Fehlercode | Beschreibung | Lösung | | ---------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | 400 | Fehlende `mint`, ungültiger Mint, null oder mehrere von `time`/`datetime`/`slot`, oder nicht analysierbarer `datetime` | Geben Sie einen gültigen Mint und genau einen Zeitpunktsparameter an | | 401 | Fehlender oder ungültiger API-Schlüssel | Überprüfen Sie, ob Ihr API-Schlüssel in der Anfrage enthalten ist | | 404 | Ungültige Wallet-Adresse im Pfad | Verifizieren Sie, dass es sich um eine gültige base58 Solana-Adresse handelt | | 429 | Ratenlimit überschritten | Reduzieren Sie die Anfragenfrequenz oder aktualisieren Sie Ihren Plan | | 502 | Upstream-RPC-Fehler oder Timeout | Erneut versuchen mit exponentiellem Backoff | ## Einschränkungen * **Multi-Token-Account Wallets können unterzählt sein.** Der Bestand wird aus der einzigen neuesten passenden Transaktion gelesen. Der häufige Fall — ein zugeordneter Token-Account pro Mint — ist exakt. Ein Wallet, das denselben Mint über mehrere Token-Konten hält, bei dem die letzte Transaktion nur einige von ihnen berührte, kann unterzählt sein. * **Nativer SOL-Genauigkeit für sehr große Bestände.** Für SOL-Bestände über \~9.007.199 SOL (2⁵³ Lamports) kann genauigkeit stromaufwärts verloren gehen. Token-Beträge sind nicht betroffen. * **`time`/`datetime` Genauigkeit hängt von den von Validatoren gemeldeten Blockzeiten ab**, die um einige Sekunden abweichen können. Verwenden Sie `slot` für exakte, deterministische Ergebnisse. * **Einzelner Token pro Anfrage.** Es gibt keine Multi-Mint- oder „alle Bestände zu Zeitpunkt T“-Batch-Form. ## Nächste Schritte Abrufen der aktuellen Token- und NFT-Bestände eines Wallets mit USD-Werten. Alle Wallet-API-Endpunkte und gemeinsamen Konventionen. Anforderungs- und Antwortschemas für historische Bestände.