Comment obtenir les soldes de portefeuille

L’API Wallet est en version bêta. Les points de terminaison et les formats de réponse peuvent changer.

Vue d’ensemble

Le point de terminaison Wallet Balances récupère toutes les possessions de tokens et de NFT pour un portefeuille Solana — SOL, tokens SPL, Token-2022 et NFTs — avec des prix en USD, des logos et des métadonnées. Les résultats sont triés par valeur en USD par ordre décroissant : les tokens avec des données tarifaires apparaissent en premier, suivis des tokens sans prix. Le point de terminaison retourne jusqu’à 100 tokens par requête, donc la pagination est manuelle. Utilisez le paramètre page pour récupérer des pages supplémentaires et lisez pagination.hasMore pour savoir quand davantage de résultats sont disponibles. Chaque requête est un seul appel API et coûte 100 crédits.

Les prix en USD proviennent de DAS et sont mis à jour toutes les heures, couvrant les 10 000 tokens les plus importants par capitalisation boursière. pricePerToken et usdValue sont null pour les tokens non pris en charge. Les prix sont des estimations, pas des taux de marché en temps réel.

Quand l’utiliser

Utilisez l’API Wallet Balances lorsque vous avez besoin de :

Afficher les avoirs de portefeuille : montrer aux utilisateurs leurs avoirs complets en tokens et NFTs.
Calculer les valeurs en USD : obtenir des évaluations de portefeuille avec des prix mis à jour toutes les heures.
Construire des interfaces utilisateur de portefeuille : alimenter les tableaux de bord de portefeuille et les listes d’actifs.
Suivre les avoirs en tokens : surveiller les soldes de tokens spécifiques à travers les portefeuilles.
Analyse de portefeuille : analyser la distribution et la concentration des avoirs.
Déclaration fiscale : générer des instantanés d’avoirs à des fins fiscales.

Démarrage rapide

Requête de solde de base

Obtenez tous les soldes de tokens pour un portefeuille avec des valeurs en USD :

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"

Inclure les NFTs dans les résultats

Obtenez à la fois les tokens et les NFTs dans une seule requête avec showNfts=true :

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

Filtrer les résultats

Utilisez des paramètres de requête pour affiner ce qui est retourné :

// 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`;

Paramètres de requête

Paramètre	Type	Par défaut	Description
`page`	entier	1	Numéro de page pour la pagination (à partir de 1)
`limit`	entier	100	Nombre maximum de tokens par page (1-100)
`showZeroBalance`	booléen	false	Inclure les tokens avec un solde zéro
`showNative`	booléen	true	Inclure les SOL natifs dans les résultats
`showNfts`	booléen	false	Inclure les NFTs dans les résultats (max 100, première page seulement)

Format de réponse

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

Notes sur les champs

balance : montant lisible par l’homme, déjà ajusté pour les décimales — 1.5 signifie 1.5 SOL et 1000.5 signifie 1000.5 USDC. Aucune conversion de lamport n’est nécessaire. Ce point de terminaison n’expose pas de champ amountRaw brut ; si vous avez besoin de la valeur entière exacte, dérivez-la comme Math.round(balance * 10 ** decimals).
decimals : fourni à titre de référence uniquement.
pricePerToken / usdValue : null pour les tokens sans données tarifaires DAS (voir la note sur les prix ci-dessus).
totalUsdValue : valeur totale en USD uniquement pour la page de réponse actuelle. Pour la valeur de portefeuille complète, pagination à travers toutes les pages et sommez chaque solde usdValue.
tokenProgram : quel standard de token chaque token utilise — spl-token (Token SPL hérité) ou token-2022 (Extensions de Token). Les deux sont entièrement pris en charge.

Cas d’utilisation

Construire un tableau de bord de portefeuille

Affichez les avoirs des utilisateurs avec des valeurs en USD :

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)})`);
    }
  });
};

Calculer la concentration de tokens

Analyser la diversification du portefeuille :

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 };
};

Suivre un solde de token spécifique

Surveiller un token spécifique à travers plusieurs portefeuilles :

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
);

Exporter les avoirs pour la déclaration fiscale

Générer un instantané des avoirs :

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;
};

Pagination

Pour les portefeuilles avec plus de 100 tokens, paginez à travers les résultats avec le paramètre page et pagination.hasMore :

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;
};

Les NFTs sont retournés uniquement sur la première page (jusqu’à 100), quel que soit la pagination des tokens.

Bonnes pratiques

Filtrer les soldes zéro pour une interface utilisateur plus propre. Utilisez showZeroBalance=false pour masquer les tokens que le portefeuille ne détient plus.
Inclure les NFTs uniquement si nécessaire. Les NFTs sont exclus par défaut pour des raisons de performance ; définissez showNfts=true uniquement lors de leur affichage.
Gérer les données tarifaires manquantes. Vérifiez toujours si pricePerToken et usdValue sont null avant d’afficher. Ce sont des estimations horaires de DAS, pas des taux de marché en temps réel.
Mettre en cache les réponses. Les données des soldes peuvent être mises en cache pendant plusieurs secondes pour réduire les appels API.
Paginer les grands portefeuilles. Certains portefeuilles détiennent des milliers de tokens ; implémentez la pagination pour les gérer efficacement.

Erreurs courantes

Code d’erreur	Description	Solution
400	Format d’adresse de portefeuille invalide	Vérifiez que l’adresse est une adresse Solana base58 valide
401	Clé API manquante ou invalide	Vérifiez que votre clé API est incluse dans la requête
429	Limite de débit dépassée	Réduisez la fréquence des requêtes ou mettez à niveau votre plan

Prochaines étapes

Solde Historique

Obtenez un solde de token ou SOL à une date passée, heure ou slot.

Vue d'ensemble de l'API Wallet

Tous les points de terminaison de l’API Wallet et conventions partagées.

Référence API

Schémas de requête et de réponse pour les soldes de portefeuille.

Commencer

Diffusion de données et écoute d'événements

API de données et RPC

Trading

Envoyer des transactions

Wallet en tant que service

Confidentialité

Ressources

Comment obtenir les soldes de portefeuille

Vue d’ensemble

Quand l’utiliser

Démarrage rapide

Requête de solde de base

Inclure les NFTs dans les résultats

Filtrer les résultats

Paramètres de requête

Format de réponse

Notes sur les champs

Cas d’utilisation

Construire un tableau de bord de portefeuille

Calculer la concentration de tokens

Suivre un solde de token spécifique

Exporter les avoirs pour la déclaration fiscale

Bonnes pratiques

Erreurs courantes

Prochaines étapes

Solde Historique

Vue d'ensemble de l'API Wallet

Référence API

​Vue d’ensemble

​Quand l’utiliser

​Démarrage rapide

​Requête de solde de base

​Inclure les NFTs dans les résultats

​Filtrer les résultats

​Paramètres de requête

​Format de réponse

​Notes sur les champs

​Cas d’utilisation

​Construire un tableau de bord de portefeuille

​Calculer la concentration de tokens

​Suivre un solde de token spécifique

​Exporter les avoirs pour la déclaration fiscale

​Pagination

​Bonnes pratiques

​Erreurs courantes

​Prochaines étapes

Solde Historique

Vue d'ensemble de l'API Wallet

Référence API

Vue d’ensemble

Quand l’utiliser

Démarrage rapide

Requête de solde de base

Inclure les NFTs dans les résultats

Filtrer les résultats

Paramètres de requête

Format de réponse

Notes sur les champs

Cas d’utilisation

Construire un tableau de bord de portefeuille

Calculer la concentration de tokens

Suivre un solde de token spécifique

Exporter les avoirs pour la déclaration fiscale

Pagination

Bonnes pratiques

Erreurs courantes

Prochaines étapes