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

# Échange & Pont

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

<Note>
  En bref<br />
  L'API Swap de Yiksi Pay vous permet d'échanger des actifs sur la même chaîne (swap) ou de déplacer des actifs entre différentes chaînes (bridge) en utilisant un seul endpoint unifié.
</Note>

## Prérequis

Avant d'utiliser l'API Swap, assurez-vous d'avoir :

<Steps>
  <Step title="Clé API">
    Obtenez votre clé API depuis le [Tableau de bord Yiksi Pay](https://dashboard.yiksipay.com). Naviguez vers **Paramètres → Clés API** pour en générer une.
  </Step>

  <Step title="Wallet Créé">
    Créez un wallet via l'[API Créer Wallet](/fr/api-reference/wallets/create-wallet) ou le tableau de bord. Vous aurez besoin du `walletId` pour les opérations de swap.
  </Step>

  <Step title="IDs d'Actifs">
    Obtenez l'`assetId` pour vos actifs source et destination depuis **Actifs** dans le tableau de bord ou via l'[API Obtenir Actifs](/fr/api-reference/miscellaneous/get-assets).
  </Step>

  <Step title="Solde Suffisant">
    Assurez-vous que votre wallet a un solde suffisant de l'actif source pour couvrir le montant du swap plus les frais de réseau.
  </Step>
</Steps>

## Comment Ça Marche

Yiksi Pay 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 **différentes blockchains**.

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

<Tip>
  Vous n'avez pas besoin de spécifier s'il s'agit d'un swap ou d'un bridge—l'API gère cela automatiquement en fonction du `fromAssetId` et du `toAssetId` que vous fournissez.
</Tip>

## Actifs et Chaînes Supportés

L'API Swap supporte les principales stablecoins sur les chaînes supportées par Yiksi Pay :

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

<Warning>
  La disponibilité des actifs varie selon la chaîne. Utilisez toujours l'[API Obtenir Actifs](/fr/api-reference/miscellaneous/get-assets) pour récupérer la liste actuelle des actifs supportés et leurs valeurs `assetId` pour vos chaînes cibles.
</Warning>

<Note>
  Voir [Intégrations](/fr/essentials/integrations) pour la liste complète des réseaux et stablecoins supportés.
</Note>

## Master Wallet vs Adresse Enfant

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="Adresse Enfant" icon="address-card">
    Exécutez des swaps depuis des adresses enfants individuelles. Parfait pour les opérations spécifiques aux utilisateurs.
  </Card>
</CardGroup>

### Endpoints

| Opération     | Master Wallet                               | Adresse Enfant                                                    |
| ------------- | ------------------------------------------- | ----------------------------------------------------------------- |
| Obtenir 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

Obtenez toujours un devis avant d'exécuter un swap pour montrer aux utilisateurs le résultat attendu.

### Paramètres de Requête

| Paramètre          | Type   | Requis | Description                                                               |
| ------------------ | ------ | ------ | ------------------------------------------------------------------------- |
| `fromAssetId`      | string | Oui    | L'ID de l'actif à échanger                                                |
| `toAssetId`        | string | Oui    | L'ID de l'actif vers lequel échanger                                      |
| `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-Yiksi Pay)   |

### Exemple de Devis

<CodeGroup>
  ```bash Curl theme={null}
  curl --request POST \
    --url https://api.yiksipay.com/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.yiksipay.com/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('Devis:', quote.data);
  ```
</CodeGroup>

### Réponse de 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 (tenant compte du glissement)        |
| `rate`                 | Taux de change effectif (montantDestination / montantSource) |
| `impact`               | Pourcentage d'impact sur le prix                             |
| `slippage`             | Pourcentage maximum autorisé de mouvement de prix            |
| `networkFee`           | Frais de gas en unités du token natif                        |
| `networkFeeInUSD`      | Frais de gas convertis en USD                                |
| `estimatedArrivalTime` | Temps de finalisation estimé en secondes                     |

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

## Étape 2 : Exécuter le Swap

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

### Paramètres de Requête

| Paramètre          | Type   | Requis | Description                                                               |
| ------------------ | ------ | ------ | ------------------------------------------------------------------------- |
| `fromAssetId`      | string | Oui    | L'ID de l'actif à échanger                                                |
| `toAssetId`        | string | Oui    | L'ID de l'actif vers lequel échanger                                      |
| `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-Yiksi Pay)   |
| `reference`        | string | Non    | Votre ID de suivi interne                                                 |
| `metadata`         | object | Non    | Données personnalisées transmises via webhooks                            |

### Exemple d'Exécution

<CodeGroup>
  ```bash Curl theme={null}
  curl --request POST \
    --url https://api.yiksipay.com/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.yiksipay.com/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 initié:', swap.data);
  ```
</CodeGroup>

### Réponse d'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 affiche le statut `PENDING`. Écoutez le webhook `swap.success` ou `swap.failed` pour confirmer la finalisation.
</Warning>

## Types d'Ordre

Choisissez le bon type d'ordre selon votre cas d'utilisation :

| Type d'Ordre  | Description                      | Idéal Pour                       |
| ------------- | -------------------------------- | -------------------------------- |
| `FASTEST`     | Priorise la vitesse sur le 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 d'utilisation |
| `NO_SLIPPAGE` | Montant exact ou échec           | Exigences de montant précis      |

## Événements Webhook

Surveillez la finalisation du swap via les webhooks :

| Événement      | Description               |
| -------------- | ------------------------- |
| `swap.success` | Swap complété avec succès |
| `swap.failed`  | Swap échoué               |

### Payload 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 montrant le flux devis → confirmer → exécuter :

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

  // Étape 1 : Obtenir le devis
  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());

  // Étape 2 : Afficher le devis à l'utilisateur
  console.log(`Vous recevrez: ${quote.data.amount}`);
  console.log(`Montant minimum: ${quote.data.minAmount}`);
  console.log(`Frais de réseau: $${quote.data.networkFeeInUSD}`);
  console.log(`Temps estimé: ${quote.data.estimatedArrivalTime}s`);

  // Étape 3 : Exécuter le swap (après confirmation de l'utilisateur)
  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 initié:', swap.data.id);
  console.log('Statut:', swap.data.status);

  // Étape 4 : Écouter le webhook pour confirmer la finalisation
  return swap.data;
}

// Utilisation
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="ID d'Actif 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 Non Disponible">
    ```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 Bas">
    ```json theme={null}
    {
      "message": "Amount below minimum swap threshold",
      "statusCode": 400,
      "error": "AMOUNT_TOO_LOW",
      "data": {
        "minimum": "10",
        "provided": "1"
      }
    }
    ```
  </Accordion>

  <Accordion title="Glissement 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>

## Meilleures Pratiques

### Expérience Utilisateur

* **Toujours afficher les devis** : Montrez le montant, les frais et le temps estimé avant l'exécution
* **Gérer le glissement** : Informez les utilisateurs des variations de prix potentielles
* **Afficher la progression** : Utilisez les webhooks pour mettre à jour les utilisateurs sur le statut du swap

### Sécurité

* **Valider les montants** : Assurez-vous que les montants de swap sont dans des plages acceptables
* **Utiliser des références** : Suivez les swaps avec des IDs de référence uniques
* **Surveiller les webhooks** : Vérifiez toujours la finalisation du swap via les webhooks

### Performance

* **Mettre en cache les IDs d'actifs** : Stockez les IDs d'actifs localement pour éviter les recherches répétées
* **Utiliser les types d'ordre appropriés** : Choisissez `FASTEST` pour le temps sensible, `CHEAPEST` pour le coût sensible
* **Implémenter les réessais** : Gérez les échecs transitoires avec un backoff exponentiel

## Référence API

| Endpoint                                                                       | Description                                        |
| ------------------------------------------------------------------------------ | -------------------------------------------------- |
| [Master Wallet Obtenir Devis](/fr/api-reference/swap/master-wallet-get-quote)  | Obtenir un devis de swap depuis le master wallet   |
| [Master Wallet Exécuter](/fr/api-reference/swap/master-wallet-execute)         | Exécuter un swap depuis le master wallet           |
| [Adresse Enfant Obtenir Devis](/fr/api-reference/swap/child-address-get-quote) | Obtenir un devis de swap depuis une adresse enfant |
| [Adresse Enfant Exécuter](/fr/api-reference/swap/child-address-execute)        | Exécuter un swap depuis une adresse enfant         |

## Support

* **Email** : [partner@yiksi.com](mailto:partner@yiksi.com)
* **Documentation** : [Référence API](/fr/api-reference/swap/master-wallet-get-quote)

<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 avec de petits montants de test sur les testnets avant de passer en production.
</Note>