Passer au contenu principal
En bref
L’API Retrait Fiat de Blockradar vous permet de convertir des stablecoins pris en charge en monnaie fiduciaire et de transférer des fonds vers des comptes bancaires. Vous pouvez récupérer les actifs pris en charge, valider des comptes bancaires, obtenir des devis et exécuter des retraits depuis des portefeuilles principaux ou des adresses enfants.
Interface Retrait Fiat Blockradar

Prérequis

Avant d’utiliser Retrait Fiat, assurez-vous de disposer des éléments suivants :
1

Exigence de conformité

Finalisez l’onboarding partenaire avant de demander l’accès à Retrait Fiat (voir Exigences de conformité ci-dessous).
2

Clé API

Obtenez votre clé API depuis le Tableau de bord Blockradar. Accédez à Developers pour en générer une.
3

Portefeuille créé

Créez un portefeuille via le tableau de bord. Vous aurez besoin du walletId pour les opérations de retrait.
4

ID d'actif

Récupérez les actifs fiat pris en charge via Obtenir les actifs pris en charge.
5

Informations bancaires

Préparez un identifiant de compte valide et un identifiant d’institution (code bancaire).

Fonctionnement

Retrait Fiat suit une séquence simple :

Découvrir les actifs

Récupérez les actifs pris en charge pour les retraits.

Obtenir les devises fiat

Récupérez toutes les devises prises en charge.

Obtenir les taux

Récupérez le taux de change actuel pour l’actif sélectionné.

Vérifier le compte

Validez les informations du compte bancaire avant de lancer un retrait.

Obtenir un devis

Estimez les frais et le taux de change pour le montant demandé.

Exécuter

Soumettez le retrait au traitement.

Exigences de conformité

Avant d’accéder à Retrait Fiat, finalisez le processus d’onboarding conformité adapté à la couverture de devise de paiement souhaitée.

Choisissez votre parcours d’onboarding

Si vous avez besoin d’un accès à la fois au NGN et à d’autres devises africaines prises en charge, complétez les deux parcours d’onboarding.

Exigence d’approbation

L’accès à Retrait Fiat est activé après revue de conformité et approbation pour le parcours d’onboarding sélectionné.

Portefeuille principal vs adresse enfant

Retrait Fiat est disponible à deux niveaux :

Portefeuille principal

Retirez depuis le portefeuille principal. Idéal pour les opérations de trésorerie.

Adresse enfant

Retirez depuis une adresse enfant spécifique. Utile pour les flux par utilisateur.

Endpoints

OpérationPortefeuille principalAdresse enfant
Obtenir les actifs pris en chargeGET /v1/wallets/{walletId}/withdraw/fiat/assets
Obtenir les institutionsGET /v1/wallets/{walletId}/withdraw/fiat/institutions
Obtenir les taux de changeGET /v1/wallets/{walletId}/withdraw/fiat/rates
Obtenir les devisesGET /v1/wallets/{walletId}/withdraw/fiat/currencies
Vérifier le compte de l’institutionPOST /v1/wallets/{walletId}/withdraw/fiat/institution-account-verification
Obtenir un devisPOST /v1/wallets/{walletId}/withdraw/fiat/quotePOST /v1/wallets/{walletId}/addresses/{addressId}/withdraw/fiat/quote
ExécuterPOST /v1/wallets/{walletId}/withdraw/fiat/executePOST /v1/wallets/{walletId}/addresses/{addressId}/withdraw/fiat/execute

Flux type

  1. Récupérez les actifs pris en charge pour choisir le stablecoin à retirer.
  2. Listez les institutions et sélectionnez un identifiant de banque/institution.
  3. Vérifiez le compte pour confirmer le nom et les informations du compte.
  4. Obtenez un devis pour afficher frais et taux avant exécution.
  5. Exécutez le retrait et suivez son statut dans votre système.

Étape 1 : Obtenir un devis

Récupérez toujours un devis avant d’exécuter un retrait afin d’afficher le taux et les frais à l’utilisateur.

Paramètres de la requête

ParamètreTypeRequisDescription
assetIdstringOuiID de l’actif stablecoin à retirer
amountnumberOuiMontant à retirer dans l’unité de l’actif
currencystringOuiDevise fiat de destination (ex. NGN)
accountIdentifierstringOuiNuméro de compte bancaire ou identifiant
institutionIdentifierstringOuiCode de la banque/institution

Exemple de devis

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/withdraw/fiat/quote \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "assetId": "asset-uuid-here",
    "amount": 1000,
    "currency": "NGN",
    "accountIdentifier": "0023103996",
    "institutionIdentifier": "SBICNGLA"
  }'

Étape 2 : Exécuter le retrait

Une fois le devis accepté, exécutez le retrait avec les mêmes informations (et tout code/OTP requis).

Paramètres de la requête

ParamètreTypeRequisDescription
assetIdstringOuiID de l’actif stablecoin à retirer
amountnumberOuiMontant à retirer dans l’unité de l’actif
currencystringOuiDevise fiat de destination (ex. NGN)
accountIdentifierstringOuiNuméro de compte bancaire ou identifiant
institutionIdentifierstringOuiCode de la banque/institution
codestringNonCode de vérification si requis par le fournisseur

Exemple d’exécution

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/withdraw/fiat/execute \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "assetId": "asset-uuid-here",
    "amount": 1000,
    "currency": "NGN",
    "accountIdentifier": "8034007516",
    "institutionIdentifier": "OPAYNGPC",
    "code": "445223"
  }'

Réponse d’exécution

{
  "message": "Withdrawal initiated successfully",
  "status": true,
  "data": {
    "id": "withdrawal-uuid",
    "status": "processing",
    "amount": 1000,
    "currency": "NGN"
  }
}

Webhooks

Suivez l’état du retrait avec les événements webhook suivants :
ÉvénementDescription
offramp.processingLe retrait est en cours de traitement
offramp.successLe retrait a été effectué avec succès
offramp.failedLe retrait a échoué

Exemple de payload webhook

{
  "event": "offramp.processing",
  "data": {
    "id": "d2b985da-7f7e-4494-a6bc-0e675d50eed3",
    "reference": "EVF2g9X70Sj4hoX3ma8l",
    "senderAddress": "0x969838345E5cd5F755DfcADB57e72F5d23271e48",
    "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "0.5",
    "amountPaid": "0.5",
    "amountUSD": "0.4998",
    "rateUSD": "0.9996",
    "fee": "0",
    "feeUSD": null,
    "currency": "USD",
    "toCurrency": "NGN",
    "status": "PROCESSING",
    "processingStatus": "SUCCESS",
    "processingProviderReference": "0x25003cb8356c92e3c296e7dd384ead681c5f57fb6182760fa4178750464ffd35",
    "processingReason": null,
    "type": "OFFRAMP",
    "createdChannel": "api",
    "network": "mainnet",
    "chainId": 8453,
    "metadata": null,
    "toAmount": "711.21",
    "rate": "1422.42",
    "beneficiary": {
      "id": "4dd8d16e-8550-4f51-84a1-60df9c608c5d",
      "name": "JOHN DOE",
      "type": "FIAT",
      "isActive": true,
      "reference": "d7dd5c7cf57acb5e2ff62eb23bceaca84d5dad6e62fec3d3836f20cfa1ea735c",
      "institutionIdentifier": "OPAYNGPC",
      "institutionAccountIdentifier": "8030303030",
      "currency": "NGN"
    }
  }
}

Exemple de flux complet

Voici une implémentation complète du flux vérifier → devis → exécuter :
async function executeFiatWithdrawal({
  walletId,
  currency,
  accountIdentifier,
  code,
}) {
  const apiKey = process.env.BLOCKRADAR_API_KEY;
  const baseUrl = "https://api.blockradar.co/v1";
  const headers = { "x-api-key": apiKey };

  // Step 1: Get supported assets
  const assetsRes = await fetch(
    `${baseUrl}/wallets/${walletId}/withdraw/fiat/assets`,
    { headers },
  ).then((r) => r.json());

  // Pick the first asset (example)
  const assetId = assetsRes.data?.[0]?.asset?.id;

  // Step 2: Get supported currencies
  const currenciesRes = await fetch(
    `${baseUrl}/wallets/${walletId}/withdraw/fiat/currencies`,
    { headers },
  ).then((r) => r.json());

  console.log("Supported currencies:", currenciesRes.data);

  // Step 3: Get institutions for the currency
  const institutionsRes = await fetch(
    `${baseUrl}/wallets/${walletId}/withdraw/fiat/institutions?currency=${currency}`,
    { headers },
  ).then((r) => r.json());

  // Pick the first institution (example)
  const institutionIdentifier = institutionsRes.data?.[0]?.code;

  // Step 4: Verify account
  const verification = await fetch(
    `${baseUrl}/wallets/${walletId}/withdraw/fiat/institution-account-verification`,
    {
      method: "POST",
      headers: {
        ...headers,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        accountIdentifier,
        currency,
        institutionIdentifier,
      }),
    },
  ).then((r) => r.json());

  console.log("Account name:", verification.data?.accountName);

  // Step 5: Get exchange rate (optional)
  const amount = 1000;
  const ratesRes = await fetch(
    `${baseUrl}/wallets/${walletId}/withdraw/fiat/rates?currency=${currency}&assetId=${assetId}&amount=${amount}&providerId=${institutionIdentifier}`,
    { headers },
  ).then((r) => r.json());

  console.log("Rate:", ratesRes.data);

  // Step 6: Get quote
  const quote = await fetch(
    `${baseUrl}/wallets/${walletId}/withdraw/fiat/quote`,
    {
      method: "POST",
      headers: {
        ...headers,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        assetId,
        amount,
        currency,
        accountIdentifier,
        institutionIdentifier,
      }),
    },
  ).then((r) => r.json());

  console.log("Estimated arrival:", quote.data?.estimatedArrivalTime);
  console.log("Network fee:", quote.data?.networkFee);

  // Step 7: Execute (after user confirmation)
  const execution = await fetch(
    `${baseUrl}/wallets/${walletId}/withdraw/fiat/execute`,
    {
      method: "POST",
      headers: {
        ...headers,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        assetId,
        amount,
        currency,
        accountIdentifier,
        institutionIdentifier,
        code,
      }),
    },
  ).then((r) => r.json());

  console.log("Withdrawal initiated:", execution.data?.id);
  console.log("Status:", execution.data?.status);

  // Step 8: Listen for webhook to confirm completion
  return execution.data;
}

// Usage
executeFiatWithdrawal({
  walletId: "wallet-uuid",
  currency: "NGN",
  accountIdentifier: "0023103996",
  code: "445223",
});

Réponses d’erreur

{
  "message": "Institution not supported",
  "statusCode": 400
}
{
  "message": "Currency not supported",
  "statusCode": 400
}
{
  "message": "Asset not supported",
  "statusCode": 404
}
{
  "message": "Fiat withdrawal feature is not enabled for this business, please contact support via the live chat or email support for more information",
}
{
  "message": "Insufficient token balance for withdrawal",
  "statusCode": 400,
}
{
  "message": "Insufficient native balance for gas fees",
  "statusCode": 400
}
{
  "message": "Insufficient master balance for gas top-up",
  "statusCode": 400
}

Bonnes pratiques

Expérience utilisateur

  • Vérifiez les comptes en premier : Confirmez toujours le nom du compte avant d’afficher un devis
  • Affichez le coût complet : Présentez le taux de change, les frais réseau et le montant total
  • Exposez l’état de traitement : Utilisez les webhooks pour informer les utilisateurs en temps réel

Sécurité

  • Validez les entrées : Assurez-vous que la devise, l’institution et les identifiants de compte sont bien formés
  • Utilisez des références : Suivez les retraits avec une reference unique
  • Confirmez via webhooks : Considérez offramp.success comme source finale de vérité

Performance

  • Mettez en cache les listes d’institutions : Rafraîchissez-les périodiquement plutôt qu’à chaque requête
  • Réutilisez les métadonnées d’actifs : Mettez en cache actifs et devises pris en charge
  • Réessayez en cas d’erreurs transitoires : Utilisez un backoff exponentiel pour les réponses 5xx

Référence API

EndpointDescription
Obtenir les actifs pris en chargeListe les stablecoins pris en charge
Obtenir les institutionsListe les institutions par devise
Obtenir les taux de changeRécupère le taux de change pour un devis
Obtenir les devisesListe les devises fiat prises en charge
Vérifier le compte de l’institutionVérifie les informations du compte bancaire
Devis portefeuille principalObtient un devis depuis le portefeuille principal
Exécution portefeuille principalExécute un retrait depuis le portefeuille principal
Devis adresse enfantObtient un devis depuis une adresse enfant
Exécution adresse enfantExécute un retrait depuis une adresse enfant

Support