So ermitteln Sie den historischen Token-Bestand eines Solana-Wallets

​

Übersicht

• 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

• 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

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"

​

Tokenbestand zu einem Datum

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

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

​

Abfrageparameter

​

Datumszeitformate

• 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

​

Antwortformat

{
  "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).

​

Anwendungsfälle

​

Bestandsänderung über einen Zeitraum

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

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

​

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