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 depuis le dashboard (voir Créer un Portefeuille Principal). 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 source lorsque `amountSide` vaut `source`, ou le montant de destination lorsque `amountSide` vaut `target`
`amountSide`	string	Non	`source` ou `target`. Par défaut : `source`. Utilisez `target` pour obtenir ou exécuter un montant de destination exact
`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)
`recipientRouting`	object	Non	Routage uniquement pour Stellar : `{ type: "none" }` ou `{ type: "memo_id", value: "<numeric string>" }`. Omettez-le pour les destinations EVM, Solana et Tron.

Utilisez amountSide: "source" lorsque l’utilisateur saisit le montant à dépenser. Utilisez amountSide: "target" lorsque l’utilisateur saisit le montant à recevoir et que Blockradar doit résoudre le montant source requis.

Routage du destinataire Stellar

recipientRouting est pris en charge uniquement lorsque la chaîne de destination est Stellar. Il s’agit d’un contrat de routage générique partagé par tous les endpoints de devis et d’exécution de ce guide. Les requêtes EVM, Solana et Tron existantes ne sont pas affectées et restent inchangées : elles ne doivent pas envoyer recipientRouting ; les requêtes qui l’incluent sont rejetées. recipientAddress reste une chaîne facultative ; ne l’envoyez pas sous forme d’objet. N’envoyez pas de champ de mémo de destinataire distinct.

Règles de destination Stellar

Destinataire muxed M... : omettez recipientRouting. L’identifiant de routage est intégré dans l’adresse muxed, et fournir des données de routage est rejeté.
Destinataire de base G... avec identifiant de routage : envoyez { type: "memo_id", value: "123" }. value doit être une chaîne numérique non vide comprise entre 0 et 18446744073709551615. Blockradar normalise l’adresse en M... avant de demander le devis ou l’exécution.
Destinataire de base G... sans identifiant de routage : envoyez { type: "none" } sans inclure value. Un destinataire G... sans recipientRouting est rejeté. Le compte de base de destination doit avoir une trustline Stellar USDC avant le devis ou l’exécution.
Portefeuille Stellar Blockradar par défaut : envoyez explicitement { type: "none" } dans recipientRouting.

Exemples de requêtes

Tous les exemples utilisent la même structure de corps sur chacun de ces endpoints :

POST /v1/wallets/{walletId}/swaps/quote
POST /v1/wallets/{walletId}/swaps/execute
POST /v1/wallets/{walletId}/addresses/{addressId}/swaps/quote
POST /v1/wallets/{walletId}/addresses/{addressId}/swaps/execute

Non-Stellar destination — no routing field

{
  "fromAssetId": "asset_usdc_base_mainnet",
  "toAssetId": "asset_usdt_bsc_mainnet",
  "amount": "100",
  "recipientAddress": "0x2455eC6700092991Ce0782365A89d5Cd89c8Fa22"
}

Stellar G... without a routing ID

{
  "fromAssetId": "asset_usdc_base_mainnet",
  "toAssetId": "asset_usdc_stellar_mainnet",
  "amount": "100",
  "recipientAddress": "G...",
  "recipientRouting": {
    "type": "none"
  }
}

Stellar G... with a routing ID

{
  "fromAssetId": "asset_usdc_base_mainnet",
  "toAssetId": "asset_usdc_stellar_mainnet",
  "amount": "100",
  "recipientAddress": "G...",
  "recipientRouting": {
    "type": "memo_id",
    "value": "123"
  }
}

Stellar M... recipient — no routing field

{
  "fromAssetId": "asset_usdc_base_mainnet",
  "toAssetId": "asset_usdc_stellar_mainnet",
  "amount": "100",
  "recipientAddress": "M..."
}

Default Blockradar Stellar wallet

{
  "fromAssetId": "asset_usdc_base_mainnet",
  "toAssetId": "asset_usdc_stellar_mainnet",
  "amount": "100",
  "recipientRouting": {
    "type": "none"
  }
}

Migration depuis les champs spécifiques à Stellar

Ancien champ	Remplacement
`recipientMemoId`	`recipientRouting: { type: "memo_id", value: "<numeric string>" }`
`stellarMemoNotRequired: true`	`recipientRouting: { type: "none" }`

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",
    "amountSide": "source",
    "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',
      amountSide: 'source',
      order: 'RECOMMENDED'
    })
  }
).then(r => r.json());

console.log('Quote:', quote.data);

Réponse du devis

{
  "message": "Swap quote fetched successfully",
  "statusCode": 200,
  "data": {
    "amount": "99.45",
    "fromAmount": "100",
    "toAmount": "99.45",
    "requestedAmount": "100",
    "amountSide": "source",
    "minAmount": "98.95",
    "rate": "0.9945",
    "impact": "0.12",
    "slippage": "0.5",
    "networkFee": "0.002",
    "networkFeeInUSD": "0.15",
    "estimatedArrivalTime": 180,
    "recipientRouting": {
      "status": "none",
      "message": "No recipient routing value will be used. Confirm the destination accepts direct deposits without one."
    }
  }
}

Pour une destination muxed, data.recipientRouting peut au contraire indiquer que l’identifiant de routage est intégré dans l’adresse de destination normalisée :

{
  "recipientRouting": {
    "status": "embedded",
    "message": "The recipient routing ID is embedded in the normalized destination address."
  }
}

data.recipientRouting est facultatif et n’est renvoyé que par les réponses de devis. Ne vous attendez pas à le trouver dans les réponses d’exécution.

Comprendre les champs du devis

Champ	Description
`amount`	Montant de destination estimé à recevoir. Pour les devis côté destination, il s’agit du montant de destination demandé
`fromAmount`	Montant de l’actif source requis pour le devis
`toAmount`	Montant de l’actif de destination renvoyé par le devis
`requestedAmount`	Montant original envoyé dans la requête
`amountSide`	Indique si `requestedAmount` représente le montant source ou le montant de destination
`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
`recipientRouting`	Métadonnées de routage Stellar facultatives. `none` signifie qu’aucune valeur de routage n’est utilisée ; `embedded` signifie qu’elle est intégrée dans l’adresse de destination normalisée.

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 source lorsque `amountSide` vaut `source`, ou le montant de destination lorsque `amountSide` vaut `target`
`amountSide`	string	Non	`source` ou `target`. Par défaut : `source`. Utilisez `target` pour obtenir ou exécuter un montant de destination exact
`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)
`recipientRouting`	object	Non	Routage uniquement pour Stellar. Utilisez la même valeur que dans la requête de devis ; omettez-le pour les destinations EVM, Solana et Tron.
`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",
    "amountSide": "source",
    "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',
      amountSide: 'source',
      order: 'RECOMMENDED',
      reference: 'swap-order-12345',
      metadata: {
        userId: 'user_abc123',
        orderId: 'order_xyz789'
      }
    })
  }
).then(r => r.json());

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

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, amountSide = 'source') {
  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,
        amountSide,
        order: 'RECOMMENDED'
      })
    }
  ).then(r => r.json());

  // Step 2: Display quote to user
  console.log(`You will receive: ${quote.data.toAmount}`);
  console.log(`Required source amount: ${quote.data.fromAmount}`);
  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,
        amountSide,
        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

Routage du destinataire Stellar

Règles de destination Stellar

Exemples de requêtes

Migration depuis les champs spécifiques à Stellar

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

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

​Routage du destinataire Stellar

​Règles de destination Stellar

​Exemples de requêtes

​Migration depuis les champs spécifiques à Stellar

​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

Routage du destinataire Stellar

Règles de destination Stellar

Exemples de requêtes

Migration depuis les champs spécifiques à Stellar

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