Passer au contenu principal
É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 :
1

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

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

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

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 :
StablecoinDescription
USDTTether USD
USDCUSD Coin
DAIDai Stablecoin
BUSDBinance USD
cNGNStablecoin Naira
EURCEuro Coin
IDRXStablecoin Indonésien
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érationMaster WalletAdresse Enfant
Obtenir DevisPOST /v1/wallets/{walletId}/swaps/quotePOST /v1/wallets/{walletId}/addresses/{addressId}/swaps/quote
ExécuterPOST /v1/wallets/{walletId}/swaps/executePOST /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ètreTypeRequisDescription
fromAssetIdstringOuiL’ID de l’actif à échanger
toAssetIdstringOuiL’ID de l’actif vers lequel échanger
amountstringOuiLe montant à échanger
orderstringNonPréférence de devis : FASTEST, CHEAPEST, RECOMMENDED, NO_SLIPPAGE
recipientAddressstringNonAdresse 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 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

ChampDescription
amountMontant estimé que vous recevrez après le swap
minAmountMontant minimum garanti (tenant compte du glissement)
rateTaux de change effectif (montantDestination / montantSource)
impactPourcentage d’impact sur le prix
slippagePourcentage maximum autorisé de mouvement de prix
networkFeeFrais de gas en unités du token natif
networkFeeInUSDFrais de gas convertis en USD
estimatedArrivalTimeTemps 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ètreTypeRequisDescription
fromAssetIdstringOuiL’ID de l’actif à échanger
toAssetIdstringOuiL’ID de l’actif vers lequel échanger
amountstringOuiLe montant à échanger
orderstringNonPréférence de devis : FASTEST, CHEAPEST, RECOMMENDED, NO_SLIPPAGE
recipientAddressstringNonAdresse de wallet externe (pour envoyer vers des wallets non-Blockradar)
referencestringNonVotre ID de suivi interne
metadataobjectNonDonné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"
    }
  }'

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’OrdreDescriptionIdéal Pour
FASTESTPriorise la vitesse sur le coûtTransactions sensibles au temps
CHEAPESTMinimise les fraisOpérations sensibles au coût
RECOMMENDEDApproche équilibrée (par défaut)La plupart des cas d’utilisation
NO_SLIPPAGEMontant exact ou échecExigences de montant précis

Événements Webhook

Surveillez la finalisation du swap via les webhooks :
ÉvénementDescription
swap.successSwap complété avec succès
swap.failedSwap é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

{
  "message": "Insufficient balance for swap",
  "statusCode": 400,
  "error": "INSUFFICIENT_BALANCE",
  "data": {
    "required": "100",
    "available": "50.25",
    "asset": "USDC"
  }
}
{
  "message": "Asset not found",
  "statusCode": 404,
  "error": "ASSET_NOT_FOUND",
  "data": {
    "assetId": "invalid_asset_id"
  }
}
{
  "message": "No swap route available for this pair",
  "statusCode": 400,
  "error": "NO_ROUTE_AVAILABLE",
  "data": {
    "fromAsset": "USDC",
    "toAsset": "CUSTOM_TOKEN"
  }
}
{
  "message": "Amount below minimum swap threshold",
  "statusCode": 400,
  "error": "AMOUNT_TOO_LOW",
  "data": {
    "minimum": "10",
    "provided": "1"
  }
}
{
  "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

EndpointDescription
Master Wallet Obtenir DevisObtenir un devis de swap depuis le master wallet
Master Wallet ExécuterExécuter un swap depuis le master wallet
Adresse Enfant Obtenir DevisObtenir un devis de swap depuis une adresse enfant
Adresse Enfant ExécuterExécuter un swap depuis une adresse enfant

Support

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.