Passer au contenu principal
En bref
Blockradar vous permet d’accepter des dépôts de stablecoins en générant des adresses blockchain dédiées pour chaque client. Les dépôts sont détectés automatiquement, déclenchent des notifications par webhook, et peuvent être consolidés (sweep) vers votre portefeuille principal — vous donnant un contrôle total sur la circulation des fonds dans votre plateforme.

Prérequis

1

Clé API

Obtenez votre clé API depuis le Tableau de bord Blockradar. Naviguez vers Developers pour en générer une.
2

Portefeuille Principal

Créez un portefeuille via le tableau de bord ou l’API. Vous aurez besoin du walletId pour toutes les opérations de dépôt.
3

Actifs Activés

Activez les stablecoins que vous souhaitez accepter sur votre portefeuille. Votre portefeuille ne détecte que les dépôts d’actifs que vous avez explicitement ajoutés — voir Gestion des Actifs.
4

URL de Webhook

Configurez un endpoint de webhook dans votre tableau de bord sous Developers → Webhooks pour recevoir les notifications de dépôts en temps réel.

Comment Ça Fonctionne

Le flux de dépôt de Blockradar repose sur un principe simple : chaque client obtient sa propre adresse, et chaque dépôt est suivi automatiquement.

Générer des Adresses

Créez une adresse blockchain unique pour chaque client ou session de paiement. Les dépôts vers cette adresse sont attribués automatiquement au client.

Détecter les Dépôts

Blockradar surveille toutes les adresses générées et déclenche un webhook dès qu’un dépôt arrive. Aucun polling requis.

Auto-Sweep

Les dépôts sont automatiquement consolidés vers votre portefeuille principal, gardant les adresses clients propres et votre trésorerie centralisée.

Consulter les Soldes

Interrogez les soldes au niveau du portefeuille ou de l’adresse, pour un actif unique ou tous les actifs à la fois, avec la conversion en USD incluse.

Contrôle Granulaire par Conception

La plupart des infrastructures blockchain traitent les portefeuilles comme des conteneurs plats et uniformes. Blockradar est différent. Chaque couche de la hiérarchie du portefeuille — portefeuille principal, adresse secondaire et actif individuel — est configurable indépendamment, afin que les fintechs puissent adapter l’expérience de dépôt à leurs besoins produit exacts. Cela signifie que vous pouvez :
  • Accepter différents stablecoins par portefeuille — activez USDC sur un portefeuille et USDT sur un autre, ou les deux sur le même portefeuille. Vous décidez de ce que chaque portefeuille surveille.
  • Configurer le comportement de sweep par adresse — auto-sweep des dépôts vers le portefeuille principal par défaut, mais désactivez-le pour des adresses spécifiques où vous souhaitez que les fonds restent en place.
  • Attacher des métadonnées à chaque adresse — taguez les adresses avec vos propres IDs utilisateurs, tokens de session ou références internes afin que les dépôts se mappent directement à votre système.
  • Activer ou désactiver les adresses à la demande — mettez en pause une adresse sans la supprimer, puis réactivez-la au besoin.
Cette granularité est essentielle lorsque vous construisez des produits comme des portefeuilles multi-devises, des escrows pour marketplace ou des flux de dépôt par utilisateur, où un modèle de portefeuille rigide forcerait des contournements que Blockradar gère nativement.

Étape 1 : Activer les Actifs sur Votre Portefeuille

Avant de pouvoir accepter des dépôts, votre portefeuille doit savoir quels stablecoins surveiller. Récupérez les actifs disponibles avec le endpoint Get Assets, puis ajoutez ceux que vous voulez.
curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/assets \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "assetId": "global-asset-id-for-usdc"
  }'
Une fois ajouté, Blockradar commence immédiatement à surveiller votre portefeuille et toutes ses adresses pour les dépôts de ce token.
Utilisez Get Wallet Assets pour récupérer les IDs d’actifs spécifiques au portefeuille. Ce sont les IDs que vous utiliserez dans les requêtes de solde et autres appels API — ils sont différents des IDs d’actifs globaux.

Étape 2 : Générer une Adresse Client

Créez une adresse dédiée pour chaque client ou session de dépôt. Chaque dépôt vers cette adresse est automatiquement attribué au client.
curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/addresses \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "name": "Customer 12345",
    "metadata": {
      "userId": "user_12345",
      "plan": "premium"
    }
  }'

Réponse

{
  "statusCode": 201,
  "message": "Address generated successfully",
  "data": {
    "id": "address-uuid",
    "address": "0xe1037B45b48390285e5067424053fa35c478296b",
    "name": "Customer 12345",
    "type": "INTERNAL",
    "isActive": true,
    "metadata": {
      "userId": "user_12345",
      "plan": "premium"
    },
    "configurations": {
      "autoSweep": true,
      "gaslessWithdraw": false
    },
    "blockchain": {
      "name": "base",
      "symbol": "ETH",
      "network": "mainnet"
    },
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Paramètres d’Adresse

ParamètreTypeRequisDescription
namestringNonLibellé lisible pour l’adresse
metadataobjectNonPaires clé-valeur personnalisées mappées à votre système interne
disableAutoSweepbooleanNontrue pour garder les dépôts sur l’adresse au lieu de les consolider vers le portefeuille principal
enableGaslessWithdrawbooleanNonActive les retraits sans gas depuis cette adresse
Partagez l’address générée avec votre client. Lorsqu’il envoie des stablecoins, Blockradar détecte le dépôt et déclenche un webhook.

Étape 3 : Écouter les Dépôts

Configurez votre endpoint de webhook pour recevoir des notifications en temps réel lorsque les dépôts arrivent.

Événements de Webhook

ÉvénementDescription
deposit.successUn dépôt a été confirmé on-chain sur une adresse client
deposit.swept.successLe dépôt a été auto-consolidé vers le portefeuille principal

Payload de Webhook

{
  "event": "deposit.success",
  "data": {
    "id": "tx-uuid",
    "hash": "0xabc123...",
    "type": "DEPOSIT",
    "status": "SUCCESS",
    "amount": "100",
    "senderAddress": "0xCustomerExternalWallet...",
    "recipientAddress": "0xe1037B45b48390285e5067424053fa35c478296b",
    "asset": {
      "id": "asset-uuid",
      "name": "USD Coin",
      "symbol": "USDC",
      "decimals": 6
    },
    "wallet": {
      "id": "wallet-uuid",
      "name": "Deposits Wallet"
    },
    "blockchain": {
      "name": "base",
      "network": "mainnet"
    },
    "metadata": {
      "userId": "user_12345",
      "plan": "premium"
    },
    "createdAt": "2024-01-15T10:30:00Z"
  }
}
Les metadata que vous avez attachées lors de la génération de l’adresse sont incluses dans chaque webhook pour cette adresse, vous permettant de mapper les dépôts à vos utilisateurs sans requête supplémentaire.

Vérifier les Soldes

Interrogez les soldes à n’importe quel niveau de la hiérarchie — portefeuille principal ou adresse individuelle, actif unique ou tous les actifs.

Solde d’un Actif Unique (Portefeuille)

curl --request GET \
  --url 'https://api.blockradar.co/v1/wallets/{walletId}/balance?assetId={assetId}' \
  --header 'x-api-key: <api-key>'

Soldes de Tous les Actifs (Adresse)

curl --request GET \
  --url https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/balances \
  --header 'x-api-key: <api-key>'

Endpoints de Solde

PortéeActif UniqueTous les Actifs
Portefeuille PrincipalGET /v1/wallets/{walletId}/balance?assetId={assetId}GET /v1/wallets/{walletId}/balances
Adresse SecondaireGET /v1/wallets/{walletId}/addresses/{addressId}/balance?assetId={assetId}GET /v1/wallets/{walletId}/addresses/{addressId}/balances

Gestion des Adresses

Lister Toutes les Adresses

Récupérez toutes les adresses d’un portefeuille, avec des analytics sur les comptes actifs vs. inactifs.
GET /v1/wallets/{walletId}/addresses

Obtenir une Adresse Spécifique

Récupérez les détails complets d’une seule adresse, y compris sa configuration et ses métadonnées.
GET /v1/wallets/{walletId}/addresses/{addressId}

Mettre à Jour une Adresse

Modifiez le nom, les métadonnées, le statut actif ou la configuration de sweep d’une adresse.
curl --request PATCH \
  --url https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "name": "Customer 12345 — upgraded",
    "metadata": {
      "userId": "user_12345",
      "plan": "enterprise"
    },
    "disableAutoSweep": true
  }'

Désactiver une Adresse

Définissez isActive sur false pour cesser de surveiller une adresse. L’adresse et son historique sont préservés — vous pouvez la réactiver à tout moment.
await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/addresses/${addressId}`,
  {
    method: 'PATCH',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey
    },
    body: JSON.stringify({ isActive: false })
  }
);

Auto-Sweep

Par défaut, les dépôts vers les adresses secondaires sont automatiquement consolidés vers le portefeuille principal. Cela garde les adresses clients propres et centralise les fonds pour la gestion de trésorerie ou les paiements sortants. Vous pouvez contrôler ce comportement au niveau de l’adresse :
RéglageComportement
Auto-sweep activé (défaut)Les dépôts sont automatiquement déplacés vers le portefeuille principal après confirmation
Auto-sweep désactivéLes dépôts restent sur l’adresse secondaire jusqu’à une consolidation manuelle ou un retrait

Sweep Manuel

Si l’auto-sweep est désactivé, vous pouvez déclencher un sweep à la demande :
POST /v1/wallets/{walletId}/sweep/assets
{
  "forceSweep": true
}

Deposit Finder

Si un dépôt n’apparaît pas (ex. webhook manqué), utilisez le deposit finder pour rescanner la blockchain :
POST /v1/wallets/{walletId}/rescan/blocks
{
  "transactionHash": "0xabc123..."
}

Exemple de Flux Complet

Voici une implémentation complète : activer un actif, générer une adresse client et gérer le webhook de dépôt.
async function setupCustomerDeposit(walletId, userId) {
  const apiKey = process.env.BLOCKRADAR_API_KEY;
  const baseUrl = 'https://api.blockradar.co/v1';
  const headers = {
    'Content-Type': 'application/json',
    'x-api-key': apiKey
  };

  // Étape 1 : Générer une adresse dédiée pour le client
  const addressRes = await fetch(
    `${baseUrl}/wallets/${walletId}/addresses`,
    {
      method: 'POST',
      headers,
      body: JSON.stringify({
        name: `User ${userId}`,
        metadata: { userId, createdAt: new Date().toISOString() }
      })
    }
  ).then(r => r.json());

  const depositAddress = addressRes.data.address;
  console.log('Share this address with customer:', depositAddress);

  return depositAddress;
}

// Handler de webhook (exemple Express.js)
app.post('/webhooks/blockradar', (req, res) => {
  const { event, data } = req.body;

  if (event === 'deposit.success') {
    const userId = data.metadata?.userId;
    const amount = data.amount;
    const symbol = data.asset.symbol;

    console.log(`Deposit received: ${amount} ${symbol} from user ${userId}`);

    // Créditer le compte utilisateur dans votre système
    creditUserAccount(userId, amount, symbol);
  }

  if (event === 'deposit.swept.success') {
    console.log(`Deposit swept to master wallet: ${data.amount} ${data.asset.symbol}`);
  }

  res.sendStatus(200);
});

Bonnes Pratiques

Gestion des Adresses

  • Une adresse par client — générez une adresse unique pour chaque utilisateur ou session de paiement pour simplifier l’attribution
  • Utilisez les métadonnées — attachez vos IDs utilisateurs internes et références afin que les payloads de webhook se mappent directement à votre système
  • Désactivez, ne supprimez pas — définissez isActive: false sur les adresses que vous n’utilisez plus, en préservant l’historique

Sécurité

  • Validez les webhooks — vérifiez que les requêtes webhook entrantes proviennent de Blockradar
  • Activez le screening AML — Blockradar peut filtrer automatiquement les adresses de dépôt (voir Vérification AML)
  • Surveillez les logs de webhook — utilisez GET /v1/wallets/{walletId}/webhooks pour déboguer les livraisons échouées

Opérations

  • N’activez que les actifs dont vous avez besoin — une liste d’actifs focalisée réduit le bruit des webhooks et garde les requêtes de solde rapides
  • Testez d’abord sur testnet — générez des adresses, simulez des dépôts et vérifiez votre handler de webhook avant de passer en mainnet
  • Utilisez le deposit finder — si un client signale un dépôt que vous n’avez pas reçu, rescannez la blockchain avant de dépanner davantage

Référence API

Portefeuille

EndpointDescription
Get WalletRécupère les détails et la configuration du portefeuille
Get BalanceVérifie le solde d’un actif unique sur le portefeuille principal
Get BalancesVérifie les soldes de tous les actifs sur le portefeuille principal
Trigger SweepConsolide manuellement les dépôts vers le portefeuille principal
Deposit FinderRescanne la blockchain pour les dépôts manquants
Webhook LogsAffiche l’historique de livraison des webhooks

Adresses

EndpointDescription
Generate AddressCrée une nouvelle adresse de dépôt client
Get AddressesListe toutes les adresses d’un portefeuille
Get AddressRécupère les détails d’une adresse spécifique
Update AddressMet à jour le nom, les métadonnées ou la configuration d’une adresse
Get BalanceVérifie le solde d’un actif unique sur une adresse
Get BalancesVérifie les soldes de tous les actifs sur une adresse
Get TransactionsAffiche l’historique des dépôts pour une adresse

Gestion des Actifs

EndpointDescription
Get Wallet AssetsListe les actifs activés sur un portefeuille
Add AssetActive un nouveau stablecoin pour les dépôts
Remove AssetArrête la surveillance d’un stablecoin
Update AssetMet à jour la configuration au niveau de l’actif