> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockradar.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Dépôt de Stablecoins

> Acceptez des dépôts de stablecoins via des adresses dédiées avec auto-sweep et notifications par webhook

<Note>
  En bref<br />
  Blockradar vous permet d'accepter des dépôts de stablecoins en générant des adresses blockchain dédiées pour chaque client. Les dépôts sont détectés automatiquement, déclenchent des notifications par webhook, et peuvent être consolidés (sweep) vers votre portefeuille principal — vous donnant un contrôle total sur la circulation des fonds dans votre plateforme.
</Note>

## Prérequis

<Steps>
  <Step title="Clé API">
    Obtenez votre clé API depuis le [Tableau de bord Blockradar](https://dashboard.blockradar.co). Naviguez vers **Developers** pour en générer une.
  </Step>

  <Step title="Portefeuille Principal">
    Créez un portefeuille via le tableau de bord ou l'API. Vous aurez besoin du `walletId` pour toutes les opérations de dépôt.
  </Step>

  <Step title="Actifs Activés">
    Activez les stablecoins que vous souhaitez accepter sur votre portefeuille. Votre portefeuille ne détecte que les dépôts d'actifs que vous avez explicitement ajoutés — voir [Gestion des Actifs](/fr/use-cases/asset-management).
  </Step>

  <Step title="URL de Webhook">
    Configurez un endpoint de webhook dans votre tableau de bord sous **Developers → Webhooks** pour recevoir les notifications de dépôts en temps réel.
  </Step>
</Steps>

## Comment Ça Fonctionne

Le flux de dépôt de Blockradar repose sur un principe simple : chaque client obtient sa propre adresse, et chaque dépôt est suivi automatiquement.

<CardGroup cols={2}>
  <Card title="Générer des Adresses" icon="address-card">
    Créez une adresse blockchain unique pour chaque client ou session de paiement. Les dépôts vers cette adresse sont attribués automatiquement au client.
  </Card>

  <Card title="Détecter les Dépôts" icon="bell">
    Blockradar surveille toutes les adresses générées et déclenche un webhook dès qu'un dépôt arrive. Aucun polling requis.
  </Card>

  <Card title="Auto-Sweep" icon="broom">
    Les dépôts sont automatiquement consolidés vers votre portefeuille principal, gardant les adresses clients propres et votre trésorerie centralisée.
  </Card>

  <Card title="Consulter les Soldes" icon="scale-balanced">
    Interrogez les soldes au niveau du portefeuille ou de l'adresse, pour un actif unique ou tous les actifs à la fois, avec la conversion en USD incluse.
  </Card>
</CardGroup>

## Contrôle Granulaire par Conception

La plupart des infrastructures blockchain traitent les portefeuilles comme des conteneurs plats et uniformes. Blockradar est différent. Chaque couche de la hiérarchie du portefeuille — portefeuille principal, adresse secondaire et actif individuel — est configurable indépendamment, afin que les fintechs puissent adapter l'expérience de dépôt à leurs besoins produit exacts.

Cela signifie que vous pouvez :

* **Accepter différents stablecoins par portefeuille** — activez USDC sur un portefeuille et USDT sur un autre, ou les deux sur le même portefeuille. Vous décidez de ce que chaque portefeuille surveille.
* **Configurer le comportement de sweep par adresse** — auto-sweep des dépôts vers le portefeuille principal par défaut, mais désactivez-le pour des adresses spécifiques où vous souhaitez que les fonds restent en place.
* **Attacher des métadonnées à chaque adresse** — taguez les adresses avec vos propres IDs utilisateurs, tokens de session ou références internes afin que les dépôts se mappent directement à votre système.
* **Activer ou désactiver les adresses à la demande** — mettez en pause une adresse sans la supprimer, puis réactivez-la au besoin.

Cette granularité est essentielle lorsque vous construisez des produits comme des portefeuilles multi-devises, des escrows pour marketplace ou des flux de dépôt par utilisateur, où un modèle de portefeuille rigide forcerait des contournements que Blockradar gère nativement.

***

## Étape 1 : Activer les Actifs sur Votre Portefeuille

Avant de pouvoir accepter des dépôts, votre portefeuille doit savoir quels stablecoins surveiller. Récupérez les actifs disponibles avec le endpoint [Get Assets](/fr/api-reference/miscellaneous/get-assets), puis ajoutez ceux que vous voulez.

<CodeGroup>
  ```bash Curl theme={null}
  curl --request POST \
    --url https://api.blockradar.co/v1/wallets/{walletId}/assets \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: <api-key>' \
    --data '{
      "assetId": "global-asset-id-for-usdc"
    }'
  ```

  ```javascript JavaScript theme={null}
  const asset = await fetch(
    `https://api.blockradar.co/v1/wallets/${walletId}/assets`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey
      },
      body: JSON.stringify({
        assetId: 'global-asset-id-for-usdc'
      })
    }
  ).then(r => r.json());

  console.log('Asset enabled:', asset.data.asset.symbol);
  ```
</CodeGroup>

Une fois ajouté, Blockradar commence immédiatement à surveiller votre portefeuille et toutes ses adresses pour les dépôts de ce token.

<Tip>
  Utilisez [Get Wallet Assets](/fr/api-reference/asset/get-wallet-assets) pour récupérer les IDs d'actifs spécifiques au portefeuille. Ce sont les IDs que vous utiliserez dans les requêtes de solde et autres appels API — ils sont différents des IDs d'actifs globaux.
</Tip>

## Étape 2 : Générer une Adresse Client

Créez une adresse dédiée pour chaque client ou session de dépôt. Chaque dépôt vers cette adresse est automatiquement attribué au client.

<CodeGroup>
  ```bash Curl theme={null}
  curl --request POST \
    --url https://api.blockradar.co/v1/wallets/{walletId}/addresses \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: <api-key>' \
    --data '{
      "name": "Customer 12345",
      "metadata": {
        "userId": "user_12345",
        "plan": "premium"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const address = await fetch(
    `https://api.blockradar.co/v1/wallets/${walletId}/addresses`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey
      },
      body: JSON.stringify({
        name: 'Customer 12345',
        metadata: {
          userId: 'user_12345',
          plan: 'premium'
        }
      })
    }
  ).then(r => r.json());

  console.log('Deposit address:', address.data.address);
  ```
</CodeGroup>

### Réponse

```json theme={null}
{
  "statusCode": 201,
  "message": "Address generated successfully",
  "data": {
    "id": "address-uuid",
    "address": "0xe1037B45b48390285e5067424053fa35c478296b",
    "name": "Customer 12345",
    "type": "INTERNAL",
    "isActive": true,
    "metadata": {
      "userId": "user_12345",
      "plan": "premium"
    },
    "configurations": {
      "autoSweep": true,
      "gaslessWithdraw": false
    },
    "blockchain": {
      "name": "base",
      "symbol": "ETH",
      "network": "mainnet"
    },
    "createdAt": "2024-01-15T10:30:00Z"
  }
}
```

### Paramètres d'Adresse

| Paramètre               | Type    | Requis | Description                                                                                          |
| ----------------------- | ------- | ------ | ---------------------------------------------------------------------------------------------------- |
| `name`                  | string  | Non    | Libellé lisible pour l'adresse                                                                       |
| `metadata`              | object  | Non    | Paires clé-valeur personnalisées mappées à votre système interne                                     |
| `disableAutoSweep`      | boolean | Non    | `true` pour garder les dépôts sur l'adresse au lieu de les consolider vers le portefeuille principal |
| `enableGaslessWithdraw` | boolean | Non    | Active les retraits sans gas depuis cette adresse                                                    |

Partagez l'`address` générée avec votre client. Lorsqu'il envoie des stablecoins, Blockradar détecte le dépôt et déclenche un webhook.

## Étape 3 : Écouter les Dépôts

Configurez votre endpoint de webhook pour recevoir des notifications en temps réel lorsque les dépôts arrivent.

### Événements de Webhook

| Événement               | Description                                                  |
| ----------------------- | ------------------------------------------------------------ |
| `deposit.success`       | Un dépôt a été confirmé on-chain sur une adresse client      |
| `deposit.swept.success` | Le dépôt a été auto-consolidé vers le portefeuille principal |

### Payload de Webhook

```json theme={null}
{
  "event": "deposit.success",
  "data": {
    "id": "tx-uuid",
    "hash": "0xabc123...",
    "type": "DEPOSIT",
    "status": "SUCCESS",
    "amount": "100",
    "senderAddress": "0xCustomerExternalWallet...",
    "recipientAddress": "0xe1037B45b48390285e5067424053fa35c478296b",
    "asset": {
      "id": "asset-uuid",
      "name": "USD Coin",
      "symbol": "USDC",
      "decimals": 6
    },
    "wallet": {
      "id": "wallet-uuid",
      "name": "Deposits Wallet"
    },
    "blockchain": {
      "name": "base",
      "network": "mainnet"
    },
    "metadata": {
      "userId": "user_12345",
      "plan": "premium"
    },
    "createdAt": "2024-01-15T10:30:00Z"
  }
}
```

<Info>
  Les `metadata` que vous avez attachées lors de la génération de l'adresse sont incluses dans chaque webhook pour cette adresse, vous permettant de mapper les dépôts à vos utilisateurs sans requête supplémentaire.
</Info>

***

## Vérifier les Soldes

Interrogez les soldes à n'importe quel niveau de la hiérarchie — portefeuille principal ou adresse individuelle, actif unique ou tous les actifs.

### Solde d'un Actif Unique (Portefeuille)

<CodeGroup>
  ```bash Curl theme={null}
  curl --request GET \
    --url 'https://api.blockradar.co/v1/wallets/{walletId}/balance?assetId={assetId}' \
    --header 'x-api-key: <api-key>'
  ```

  ```javascript JavaScript theme={null}
  const balance = await fetch(
    `https://api.blockradar.co/v1/wallets/${walletId}/balance?assetId=${assetId}`,
    { headers: { 'x-api-key': apiKey } }
  ).then(r => r.json());

  console.log(`Balance: ${balance.data.balance} (≈$${balance.data.convertedBalance})`);
  ```
</CodeGroup>

### Soldes de Tous les Actifs (Adresse)

<CodeGroup>
  ```bash Curl theme={null}
  curl --request GET \
    --url https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/balances \
    --header 'x-api-key: <api-key>'
  ```

  ```javascript JavaScript theme={null}
  const balances = await fetch(
    `https://api.blockradar.co/v1/wallets/${walletId}/addresses/${addressId}/balances`,
    { headers: { 'x-api-key': apiKey } }
  ).then(r => r.json());

  balances.data.forEach(b => {
    console.log(`${b.asset.asset.symbol}: ${b.balance} (≈$${b.convertedBalance})`);
  });
  ```
</CodeGroup>

### Endpoints de Solde

| Portée                 | Actif Unique                                                                 | Tous les Actifs                                             |
| ---------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------- |
| Portefeuille Principal | `GET /v1/wallets/{walletId}/balance?assetId={assetId}`                       | `GET /v1/wallets/{walletId}/balances`                       |
| Adresse Secondaire     | `GET /v1/wallets/{walletId}/addresses/{addressId}/balance?assetId={assetId}` | `GET /v1/wallets/{walletId}/addresses/{addressId}/balances` |

***

## Gestion des Adresses

### Lister Toutes les Adresses

Récupérez toutes les adresses d'un portefeuille, avec des analytics sur les comptes actifs vs. inactifs.

```bash theme={null}
GET /v1/wallets/{walletId}/addresses
```

### Obtenir une Adresse Spécifique

Récupérez les détails complets d'une seule adresse, y compris sa configuration et ses métadonnées.

```bash theme={null}
GET /v1/wallets/{walletId}/addresses/{addressId}
```

### Mettre à Jour une Adresse

Modifiez le nom, les métadonnées, le statut actif ou la configuration de sweep d'une adresse.

<CodeGroup>
  ```bash Curl theme={null}
  curl --request PATCH \
    --url https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId} \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: <api-key>' \
    --data '{
      "name": "Customer 12345 — upgraded",
      "metadata": {
        "userId": "user_12345",
        "plan": "enterprise"
      },
      "disableAutoSweep": true
    }'
  ```

  ```javascript JavaScript theme={null}
  const updated = await fetch(
    `https://api.blockradar.co/v1/wallets/${walletId}/addresses/${addressId}`,
    {
      method: 'PATCH',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey
      },
      body: JSON.stringify({
        name: 'Customer 12345 — upgraded',
        metadata: {
          userId: 'user_12345',
          plan: 'enterprise'
        },
        disableAutoSweep: true
      })
    }
  ).then(r => r.json());
  ```
</CodeGroup>

### Désactiver une Adresse

Définissez `isActive` sur `false` pour cesser de surveiller une adresse. L'adresse et son historique sont préservés — vous pouvez la réactiver à tout moment.

```javascript theme={null}
await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/addresses/${addressId}`,
  {
    method: 'PATCH',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey
    },
    body: JSON.stringify({ isActive: false })
  }
);
```

***

## Auto-Sweep

Par défaut, les dépôts vers les adresses secondaires sont automatiquement consolidés vers le portefeuille principal. Cela garde les adresses clients propres et centralise les fonds pour la gestion de trésorerie ou les paiements sortants.

Vous pouvez contrôler ce comportement au niveau de l'adresse :

| Réglage                        | Comportement                                                                                 |
| ------------------------------ | -------------------------------------------------------------------------------------------- |
| Auto-sweep **activé** (défaut) | Les dépôts sont automatiquement déplacés vers le portefeuille principal après confirmation   |
| Auto-sweep **désactivé**       | Les dépôts restent sur l'adresse secondaire jusqu'à une consolidation manuelle ou un retrait |

### Sweep Manuel

Si l'auto-sweep est désactivé, vous pouvez déclencher un sweep à la demande :

```bash theme={null}
POST /v1/wallets/{walletId}/sweep/assets
```

```json theme={null}
{
  "forceSweep": true
}
```

### Deposit Finder

Si un dépôt n'apparaît pas (ex. webhook manqué), utilisez le deposit finder pour rescanner la blockchain :

```bash theme={null}
POST /v1/wallets/{walletId}/rescan/blocks
```

```json theme={null}
{
  "transactionHash": "0xabc123..."
}
```

***

## Exemple de Flux Complet

Voici une implémentation complète : activer un actif, générer une adresse client et gérer le webhook de dépôt.

```javascript theme={null}
async function setupCustomerDeposit(walletId, userId) {
  const apiKey = process.env.BLOCKRADAR_API_KEY;
  const baseUrl = 'https://api.blockradar.co/v1';
  const headers = {
    'Content-Type': 'application/json',
    'x-api-key': apiKey
  };

  // Étape 1 : Générer une adresse dédiée pour le client
  const addressRes = await fetch(
    `${baseUrl}/wallets/${walletId}/addresses`,
    {
      method: 'POST',
      headers,
      body: JSON.stringify({
        name: `User ${userId}`,
        metadata: { userId, createdAt: new Date().toISOString() }
      })
    }
  ).then(r => r.json());

  const depositAddress = addressRes.data.address;
  console.log('Share this address with customer:', depositAddress);

  return depositAddress;
}

// Handler de webhook (exemple Express.js)
app.post('/webhooks/blockradar', (req, res) => {
  const { event, data } = req.body;

  if (event === 'deposit.success') {
    const userId = data.metadata?.userId;
    const amount = data.amount;
    const symbol = data.asset.symbol;

    console.log(`Deposit received: ${amount} ${symbol} from user ${userId}`);

    // Créditer le compte utilisateur dans votre système
    creditUserAccount(userId, amount, symbol);
  }

  if (event === 'deposit.swept.success') {
    console.log(`Deposit swept to master wallet: ${data.amount} ${data.asset.symbol}`);
  }

  res.sendStatus(200);
});
```

***

## Bonnes Pratiques

### Gestion des Adresses

* **Une adresse par client** — générez une adresse unique pour chaque utilisateur ou session de paiement pour simplifier l'attribution
* **Utilisez les métadonnées** — attachez vos IDs utilisateurs internes et références afin que les payloads de webhook se mappent directement à votre système
* **Désactivez, ne supprimez pas** — définissez `isActive: false` sur les adresses que vous n'utilisez plus, en préservant l'historique

### Sécurité

* **Validez les webhooks** — vérifiez que les requêtes webhook entrantes proviennent de Blockradar
* **Activez le screening AML** — Blockradar peut filtrer automatiquement les adresses de dépôt (voir [Vérification AML](/fr/use-cases/aml-screening))
* **Surveillez les logs de webhook** — utilisez `GET /v1/wallets/{walletId}/webhooks` pour déboguer les livraisons échouées

### Opérations

* **N'activez que les actifs dont vous avez besoin** — une liste d'actifs focalisée réduit le bruit des webhooks et garde les requêtes de solde rapides
* **Testez d'abord sur testnet** — générez des adresses, simulez des dépôts et vérifiez votre handler de webhook avant de passer en mainnet
* **Utilisez le deposit finder** — si un client signale un dépôt que vous n'avez pas reçu, rescannez la blockchain avant de dépanner davantage

***

## Référence API

### Portefeuille

| Endpoint                                                       | Description                                                         |
| -------------------------------------------------------------- | ------------------------------------------------------------------- |
| [Get Wallet](/fr/api-reference/wallet/get-wallet)              | Récupère les détails et la configuration du portefeuille            |
| [Get Balance](/fr/api-reference/wallet/get-balance)            | Vérifie le solde d'un actif unique sur le portefeuille principal    |
| [Get Balances](/fr/api-reference/wallet/get-balances)          | Vérifie les soldes de tous les actifs sur le portefeuille principal |
| [Trigger Sweep](/fr/api-reference/wallet/trigger-sweep-assets) | Consolide manuellement les dépôts vers le portefeuille principal    |
| [Deposit Finder](/fr/api-reference/wallet/deposit-finder)      | Rescanne la blockchain pour les dépôts manquants                    |
| [Webhook Logs](/fr/api-reference/wallet/webhooks-logs)         | Affiche l'historique de livraison des webhooks                      |

### Adresses

| Endpoint                                                         | Description                                                          |
| ---------------------------------------------------------------- | -------------------------------------------------------------------- |
| [Generate Address](/fr/api-reference/addresses/generate-address) | Crée une nouvelle adresse de dépôt client                            |
| [Get Addresses](/fr/api-reference/addresses/get-addresses)       | Liste toutes les adresses d'un portefeuille                          |
| [Get Address](/fr/api-reference/addresses/get-address)           | Récupère les détails d'une adresse spécifique                        |
| [Update Address](/fr/api-reference/addresses/update-address)     | Met à jour le nom, les métadonnées ou la configuration d'une adresse |
| [Get Balance](/fr/api-reference/addresses/get-balance)           | Vérifie le solde d'un actif unique sur une adresse                   |
| [Get Balances](/fr/api-reference/addresses/get-balances)         | Vérifie les soldes de tous les actifs sur une adresse                |
| [Get Transactions](/fr/api-reference/addresses/get-transactions) | Affiche l'historique des dépôts pour une adresse                     |

### Gestion des Actifs

| Endpoint                                                         | Description                                      |
| ---------------------------------------------------------------- | ------------------------------------------------ |
| [Get Wallet Assets](/fr/api-reference/asset/get-wallet-assets)   | Liste les actifs activés sur un portefeuille     |
| [Add Asset](/fr/api-reference/asset/add-asset-to-wallet)         | Active un nouveau stablecoin pour les dépôts     |
| [Remove Asset](/fr/api-reference/asset/remove-asset-from-wallet) | Arrête la surveillance d'un stablecoin           |
| [Update Asset](/fr/api-reference/asset/update-wallet-asset)      | Met à jour la configuration au niveau de l'actif |