Échange & Pont

En bref
L’API Swap de Blockradar 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é.

Prérequis

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

Clé API

Obtenez votre clé API depuis le Tableau de bord Blockradar. Naviguez vers Paramètres → Clés API pour en générer une.

Wallet Créé

Créez un wallet via l’API Créer Wallet ou le tableau de bord. Vous aurez besoin du walletId pour les opérations de swap.

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.

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.

Comment Ça Marche

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

Swap

Échangez différents actifs sur la même blockchain.Exemple : USDC → USDT sur Base

Bridge

Déplacez des actifs entre différentes blockchains.Exemple : USDC sur BSC → USDC sur Optimism

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.

Actifs et Chaînes Supportés

L’API Swap supporte les principales stablecoins sur les chaînes supportées par 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

La disponibilité des actifs varie selon la chaîne. Utilisez toujours l’API Obtenir Actifs pour récupérer la liste actuelle des actifs supportés et leurs valeurs assetId pour vos chaînes cibles.

Voir Intégrations pour la liste complète des réseaux et stablecoins supportés.

Master Wallet vs Adresse Enfant

L’API Swap est disponible à deux niveaux :

Master Wallet

Exécutez des swaps directement depuis votre master wallet. Idéal pour les opérations de trésorerie.

Adresse Enfant

Exécutez des swaps depuis des adresses enfants individuelles. Parfait pour les opérations spécifiques aux utilisateurs.

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

Exemple de Devis

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

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('Devis:', quote.data);

Réponse de Devis

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

Affichez toujours au minimum : montant à recevoir, temps d’arrivée estimé et frais avant que l’utilisateur confirme le swap.

É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-Blockradar)
`reference`	string	Non	Votre ID de suivi interne
`metadata`	object	Non	Données personnalisées transmises via webhooks

Exemple d’Exécution

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

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 initié:', swap.data);

Réponse d’Exécution

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

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.

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

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

async function executeSwap(walletId, fromAssetId, toAssetId, amount) {
  const apiKey = process.env.BLOCKRADAR_API_KEY;
  const baseUrl = 'https://api.blockradar.co/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

Solde Insuffisant

{
  "message": "Insufficient balance for swap",
  "statusCode": 400,
  "error": "INSUFFICIENT_BALANCE",
  "data": {
    "required": "100",
    "available": "50.25",
    "asset": "USDC"
  }
}

ID d'Actif Invalide

{
  "message": "Asset not found",
  "statusCode": 404,
  "error": "ASSET_NOT_FOUND",
  "data": {
    "assetId": "invalid_asset_id"
  }
}

Route de Swap Non Disponible

{
  "message": "No swap route available for this pair",
  "statusCode": 400,
  "error": "NO_ROUTE_AVAILABLE",
  "data": {
    "fromAsset": "USDC",
    "toAsset": "CUSTOM_TOKEN"
  }
}

Montant Trop Bas

{
  "message": "Amount below minimum swap threshold",
  "statusCode": 400,
  "error": "AMOUNT_TOO_LOW",
  "data": {
    "minimum": "10",
    "provided": "1"
  }
}

Glissement Dépassé

{
  "message": "Price moved beyond slippage tolerance",
  "statusCode": 400,
  "error": "SLIPPAGE_EXCEEDED",
  "data": {
    "expectedAmount": "99.45",
    "actualAmount": "97.00",
    "slippageTolerance": "0.5%"
  }
}

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	Obtenir un devis de swap depuis le master wallet
Master Wallet Exécuter	Exécuter un swap depuis le master wallet
Adresse Enfant Obtenir Devis	Obtenir un devis de swap depuis une adresse enfant
Adresse Enfant Exécuter	Exécuter un swap depuis une adresse enfant

Support

Email : [email protected]
Documentation : Référence API
Blog : Comment Échanger ou Ponter des Actifs avec Blockradar

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.

Get Started

Wallets

Receive Payments

Send Payments

Convert & Manage

Compliance & Recovery

Integrations

Prérequis

Comment Ça Marche

Swap

Bridge

Actifs et Chaînes Supportés

Master Wallet vs Adresse Enfant

Master Wallet

Adresse Enfant

Endpoints

Étape 1 : Obtenir un Devis

Paramètres de Requête

Exemple de Devis

Réponse de Devis

Comprendre les Champs du Devis

Étape 2 : Exécuter le Swap

Paramètres de Requête

Exemple d’Exécution

Réponse d’Exécution

Types d’Ordre

Événements Webhook

Payload du Webhook

Exemple de Flux Complet

Réponses d’Erreur

Meilleures Pratiques

Expérience Utilisateur

Sécurité

Performance

Référence API

Support

​Prérequis

​Comment Ça Marche

Swap

Bridge

​Actifs et Chaînes Supportés

​Master Wallet vs Adresse Enfant

Master Wallet

Adresse Enfant

​Endpoints

​Étape 1 : Obtenir un Devis

​Paramètres de Requête

​Exemple de Devis

​Réponse de Devis

​Comprendre les Champs du Devis

​Étape 2 : Exécuter le Swap

​Paramètres de Requête

​Exemple d’Exécution

​Réponse d’Exécution

​Types d’Ordre

​Événements Webhook

​Payload du Webhook

​Exemple de Flux Complet

​Réponses d’Erreur

​Meilleures Pratiques

​Expérience Utilisateur

​Sécurité

​Performance

​Référence API

​Support

Prérequis

Comment Ça Marche

Actifs et Chaînes Supportés

Master Wallet vs Adresse Enfant

Endpoints

Étape 1 : Obtenir un Devis

Paramètres de Requête

Exemple de Devis

Réponse de Devis

Comprendre les Champs du Devis

Étape 2 : Exécuter le Swap

Paramètres de Requête

Exemple d’Exécution

Réponse d’Exécution

Types d’Ordre

Événements Webhook

Payload du Webhook

Exemple de Flux Complet

Réponses d’Erreur

Meilleures Pratiques

Expérience Utilisateur

Sécurité

Performance

Référence API

Support