Swap et Bridge

En résumé
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.

Prérequis

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

Clé d'API

Obtenez votre clé d’API depuis le Dashboard Blockradar. Rendez-vous dans Developers pour en générer une.

Wallet créée

Créez une wallet via l’API Create Wallet ou depuis le dashboard. Vous aurez besoin du walletId pour les opérations de swap.

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.

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.

Fonctionnement

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 blockchains différentes.Exemple : USDC sur BSC → USDC sur Optimism

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.

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

La disponibilité des actifs varie selon la chaîne. Utilisez toujours l’API Get Assets pour récupérer la liste actualisée des actifs pris en charge et leurs valeurs assetId pour vos chaînes cibles.

Consultez la rubrique Intégrations pour la liste complète des réseaux et stablecoins pris en charge.

Master Wallet vs Child Address

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.

Child Address

Exécutez des swaps depuis des child addresses individuelles. Parfait pour les opérations spécifiques à un utilisateur.

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

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

Réponse du 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 (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

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

É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

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

Réponse de l’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 indique le statut PENDING. Écoutez le webhook swap.success ou swap.failed pour confirmer la finalisation.

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

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

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

Solde insuffisant

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

Asset ID invalide

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

Route de swap indisponible

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

Montant trop faible

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

Slippage dépassé

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

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	Obtenir un devis de swap depuis la master wallet
Master Wallet Execute	Exécuter un swap depuis la master wallet
Child Address Get Quote	Obtenir un devis de swap depuis une child address
Child Address Execute	Exécuter un swap depuis une child address

Support

E-mail : [email protected]
Documentation : Référence de l’API
Blog : Comment swap ou bridge 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 par de petits montants de test sur les testnets avant de passer en production.

Démarrage

Portefeuilles

Encaissements

Paiements

Convertir et Gérer

Conformité et Outils

Prérequis

Fonctionnement

Swap

Bridge

Actifs et chaînes pris en charge

Master Wallet vs Child Address

Master Wallet

Child Address

Endpoints

Étape 1 : Obtenir un devis

Paramètres de la requête

Exemple de devis

Réponse du devis

Comprendre les champs du devis

Étape 2 : Exécuter le Swap

Paramètres de la requête

Exemple d’exécution

Réponse de l’exécution

Types d’ordres

Événements Webhook

Charge utile du Webhook

Exemple de flux complet

Réponses d’erreur

Bonnes pratiques

Expérience utilisateur

Sécurité

Performance

Référence de l’API

Support

Démarrage

Portefeuilles

Encaissements

Paiements

Convertir et Gérer

Conformité et Outils

Documentation Index

​Prérequis

​Fonctionnement

Swap

Bridge

​Actifs et chaînes pris en charge

​Master Wallet vs Child Address

Master Wallet

Child Address

​Endpoints

​Étape 1 : Obtenir un devis

​Paramètres de la requête

​Exemple de devis

​Réponse du devis

​Comprendre les champs du devis

​Étape 2 : Exécuter le Swap

​Paramètres de la requête

​Exemple d’exécution

​Réponse de l’exécution

​Types d’ordres

​Événements Webhook

​Charge utile du Webhook

​Exemple de flux complet

​Réponses d’erreur

​Bonnes pratiques

​Expérience utilisateur

​Sécurité

​Performance

​Référence de l’API

​Support

Prérequis

Fonctionnement

Actifs et chaînes pris en charge

Master Wallet vs Child Address

Endpoints

Étape 1 : Obtenir un devis

Paramètres de la requête

Exemple de devis

Réponse du devis

Comprendre les champs du devis

Étape 2 : Exécuter le Swap

Paramètres de la requête

Exemple d’exécution

Réponse de l’exécution

Types d’ordres

Événements Webhook

Charge utile du Webhook

Exemple de flux complet

Réponses d’erreur

Bonnes pratiques

Expérience utilisateur

Sécurité

Performance

Référence de l’API

Support