So rufst du Wallet-Guthaben ab

Die Wallet API befindet sich in der Betaphase. Endpoints und Formate der response können sich ändern.

Übersicht

Der Endpoint für Wallet-Guthaben ruft alle Bestände einer Solana-Wallet ab — SOL, SPL Token, Token-2022 und NFTs — einschließlich Preisen in USD, Logos und Metadaten. Die Ergebnisse sind absteigend nach USD-Wert sortiert: Token mit Preisdaten erscheinen zuerst, danach Token ohne Preisangaben. Der Endpoint gibt pro request bis zu 100 Token zurück. Die Seitennavigation erfolgt daher manuell. Rufe mit dem Parameter page weitere Seiten ab und prüfe anhand von pagination.hasMore, ob weitere Ergebnisse verfügbar sind. Jeder request entspricht einem einzelnen API-Aufruf und kostet 100 Credits.

Die USD-Preise stammen aus DAS und werden stündlich aktualisiert. Sie decken die 10.000 Token mit der höchsten Marktkapitalisierung ab. pricePerToken und usdValue sind für nicht unterstützte Token null. Die Preise sind Schätzwerte und keine Echtzeit-Marktkurse.

Wann du dies verwenden solltest

Verwende die Wallet Balances API, wenn du Folgendes tun möchtest:

Portfolio-Bestände anzeigen: Zeige Nutzern ihre vollständigen Bestände an Token und NFTs.
USD-Werte berechnen: Ermittle Portfoliobewertungen mit stündlich aktualisierten Preisen.
Wallet-Oberflächen erstellen: Stelle Daten für Wallet-Dashboards und Asset-Listen bereit.
Bestände an Token verfolgen: Überwache bestimmte Guthaben an Token über mehrere Wallets hinweg.
Portfolio analysieren: Analysiere die Verteilung und Konzentration der Bestände.
Steuerberichte erstellen: Erzeuge Momentaufnahmen der Bestände für Steuerzwecke.

Schnellstart

Einfache Guthabenabfrage

Rufe alle Guthaben an Token einer Wallet mit ihren USD-Werten ab:

JavaScript
Python
cURL

const getWalletBalances = async (address) => {
  const url = `https://api.helius.xyz/v1/wallet/${address}/balances?api-key=YOUR_API_KEY`;

  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  const data = await response.json();

  const solBalance = data.balances[0]; // SOL is always first when showNative=true
  console.log(`SOL Balance: ${solBalance.balance} SOL ($${solBalance.usdValue})`);
  console.log(`Page ${data.pagination.page} Total Value: $${data.totalUsdValue}`);
  console.log(`Token Count (this page): ${data.balances.length}`);

  // Display top holdings
  data.balances.slice(0, 5).forEach(token => {
    console.log(`${token.symbol}: ${token.balance} ($${token.usdValue || 'N/A'})`);
  });

  return data;
};

getWalletBalances("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY");

import requests

def get_wallet_balances(address: str):
    url = f"https://api.helius.xyz/v1/wallet/{address}/balances"
    headers = {"X-Api-Key": "YOUR_API_KEY"}

    response = requests.get(url, headers=headers)
    response.raise_for_status()

    data = response.json()

    sol_balance = data['balances'][0]  # SOL is always first when showNative=true
    print(f"SOL Balance: {sol_balance['balance']} SOL (${sol_balance['usdValue']})")
    print(f"Page {data['pagination']['page']} Total Value: ${data['totalUsdValue']}")
    print(f"Token Count (this page): {len(data['balances'])}")

    # Display top holdings
    for token in data['balances'][:5]:
        usd_value = token.get('usdValue', 'N/A')
        print(f"{token['symbol']}: {token['balance']} (${usd_value})")

    return data

get_wallet_balances("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY")

curl "https://api.helius.xyz/v1/wallet/86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY/balances?api-key=YOUR_API_KEY"

NFTs in die Ergebnisse aufnehmen

Rufe mit showNfts=true sowohl Token als auch NFTs in einem einzigen request ab:

JavaScript
Python

const getWalletWithNfts = async (address) => {
  const url = `https://api.helius.xyz/v1/wallet/${address}/balances?api-key=YOUR_API_KEY&showNfts=true`;

  const response = await fetch(url);
  const data = await response.json();

  console.log(`Tokens: ${data.balances.length}`);
  console.log(`NFTs: ${data.nfts?.length || 0}`);

  // Display NFTs
  data.nfts?.forEach(nft => {
    console.log(`NFT: ${nft.name || 'Unnamed'} (${nft.collectionName || 'Unknown Collection'})`);
  });

  return data;
};

getWalletWithNfts("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY");

def get_wallet_with_nfts(address: str):
    url = f"https://api.helius.xyz/v1/wallet/{address}/balances"
    params = {
        "api-key": "YOUR_API_KEY",
        "showNfts": "true"
    }

    response = requests.get(url, params=params)
    response.raise_for_status()

    data = response.json()

    print(f"Tokens: {len(data['balances'])}")
    print(f"NFTs: {len(data.get('nfts', []))}")

    # Display NFTs
    for nft in data.get('nfts', []):
        name = nft.get('name', 'Unnamed')
        collection = nft.get('collectionName', 'Unknown Collection')
        print(f"NFT: {name} ({collection})")

    return data

get_wallet_with_nfts("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY")

Ergebnisse filtern

Grenze die zurückgegebenen Daten mit Abfrageparametern ein:

// Only show tokens with non-zero balances
const url = `https://api.helius.xyz/v1/wallet/${address}/balances?api-key=YOUR_API_KEY&showZeroBalance=false`;

// Exclude native SOL from results
const url = `https://api.helius.xyz/v1/wallet/${address}/balances?api-key=YOUR_API_KEY&showNative=false`;

// Get only the top 50 tokens by value
const url = `https://api.helius.xyz/v1/wallet/${address}/balances?api-key=YOUR_API_KEY&limit=50`;

Abfrageparameter

Parameter	Typ	Standardwert	Beschreibung
`page`	integer	1	Seitennummer für die Seitennavigation (beginnend bei 1)
`limit`	integer	100	Maximale Anzahl an Token pro Seite (1–100)
`showZeroBalance`	boolean	false	Token mit einem Guthaben von null einbeziehen
`showNative`	boolean	true	Natives SOL in die Ergebnisse aufnehmen
`showNfts`	boolean	false	NFTs in die Ergebnisse aufnehmen (maximal 100, nur auf der ersten Seite)

Format der response

{
  "balances": [
    {
      "mint": "So11111111111111111111111111111111111111111",
      "symbol": "SOL",
      "name": "Solana",
      "balance": 1.5,
      "decimals": 9,
      "pricePerToken": 145.32,
      "usdValue": 217.98,
      "logoUri": "https://raw.githubusercontent.com/solana-labs/token-list/main/assets/mainnet/So11111111111111111111111111111111111111112/logo.png",
      "tokenProgram": "spl-token"
    },
    {
      "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "symbol": "USDC",
      "name": "USD Coin",
      "balance": 1000.5,
      "decimals": 6,
      "pricePerToken": 1.0,
      "usdValue": 1000.5,
      "logoUri": "https://example.com/usdc-logo.png",
      "tokenProgram": "spl-token"
    }
  ],
  "nfts": [
    {
      "mint": "7Xq8wXyXVqfBPPqVJjPDwG9zN5wCVxBYZ6z7vPYBzr6F",
      "name": "Degen Ape #1234",
      "imageUri": "https://example.com/nft.png",
      "collectionName": "Degen Ape Academy",
      "collectionAddress": "DegN1dXmU2uYa4n7U9qTh7YNYpK4u8L9qXx7XqYqJfGH",
      "compressed": false
    }
  ],
  "totalUsdValue": 1218.48,
  "pagination": {
    "page": 1,
    "limit": 100,
    "hasMore": true
  }
}

Hinweise zu den Feldern

balance: menschenlesbarer Betrag, bereits an die Dezimalstellen angepasst — 1.5 bedeutet 1,5 SOL und 1000.5 bedeutet 1000,5 USDC. Eine Umrechnung von Lamports ist nicht erforderlich. Dieser Endpoint stellt kein unverarbeitetes Feld amountRaw bereit. Wenn du den exakten ganzzahligen Wert benötigst, berechne ihn als Math.round(balance * 10 ** decimals).
decimals: dient nur als Referenz.
pricePerToken / usdValue: null für Token ohne Preisdaten von DAS (siehe Preishinweis oben).
totalUsdValue: gesamter USD-Wert nur für die aktuelle Seite der response. Um den Wert des gesamten Portfolios zu ermitteln, durchlaufe alle Seiten und addiere usdValue für jedes Guthaben.
tokenProgram: gibt an, welchen Standard das jeweilige Token verwendet — spl-token (klassisches SPL Token) oder token-2022 (Token Extensions). Beide werden vollständig unterstützt.

Anwendungsfälle

Portfolio-Dashboard erstellen

Zeige die Bestände der Nutzer mit USD-Werten an:

const renderPortfolio = async (address) => {
  const { balances, totalUsdValue } = await getWalletBalances(address);

  console.log(`Current Page Value: $${totalUsdValue.toLocaleString()}`);
  console.log(`\nTop Holdings:`);

  // totalUsdValue is page-scoped; paginate before computing full portfolio value.
  balances.slice(0, 10).forEach((token, i) => {
    if (token.usdValue) {
      console.log(`${i + 1}. ${token.symbol}: ${token.balance.toFixed(4)} ($${token.usdValue.toFixed(2)})`);
    }
  });
};

Konzentration der Token berechnen

Analysiere die Diversifizierung des Portfolios:

const analyzeConcentration = async (address) => {
  const { balances, totalUsdValue } = await getWalletBalances(address);

  const tokensWithValue = balances.filter(t => t.usdValue);

  if (tokensWithValue.length === 0) {
    console.log('No tokens with USD pricing data available');
    return null;
  }

  const topToken = tokensWithValue[0];
  const pageConcentration = (topToken.usdValue / totalUsdValue) * 100;

  console.log(`Largest Position on Current Page: ${topToken.symbol} (${pageConcentration.toFixed(1)}%)`);

  if (pageConcentration > 50) {
    console.log(`Warning: Current page is highly concentrated in ${topToken.symbol}`);
  }

  return { topToken, pageConcentration };
};

Guthaben eines bestimmten Token verfolgen

Überwache ein bestimmtes Token über mehrere Wallets hinweg:

const getTokenBalance = async (address, tokenMint) => {
  const { balances } = await getWalletBalances(address);

  const token = balances.find(t => t.mint === tokenMint);

  if (!token) {
    console.log(`Token not found in wallet`);
    return null;
  }

  console.log(`${token.symbol} Balance: ${token.balance}`);
  console.log(`USD Value: $${token.usdValue || 'N/A'}`);

  return token;
};

// Example: Check USDC balance
getTokenBalance(
  "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY",
  "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" // USDC mint
);

Bestände für Steuerberichte exportieren

Erzeuge eine Momentaufnahme der Bestände:

const exportHoldingsSnapshot = async (address) => {
  const { balances, totalUsdValue } = await getWalletBalances(address);

  const snapshot = {
    date: new Date().toISOString(),
    address,
    pageValueUSD: totalUsdValue,
    holdings: balances
      .filter(t => t.usdValue)
      .map(t => ({
        symbol: t.symbol,
        mint: t.mint,
        balance: t.balance,
        pricePerToken: t.pricePerToken,
        usdValue: t.usdValue
      }))
  };

  console.log(JSON.stringify(snapshot, null, 2));
  return snapshot;
};

Seitennavigation

Durchlaufe bei Wallets mit mehr als 100 Token die Ergebnisse mit dem Parameter page und pagination.hasMore seitenweise:

const getAllBalances = async (address) => {
  let allBalances = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const url = `https://api.helius.xyz/v1/wallet/${address}/balances?api-key=YOUR_API_KEY&page=${page}&limit=100`;

    const response = await fetch(url);
    const data = await response.json();

    allBalances = allBalances.concat(data.balances);
    hasMore = data.pagination.hasMore;
    page++;

    console.log(`Fetched page ${data.pagination.page}, total tokens so far: ${allBalances.length}`);
  }

  console.log(`Total tokens: ${allBalances.length}`);
  return allBalances;
};

NFTs werden unabhängig von der Seitennavigation der Token nur auf der ersten Seite zurückgegeben (bis zu 100).

Bewährte Methoden

Filtere Guthaben von null, um die Oberfläche übersichtlicher zu gestalten. Blende mit showZeroBalance=false Token aus, die sich nicht mehr in der Wallet befinden.
Beziehe NFTs nur bei Bedarf ein. Aus Leistungsgründen sind NFTs standardmäßig ausgeschlossen. Setze showNfts=true nur, wenn du sie anzeigst.
Berücksichtige fehlende Preisdaten. Prüfe vor der Anzeige immer, ob pricePerToken und usdValue den Wert null haben. Dies sind stündliche Schätzungen von DAS und keine Echtzeit-Marktkurse.
Speichere responses im Cache. Du kannst Guthabendaten mehrere Sekunden lang zwischenspeichern, um die Anzahl der API-Aufrufe zu reduzieren.
Durchlaufe große Wallets seitenweise. Einige Wallets enthalten Tausende Token. Implementiere eine Seitennavigation, um sie effizient zu verarbeiten.

Häufige Fehler

Fehlercode	Beschreibung	Lösung
400	Ungültiges Format der Wallet-Adresse	Prüfe, ob die Adresse eine gültige Solana-Adresse im base58-Format ist
401	Fehlender oder ungültiger API key	Prüfe, ob dein API key im request enthalten ist
429	Rate limit überschritten	Reduziere die Häufigkeit der requests oder wechsle zu einem höheren Tarif

Nächste Schritte

Historical Balance

Rufe das Guthaben eines Token oder von SOL für einen früheren Zeitstempel, ein früheres Datum mit Uhrzeit oder einen früheren slot ab.

Wallet API Overview

Alle Endpoints der Wallet API und ihre gemeinsamen Konventionen.

API Reference

Schemas für request und response von Wallet-Guthaben.

Erste Schritte

Streaming von Daten und Event-Überwachung

Daten-APIs und RPCs

Trading

Transaktionen senden

Wallet-as-a-Service

Datenschutz

Ressourcen

So rufst du Wallet-Guthaben ab

Übersicht

Wann du dies verwenden solltest

Schnellstart

Einfache Guthabenabfrage

NFTs in die Ergebnisse aufnehmen

Ergebnisse filtern

Abfrageparameter

Format der response

Hinweise zu den Feldern

Anwendungsfälle

Portfolio-Dashboard erstellen

Konzentration der Token berechnen

Guthaben eines bestimmten Token verfolgen

Bestände für Steuerberichte exportieren

Seitennavigation

Bewährte Methoden

Häufige Fehler

Nächste Schritte

Historical Balance

Wallet API Overview

API Reference

​Übersicht

​Wann du dies verwenden solltest

​Schnellstart

​Einfache Guthabenabfrage

​NFTs in die Ergebnisse aufnehmen

​Ergebnisse filtern

​Abfrageparameter

​Format der response

​Hinweise zu den Feldern

​Anwendungsfälle

​Portfolio-Dashboard erstellen

​Konzentration der Token berechnen

​Guthaben eines bestimmten Token verfolgen

​Bestände für Steuerberichte exportieren

​Seitennavigation

​Bewährte Methoden

​Häufige Fehler

​Nächste Schritte

Historical Balance

Wallet API Overview

API Reference

Übersicht

Wann du dies verwenden solltest

Schnellstart

Einfache Guthabenabfrage

NFTs in die Ergebnisse aufnehmen

Ergebnisse filtern

Abfrageparameter

Format der response

Hinweise zu den Feldern

Anwendungsfälle

Portfolio-Dashboard erstellen

Konzentration der Token berechnen

Guthaben eines bestimmten Token verfolgen

Bestände für Steuerberichte exportieren

Seitennavigation

Bewährte Methoden

Häufige Fehler

Nächste Schritte