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

# Swap et Bridge

> Échangez des actifs entre chaînes avec une API unifiée

<img src="https://mintcdn.com/blockradar/FrE2zfJ4u32QicMn/images/swap.jpg?fit=max&auto=format&n=FrE2zfJ4u32QicMn&q=85&s=a3cb4d76aa3218dd5b8cf2c816d55b93" alt="Swap et Bridge" width="2880" height="1620" data-path="images/swap.jpg" />

<Note>
  En résumé<br />
  L'API Swap de Blockradar vous permet d'échanger des actifs sur la même chaîne (swap) ou de transférer des actifs entre différentes chaînes (bridge) via un endpoint unifié unique.
</Note>

## Prérequis

Avant d'utiliser l'API Swap, assurez-vous de disposer des éléments suivants :

<Steps>
  <Step title="Clé d'API">
    Obtenez votre clé d'API depuis le [Dashboard Blockradar](https://dashboard.blockradar.co). Rendez-vous dans **Developers** pour en générer une.
  </Step>

  <Step title="Wallet créée">
    Créez une wallet via l'[API Create Wallet](/en/api-reference/wallets/create-wallet) ou depuis le dashboard. Vous aurez besoin du `walletId` pour les opérations de swap.
  </Step>

  <Step title="IDs des actifs">
    Récupérez l'`assetId` de vos actifs source et destination depuis **Assets** dans le dashboard ou via l'[API Get Assets](/en/api-reference/miscellaneous/get-assets).
  </Step>

  <Step title="Solde suffisant">
    Vérifiez que votre wallet dispose d'un solde suffisant de l'actif source pour couvrir le montant du swap ainsi que les frais de réseau.
  </Step>
</Steps>

## Fonctionnement

Blockradar détermine automatiquement si votre transaction est un **swap** ou un **bridge** en fonction de votre sélection d'actifs :

<CardGroup cols={2}>
  <Card title="Swap" icon="repeat">
    Échangez différents actifs sur la **même blockchain**.

    *Exemple : USDC → USDT sur Base*
  </Card>

  <Card title="Bridge" icon="bridge">
    Déplacez des actifs entre **blockchains différentes**.

    *Exemple : USDC sur BSC → USDC sur Optimism*
  </Card>
</CardGroup>

<Tip>
  Vous n'avez pas besoin de préciser s'il s'agit d'un swap ou d'un bridge — l'API gère cela automatiquement à partir des `fromAssetId` et `toAssetId` que vous fournissez.
</Tip>

## Actifs et chaînes pris en charge

L'API Swap prend en charge les principales stablecoins sur les chaînes compatibles avec Blockradar :

| Stablecoin | Description             |
| ---------- | ----------------------- |
| USDT       | Tether USD              |
| USDC       | USD Coin                |
| DAI        | Dai Stablecoin          |
| BUSD       | Binance USD             |
| cNGN       | Stablecoin Naira        |
| EURC       | Euro Coin               |
| IDRX       | Stablecoin indonésien   |
| JPYC       | Stablecoin yen japonais |

<Warning>
  La disponibilité des actifs varie selon la chaîne. Utilisez toujours l'[API Get Assets](/en/api-reference/miscellaneous/get-assets) pour récupérer la liste actualisée des actifs pris en charge et leurs valeurs `assetId` pour vos chaînes cibles.
</Warning>

<Note>
  Consultez la rubrique [Intégrations](/en/essentials/integrations) pour la liste complète des réseaux et stablecoins pris en charge.
</Note>

## Master Wallet vs Child Address

L'API Swap est disponible à deux niveaux :

<CardGroup cols={2}>
  <Card title="Master Wallet" icon="wallet">
    Exécutez des swaps directement depuis votre master wallet. Idéal pour les opérations de trésorerie.
  </Card>

  <Card title="Child Address" icon="address-card">
    Exécutez des swaps depuis des child addresses individuelles. Parfait pour les opérations spécifiques à un utilisateur.
  </Card>
</CardGroup>

### Endpoints

| Opération        | Master Wallet                               | Child Address                                                     |
| ---------------- | ------------------------------------------- | ----------------------------------------------------------------- |
| Obtenir un devis | `POST /v1/wallets/{walletId}/swaps/quote`   | `POST /v1/wallets/{walletId}/addresses/{addressId}/swaps/quote`   |
| Exécuter         | `POST /v1/wallets/{walletId}/swaps/execute` | `POST /v1/wallets/{walletId}/addresses/{addressId}/swaps/execute` |

## Étape 1 : Obtenir un devis

Demandez toujours un devis avant d'exécuter un swap afin de présenter aux utilisateurs le résultat attendu.

### Paramètres de la requête

| Paramètre          | Type   | Requis | Description                                                               |
| ------------------ | ------ | ------ | ------------------------------------------------------------------------- |
| `fromAssetId`      | string | Oui    | L'asset ID de départ du swap                                              |
| `toAssetId`        | string | Oui    | L'asset ID de destination du swap                                         |
| `amount`           | string | Oui    | Le montant à échanger                                                     |
| `order`            | string | Non    | Préférence de devis : `FASTEST`, `CHEAPEST`, `RECOMMENDED`, `NO_SLIPPAGE` |
| `recipientAddress` | string | Non    | Adresse de wallet externe (pour envoyer vers des wallets non Blockradar)  |

### Exemple de devis

<CodeGroup>
  ```bash Curl theme={null}
  curl --request POST \
    --url https://api.blockradar.co/v1/wallets/{walletId}/swaps/quote \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: <api-key>' \
    --data '{
      "fromAssetId": "asset_usdc_base_mainnet",
      "toAssetId": "asset_usdt_bsc_mainnet",
      "amount": "100",
      "order": "RECOMMENDED"
    }'
  ```

  ```javascript JavaScript theme={null}
  const quote = await fetch(
    `https://api.blockradar.co/v1/wallets/${walletId}/swaps/quote`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey
      },
      body: JSON.stringify({
        fromAssetId: 'asset_usdc_base_mainnet',
        toAssetId: 'asset_usdt_bsc_mainnet',
        amount: '100',
        order: 'RECOMMENDED'
      })
    }
  ).then(r => r.json());

  console.log('Quote:', quote.data);
  ```
</CodeGroup>

### Réponse du devis

```json theme={null}
{
  "message": "Swap quote fetched successfully",
  "statusCode": 200,
  "data": {
    "amount": "99.45",
    "minAmount": "98.95",
    "rate": "0.9945",
    "impact": "0.12",
    "slippage": "0.5",
    "networkFee": "0.002",
    "networkFeeInUSD": "0.15",
    "estimatedArrivalTime": 180
  }
}
```

### Comprendre les champs du devis

| Champ                  | Description                                            |
| ---------------------- | ------------------------------------------------------ |
| `amount`               | Montant estimé que vous recevrez après le swap         |
| `minAmount`            | Montant minimum garanti (en tenant compte du slippage) |
| `rate`                 | Taux de change effectif (toAmount / fromAmount)        |
| `impact`               | Pourcentage d'impact sur le prix                       |
| `slippage`             | Pourcentage maximal de variation de prix autorisée     |
| `networkFee`           | Frais de gas exprimés en unités du token natif         |
| `networkFeeInUSD`      | Frais de gas convertis en USD                          |
| `estimatedArrivalTime` | Temps estimé de finalisation en secondes               |

<Tip>
  Affichez toujours au minimum : **montant à recevoir**, **temps d'arrivée estimé** et **frais** avant que l'utilisateur ne confirme le swap.
</Tip>

## Étape 2 : Exécuter le Swap

Une fois que l'utilisateur a confirmé le devis, exécutez le swap.

### Paramètres de la requête

| Paramètre          | Type   | Requis | Description                                                               |
| ------------------ | ------ | ------ | ------------------------------------------------------------------------- |
| `fromAssetId`      | string | Oui    | L'asset ID de départ du swap                                              |
| `toAssetId`        | string | Oui    | L'asset ID de destination du swap                                         |
| `amount`           | string | Oui    | Le montant à échanger                                                     |
| `order`            | string | Non    | Préférence de devis : `FASTEST`, `CHEAPEST`, `RECOMMENDED`, `NO_SLIPPAGE` |
| `recipientAddress` | string | Non    | Adresse de wallet externe (pour envoyer vers des wallets non Blockradar)  |
| `reference`        | string | Non    | Votre identifiant interne de suivi                                        |
| `metadata`         | object | Non    | Données personnalisées transmises via les webhooks                        |

### Exemple d'exécution

<CodeGroup>
  ```bash Curl theme={null}
  curl --request POST \
    --url https://api.blockradar.co/v1/wallets/{walletId}/swaps/execute \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: <api-key>' \
    --data '{
      "fromAssetId": "asset_usdc_base_mainnet",
      "toAssetId": "asset_usdt_bsc_mainnet",
      "amount": "100",
      "order": "RECOMMENDED",
      "reference": "swap-order-12345",
      "metadata": {
        "userId": "user_abc123",
        "orderId": "order_xyz789"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const swap = await fetch(
    `https://api.blockradar.co/v1/wallets/${walletId}/swaps/execute`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey
      },
      body: JSON.stringify({
        fromAssetId: 'asset_usdc_base_mainnet',
        toAssetId: 'asset_usdt_bsc_mainnet',
        amount: '100',
        order: 'RECOMMENDED',
        reference: 'swap-order-12345',
        metadata: {
          userId: 'user_abc123',
          orderId: 'order_xyz789'
        }
      })
    }
  ).then(r => r.json());

  console.log('Swap initiated:', swap.data);
  ```
</CodeGroup>

### Réponse de l'exécution

```json theme={null}
{
  "message": "Swap transaction created successfully",
  "statusCode": 200,
  "data": {
    "id": "swap-uuid-123",
    "type": "SWAP",
    "status": "PENDING",
    "fromAsset": {
      "symbol": "USDC",
      "amount": "100",
      "blockchain": "base"
    },
    "toAsset": {
      "symbol": "USDT",
      "amount": "99.45",
      "blockchain": "bsc"
    },
    "reference": "swap-order-12345",
    "metadata": {
      "userId": "user_abc123",
      "orderId": "order_xyz789"
    },
    "createdAt": "2024-01-15T10:30:00Z"
  }
}
```

<Warning>
  Les opérations de swap sont asynchrones. La réponse initiale indique le statut `PENDING`. Écoutez le webhook `swap.success` ou `swap.failed` pour confirmer la finalisation.
</Warning>

## Types d'ordres

Choisissez le type d'ordre adapté à votre cas d'usage :

| Type d'ordre  | Description                                | Idéal pour                      |
| ------------- | ------------------------------------------ | ------------------------------- |
| `FASTEST`     | Privilégie la vitesse au détriment du coût | Transactions sensibles au temps |
| `CHEAPEST`    | Minimise les frais                         | Opérations sensibles au coût    |
| `RECOMMENDED` | Approche équilibrée (par défaut)           | La plupart des cas              |
| `NO_SLIPPAGE` | Montant exact ou échec                     | Exigences de montant précis     |

## Événements Webhook

Suivez la finalisation des swaps via les webhooks :

| Événement      | Description               |
| -------------- | ------------------------- |
| `swap.success` | Swap effectué avec succès |
| `swap.failed`  | Swap en échec             |

### Charge utile du Webhook

```json theme={null}
{
  "event": "swap.success",
  "data": {
    "id": "swap-uuid-123",
    "type": "SWAP",
    "status": "SUCCESS",
    "fromAsset": {
      "symbol": "USDC",
      "amount": "100",
      "blockchain": "base",
      "hash": "0xabc..."
    },
    "toAsset": {
      "symbol": "USDT",
      "amount": "99.45",
      "blockchain": "bsc",
      "hash": "0xdef..."
    },
    "reference": "swap-order-12345",
    "metadata": {
      "userId": "user_abc123",
      "orderId": "order_xyz789"
    },
    "completedAt": "2024-01-15T10:33:00Z"
  }
}
```

## Exemple de flux complet

Voici une implémentation complète illustrant le flux devis → confirmation → exécution :

```javascript theme={null}
async function executeSwap(walletId, fromAssetId, toAssetId, amount) {
  const apiKey = process.env.BLOCKRADAR_API_KEY;
  const baseUrl = 'https://api.blockradar.co/v1';

  // Step 1: Get quote
  const quote = await fetch(
    `${baseUrl}/wallets/${walletId}/swaps/quote`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey
      },
      body: JSON.stringify({
        fromAssetId,
        toAssetId,
        amount,
        order: 'RECOMMENDED'
      })
    }
  ).then(r => r.json());

  // Step 2: Display quote to user
  console.log(`You will receive: ${quote.data.amount}`);
  console.log(`Minimum amount: ${quote.data.minAmount}`);
  console.log(`Network fee: $${quote.data.networkFeeInUSD}`);
  console.log(`Estimated time: ${quote.data.estimatedArrivalTime}s`);

  // Step 3: Execute swap (after user confirmation)
  const swap = await fetch(
    `${baseUrl}/wallets/${walletId}/swaps/execute`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey
      },
      body: JSON.stringify({
        fromAssetId,
        toAssetId,
        amount,
        order: 'RECOMMENDED',
        reference: `swap-${Date.now()}`
      })
    }
  ).then(r => r.json());

  console.log('Swap initiated:', swap.data.id);
  console.log('Status:', swap.data.status);

  // Step 4: Listen for webhook to confirm completion
  return swap.data;
}

// Usage
executeSwap(
  'wallet-uuid',
  'asset_usdc_base_mainnet',
  'asset_usdt_bsc_mainnet',
  '100'
);
```

## Réponses d'erreur

<AccordionGroup>
  <Accordion title="Solde insuffisant">
    ```json theme={null}
    {
      "message": "Insufficient balance for swap",
      "statusCode": 400,
      "error": "INSUFFICIENT_BALANCE",
      "data": {
        "required": "100",
        "available": "50.25",
        "asset": "USDC"
      }
    }
    ```
  </Accordion>

  <Accordion title="Asset ID invalide">
    ```json theme={null}
    {
      "message": "Asset not found",
      "statusCode": 404,
      "error": "ASSET_NOT_FOUND",
      "data": {
        "assetId": "invalid_asset_id"
      }
    }
    ```
  </Accordion>

  <Accordion title="Route de swap indisponible">
    ```json theme={null}
    {
      "message": "No swap route available for this pair",
      "statusCode": 400,
      "error": "NO_ROUTE_AVAILABLE",
      "data": {
        "fromAsset": "USDC",
        "toAsset": "CUSTOM_TOKEN"
      }
    }
    ```
  </Accordion>

  <Accordion title="Montant trop faible">
    ```json theme={null}
    {
      "message": "Amount below minimum swap threshold",
      "statusCode": 400,
      "error": "AMOUNT_TOO_LOW",
      "data": {
        "minimum": "10",
        "provided": "1"
      }
    }
    ```
  </Accordion>

  <Accordion title="Slippage dépassé">
    ```json theme={null}
    {
      "message": "Price moved beyond slippage tolerance",
      "statusCode": 400,
      "error": "SLIPPAGE_EXCEEDED",
      "data": {
        "expectedAmount": "99.45",
        "actualAmount": "97.00",
        "slippageTolerance": "0.5%"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Bonnes pratiques

### Expérience utilisateur

* **Affichez toujours les devis** : montrez le montant, les frais et le temps estimé avant l'exécution
* **Gérez le slippage** : informez les utilisateurs des variations possibles de prix
* **Affichez la progression** : utilisez les webhooks pour informer les utilisateurs du statut du swap

### Sécurité

* **Validez les montants** : assurez-vous que les montants de swap se situent dans des plages acceptables
* **Utilisez des références** : suivez les swaps avec des identifiants de référence uniques
* **Surveillez les webhooks** : vérifiez toujours la finalisation du swap via les webhooks

### Performance

* **Mettez en cache les asset IDs** : stockez les asset IDs localement pour éviter des requêtes répétées
* **Utilisez les types d'ordres appropriés** : choisissez `FASTEST` pour les opérations sensibles au temps et `CHEAPEST` pour celles sensibles au coût
* **Implémentez des nouvelles tentatives** : gérez les défaillances transitoires avec un backoff exponentiel

## Référence de l'API

| Endpoint                                                                  | Description                                       |
| ------------------------------------------------------------------------- | ------------------------------------------------- |
| [Master Wallet Get Quote](/en/api-reference/swap/master-wallet-get-quote) | Obtenir un devis de swap depuis la master wallet  |
| [Master Wallet Execute](/en/api-reference/swap/master-wallet-execute)     | Exécuter un swap depuis la master wallet          |
| [Child Address Get Quote](/en/api-reference/swap/child-address-get-quote) | Obtenir un devis de swap depuis une child address |
| [Child Address Execute](/en/api-reference/swap/child-address-execute)     | Exécuter un swap depuis une child address         |

## Support

* **E-mail** : [support@blockradar.co](mailto:support@blockradar.co)
* **Documentation** : [Référence de l'API](/en/api-reference/swap/master-wallet-get-quote)
* **Blog** : [Comment swap ou bridge des actifs avec Blockradar](https://www.blockradar.co/blog/how-to-swap-or-bridge-assets-with-blockradar-a-follow-along-guide)

<Note>
  L'API Swap fournit une interface unifiée pour les swaps sur la même chaîne et les bridges entre chaînes. Commencez par de petits montants de test sur les testnets avant de passer en production.
</Note>