So rufst du den historischen token-Kontostand einer Solana-Wallet ab

​

Übersicht

• Tokens (SPL / Token-2022): Wird aus den token-Kontoständen nach der Transaktion gelesen und über alle token-Konten der Wallet für diesen Mint summiert.
• Natives SOL: Wird aus den Lamport-Kontoständen nach der Transaktion gelesen. Adressiere natives SOL mit dem Pseudo-Mint So11111111111111111111111111111111111111111.

​

Wann du dies verwenden solltest

• PnL-Berechnung: Ermittle die Bestände am Anfang und Ende eines Zeitraums.
• Kostenbasis und Steuerlose: Rekonstruiere Kontostände bei Erwerbs- oder Veräußerungsereignissen.
• Streitbeilegung: Weise nach, was eine Wallet zu einem bestimmten Zeitpunkt hielt.
• Snapshot-Prüfung: Prüfe den Kontostand einer Wallet bei einem Airdrop- oder Governance-Snapshot.
• Buchhaltung und Audits: Rekonstruiere den Wallet-Zustand an Periodengrenzen.

​

Schnellstart

​

token-Kontostand zu einem Zeitstempel

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"

​

token-Kontostand zu einem Datum mit Uhrzeit

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

​

Kontostand von nativem SOL an einem slot

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

​

Abfrageparameter

​

Datums- und Uhrzeitformate

• Nur Datum: 2025-01-10 → Mitternacht UTC
• 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 → Wird wie angegeben berücksichtigt

​

response-Format

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

​

Hinweise zu den Feldern

• wallet: Gibt die abgefragte Wallet-Adresse unverändert zurück.
• mint: Gibt den abgefragten Mint unverändert zurück, bei nativem SOL den SOL-Pseudo-Mint.
• isNative: true, wenn das Ergebnis natives SOL ist.
• balance: Menschenlesbarer Betrag als Dezimalzeichenfolge. Es handelt sich um eine Zeichenfolge und nicht um eine Zahl, damit große Kontostände nicht an Genauigkeit verlieren. Nachgestellte Nullen werden entfernt ("1.5" statt "1.500000").
• balanceRaw: Exakter Betrag in der kleinsten Einheit (Lamports für SOL) als Zeichenfolge.
• decimals: Dezimalstellen des tokens (9 für SOL).
• requested: Gibt die Abfrage unverändert zurück. Wenn datetime verwendet wird, enthält time zusätzlich die aufgelösten Epoch-Sekunden. Dadurch ist die UTC-Interpretation sichtbar.
• asOf: Die Transaktion, aus der der Kontostand gelesen wurde (slot, blockTime, signature).

​

Anwendungsfälle

​

Kontostandsä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üfung 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

• Verwende slot für deterministische Ergebnisse. time und datetime werden über die von Validatoren gemeldeten Blockzeiten aufgelöst, die um einige Sekunden abweichen können. Wenn exakte Reproduzierbarkeit wichtig ist, etwa bei Snapshots oder Audits, frage nach slot ab.
• Parse Kontostände als Zeichenfolgen. balance und balanceRaw sind Zeichenfolgen, um die Genauigkeit zu erhalten. Verwende BigInt(balanceRaw) oder Ganzzahlen mit beliebiger Genauigkeit in deiner Sprache für Berechnungen. Konvertiere die Werte nicht in Gleitkommazahlen.
• Behandle asOf: null als null. Ein null asOf ist eine erfolgreiche response und bedeutet, dass die Wallet bis zum angefragten Zeitpunkt keine Aktivität für diesen token hatte. Behandle dies nicht als Fehler.
• Speichere historische Ergebnisse im Cache. Ein Kontostand zu einem vergangenen Zeitpunkt ändert sich nie. Speichere die Ergebnisse dauerhaft im Cache, um wiederholte API-Aufrufe zu vermeiden.

​

Häufige Fehler

​

Einschränkungen

• Bei Wallets mit mehreren token-Konten kann der Wert zu niedrig sein. Der Kontostand wird aus der einzelnen neuesten passenden Transaktion gelesen. Der übliche Fall mit einem zugeordneten token-Konto pro Mint ist exakt. Wenn eine Wallet denselben Mint über mehrere token-Konten hält und die neueste Transaktion nur einige davon betraf, kann der ermittelte Wert zu niedrig sein.
• Genauigkeit von nativem SOL bei sehr großen Kontoständen. Bei SOL-Kontoständen über etwa 9.007.199 SOL (2⁵³ Lamports) kann vorgelagert Genauigkeit verloren gehen. token-Beträge sind davon nicht betroffen.
• Die Genauigkeit von time/datetime hängt von den durch Validatoren gemeldeten Blockzeiten ab, die um einige Sekunden abweichen können. Verwende slot für exakte, deterministische Ergebnisse.
• Ein token pro request. Es gibt keine Batch-Form für mehrere Mints oder „alle Kontostände zum Zeitpunkt T“.

​

Nächste Schritte