> ## 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.

# Comment obtenir les soldes de portefeuille

> Récupérez tous les soldes de tokens et NFT pour tout portefeuille Solana avec des valeurs USD, des logos et des métadonnées. Triés par valeur pour un suivi de portefeuille facile.

<Note>
  L'API Wallet est en version bêta. Les points de terminaison et les formats de réponse peuvent changer.
</Note>

## 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.

<Note>
  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.
</Note>

## 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 :

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={"system"}
    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");
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    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")
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={"system"}
    curl "https://api.helius.xyz/v1/wallet/86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY/balances?api-key=YOUR_API_KEY"
    ```
  </Tab>
</Tabs>

### Inclure les NFTs dans les résultats

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

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={"system"}
    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");
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    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")
    ```
  </Tab>
</Tabs>

### Filtrer les résultats

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

```javascript theme={"system"}
// 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

```json theme={"system"}
{
  "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 :

```javascript theme={"system"}
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 :

```javascript theme={"system"}
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 :

```javascript theme={"system"}
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 :

```javascript theme={"system"}
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` :

```javascript theme={"system"}
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

<CardGroup cols={3}>
  <Card title="Solde Historique" icon="clock" href="/docs/fr/wallet-api/balance-at">
    Obtenez un solde de token ou SOL à une date passée, heure ou slot.
  </Card>

  <Card title="Vue d'ensemble de l'API Wallet" icon="wallet" href="/docs/fr/wallet-api/overview">
    Tous les points de terminaison de l'API Wallet et conventions partagées.
  </Card>

  <Card title="Référence API" icon="code" href="/docs/fr/api-reference/wallet-api/balances">
    Schémas de requête et de réponse pour les soldes de portefeuille.
  </Card>
</CardGroup>