De 0 à l'Intégration

Ce guide vous accompagne à travers tout ce dont vous avez besoin pour accepter des dépôts de stablecoin avec Blockradar, de la configuration du compte à la gestion de votre premier événement webhook. Vous pouvez intégrer et lancer en production avec un seul développeur en moins de 2 heures.

Suivez et construisez au fil de votre lecture. À la fin, vous aurez un flux de paiement en stablecoin fonctionnel.

Ce que vous allez construire

À la fin de ce guide, vous aurez :

Un compte Blockradar et un portefeuille principal sur le testnet
Des adresses secondaires générées et liées à vos utilisateurs
Un gestionnaire de webhooks recevant des événements de dépôt en temps réel
Un modèle pour mettre à jour les soldes des utilisateurs après un dépôt

Étape 1 : Créez votre compte

Inscrivez-vous

Visitez dashboard.blockradar.co/signup et complétez le processus d’intégration. Cela prend moins de 60 secondes.

Vérifiez le Mode Live

Dans le coin supérieur droit du tableau de bord, vous verrez un bouton Mode Live. Il est désactivé par défaut, ce qui signifie que chaque action s’exécute sur le testnet, un environnement sécurisé sans fonds réels. Laissez-le désactivé pendant ce guide.

Étape 2 : Créez un portefeuille principal

Qu’est-ce qu’un portefeuille principal ?

Le portefeuille principal est la base de votre infrastructure stablecoin. Considérez-le comme votre trésorerie — il contrôle toutes les adresses secondaires que vous créez pour vos utilisateurs. Chaque portefeuille principal est lié à une blockchain spécifique : si vous voulez accepter des dépôts sur Ethereum, Base et BNB Chain, vous créerez un portefeuille principal distinct pour chacune.

Créez votre premier portefeuille

Accédez à la page Portefeuilles

Depuis le tableau de bord, cliquez sur Créer un Portefeuille Principal.

Sélectionnez un réseau

Choisissez Base Sepolia (Testnet) pour suivre ce guide. Vous pourrez créer des portefeuilles sur d’autres chaînes plus tard.

Nommez votre portefeuille

Donnez-lui un nom comme base-testnet et cliquez sur Créer.

Vous disposez maintenant d’un portefeuille principal. C’est là que toutes les adresses secondaires de vos utilisateurs seront générées.

Étape 3 : Générez des adresses pour vos utilisateurs

Que sont les adresses secondaires ?

Lorsqu’un utilisateur s’inscrit sur votre application et doit recevoir des stablecoins, il a besoin d’une adresse de portefeuille, comme un numéro de compte bancaire, mais sur la blockchain. Dans Blockradar, celles-ci sont appelées adresses secondaires. Elles sont générées sous votre portefeuille principal et héritent de sa configuration réseau.

Les adresses générées sur n’importe quelle chaîne compatible EVM (Base, Ethereum, BNB Chain, etc.) fonctionnent sur toutes les chaînes EVM. Une adresse couvre tous vos réseaux EVM.

Générez une adresse via l’API

Appelez cet endpoint lorsqu’un utilisateur s’inscrit sur votre plateforme :

curl -X POST https://api.blockradar.co/v1/wallets/{walletId}/addresses \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Wallet",
    "disableAutoSweep": false,
    "enableGaslessWithdraw": true,
    "metadata": {
      "user_id": 1234,
      "email": "[email protected]"
    }
  }'

const options = {
  method: "POST",
  headers: {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Customer Wallet",
    disableAutoSweep: false,
    enableGaslessWithdraw: true,
    metadata: { user_id: 1234, email: "[email protected]" },
  }),
};

fetch("https://api.blockradar.co/v1/wallets/{walletId}/addresses", options)
  .then((res) => res.json())
  .then(console.log);

Où trouver votre walletId et votre clé API

Accédez à votre portefeuille principal dans le tableau de bord
Faites défiler jusqu’à la section API Config
Cliquez sur l’icône d’affichage (vous devrez passer la 2FA)
Copiez votre API Key et votre Wallet ID

Le champ metadata

L’objet metadata est l’une des parties les plus importantes de cette requête. Tout ce que vous y attachez sera inclus dans chaque webhook que Blockradar envoie pour cette adresse : dépôts, retraits, balayages. C’est ainsi que votre backend identifie l’utilisateur auquel appartient une transaction.

{
  "user_id": 1234,
  "email": "[email protected]"
}

Bonne pratique : Incluez toujours un user_id dans les métadonnées pour mapper chaque dépôt directement à un utilisateur dans votre base de données, sans recherche supplémentaire.

Étape 4 : Configurez le balayage automatique et les transactions sans gas

Balayage automatique

Lorsque le balayage automatique est activé (disableAutoSweep: false), les fonds déposés sur une adresse secondaire sont automatiquement consolidés dans votre portefeuille principal. Cela simplifie la gestion de trésorerie : tous les fonds sont regroupés au même endroit, et vous suivez les soldes des utilisateurs dans votre propre base de données.

Pour que le balayage automatique fonctionne, votre portefeuille principal doit détenir des tokens natifs pour couvrir les frais de gas. Trouvez l’adresse de dépôt du portefeuille principal sur la page de présentation du portefeuille et envoyez-y des tokens testnet.

Faucets testnet pour les tokens de gas :

Réseau	Token	Faucet
Base Sepolia	ETH	alchemy.com/faucets/base-sepolia
Ethereum Sepolia	ETH	alchemy.com/faucets/ethereum-sepolia
BNB Testnet	BNB	bnbchain.org/en/testnet-faucet
Polygon Testnet	MATIC	faucet.polygon.technology
Tron Testnet	TRX	nileex.io
Solana Devnet	SOL	faucet.solana.com
Celo Alfajores	CELO	faucet.celo.org/alfajores
Avalanche Fuji	AVAX	core.app/tools/testnet-faucet

Faucets testnet pour les stablecoins :

Réseau	Token	Faucet
Base / Ethereum / Polygon / Solana	USDC	faucet.circle.com
BNB Testnet	USDT	bnbchain.org/en/testnet-faucet

Transactions sans gas

Lorsque enableGaslessWithdraw: true, vos utilisateurs peuvent envoyer des stablecoins depuis leur adresse sans détenir de tokens natifs. Votre portefeuille principal couvre le gas en leur nom. Cela supprime la principale friction de l’onboarding crypto.

Définissez des valeurs par défaut globales

Au lieu de configurer chaque adresse individuellement, vous pouvez définir des valeurs par défaut pour l’ensemble du portefeuille principal :

Accédez à votre portefeuille principal
Cliquez sur Configurations
Définissez disableAutoSweep et enableGaslessWithdraw

La configuration définie au niveau de l’adresse remplace celle du portefeuille principal. N’utilisez la configuration au niveau de l’adresse que lorsque vous avez besoin d’exceptions.

Étape 5 : Configurez les webhooks

Blockradar utilise des webhooks pour notifier votre backend lorsque des événements blockchain se produisent : dépôts, retraits, balayages, etc. Configurez-les avant de tester des transactions.

Enregistrez votre endpoint webhook

Accédez à votre portefeuille principal dans le tableau de bord
Cliquez sur Développeur → Webhook
Entrez l’URL de votre endpoint backend (doit être un endpoint POST)

Gérez les webhooks dans votre backend

app.post("/webhook-handler", (req, res) => {
  const event = req.body;
  console.log("Webhook received:", event);
  // Handle event based on event type
  res.sendStatus(200);
});

Événements webhook courants

Événement	Description
`deposit.success`	Un dépôt a été reçu sur une adresse secondaire
`deposit.swept.success`	Les fonds ont été balayés d’une adresse secondaire vers le portefeuille principal
`withdraw.success`	Un retrait a été envoyé avec succès
`swap.success`	Un échange a été exécuté avec succès

Référence complète des webhooks

Consultez tous les types d’événements, les schémas de payload, la logique de nouvelles tentatives et la vérification HMAC.

Étape 6 : Gérez un événement de dépôt

Lorsqu’un utilisateur envoie de l’USDC à son adresse, Blockradar déclenche un événement deposit.success vers votre endpoint webhook.

Exemple de payload

{
  "event": "deposit.success",
  "data": {
    "amountPaid": "10.0",
    "currency": "USD",
    "senderAddress": "0xabc...",
    "recipientAddress": "0xdef...",
    "metadata": {
      "user_id": 1234
    }
  }
}

Comment le traiter

Identifiez l'utilisateur

Extrayez metadata.user_id du payload pour mapper le dépôt à un utilisateur dans votre base de données.

Lisez le montant

Utilisez data.amountPaid pour déterminer combien a été déposé. Appliquez les éventuels frais de dépôt en les soustrayant de cette valeur avant l’enregistrement.

Mettez à jour le solde

Créditez le solde de l’utilisateur dans votre base de données. Si le balayage automatique est activé, les fonds se trouvent déjà dans votre portefeuille principal.

Ce que vous avez construit

Vous disposez maintenant d’un flux complet de paiement en stablecoin :

Un portefeuille principal sur le testnet
Des adresses secondaires liées aux utilisateurs via les métadonnées
Un balayage automatique consolidant les fonds dans votre trésorerie
Des transactions sans gas réduisant les frictions pour vos utilisateurs
Un gestionnaire de webhooks mettant à jour les soldes en temps réel

Où aller ensuite

Envoyer des paiements

Envoyez des stablecoins à vos utilisateurs ou partenaires de manière programmatique.

Ajouter la vérification AML

Vérifiez les adresses avant d’envoyer ou de recevoir des fonds.

Explorer les échanges

Permettez aux utilisateurs d’échanger entre stablecoins avec un seul appel API.

Lancer en production

Activez le Mode Live dans le tableau de bord et commencez à accepter de vrais fonds.

Démarrage

Portefeuilles

Encaissements

Paiements

Convertir et Gérer

Conformité et Outils

De 0 à l'Intégration

Ce que vous allez construire

Étape 1 : Créez votre compte

Étape 2 : Créez un portefeuille principal

Qu’est-ce qu’un portefeuille principal ?

Créez votre premier portefeuille

Étape 3 : Générez des adresses pour vos utilisateurs

Que sont les adresses secondaires ?

Générez une adresse via l’API

Où trouver votre walletId et votre clé API

Le champ metadata

Étape 4 : Configurez le balayage automatique et les transactions sans gas

Balayage automatique

Transactions sans gas

Définissez des valeurs par défaut globales

Étape 5 : Configurez les webhooks

Enregistrez votre endpoint webhook

Gérez les webhooks dans votre backend

Événements webhook courants

Référence complète des webhooks

Étape 6 : Gérez un événement de dépôt

Exemple de payload

Comment le traiter

Ce que vous avez construit

Où aller ensuite

Envoyer des paiements

Ajouter la vérification AML

Explorer les échanges

Lancer en production

​Ce que vous allez construire

​Étape 1 : Créez votre compte

​Étape 2 : Créez un portefeuille principal

​Qu’est-ce qu’un portefeuille principal ?

​Créez votre premier portefeuille

​Étape 3 : Générez des adresses pour vos utilisateurs

​Que sont les adresses secondaires ?

​Générez une adresse via l’API

​Où trouver votre walletId et votre clé API

​Le champ metadata

​Étape 4 : Configurez le balayage automatique et les transactions sans gas

​Balayage automatique

​Transactions sans gas

​Définissez des valeurs par défaut globales

​Étape 5 : Configurez les webhooks

​Enregistrez votre endpoint webhook

​Gérez les webhooks dans votre backend

​Événements webhook courants

Référence complète des webhooks

​Étape 6 : Gérez un événement de dépôt

​Exemple de payload

​Comment le traiter

​Ce que vous avez construit

​Où aller ensuite

Envoyer des paiements

Ajouter la vérification AML

Explorer les échanges

Lancer en production

Ce que vous allez construire

Étape 1 : Créez votre compte

Étape 2 : Créez un portefeuille principal

Qu’est-ce qu’un portefeuille principal ?

Créez votre premier portefeuille

Étape 3 : Générez des adresses pour vos utilisateurs

Que sont les adresses secondaires ?

Générez une adresse via l’API

Où trouver votre walletId et votre clé API

Le champ metadata

Étape 4 : Configurez le balayage automatique et les transactions sans gas

Balayage automatique

Transactions sans gas

Définissez des valeurs par défaut globales

Étape 5 : Configurez les webhooks

Enregistrez votre endpoint webhook

Gérez les webhooks dans votre backend

Événements webhook courants

Étape 6 : Gérez un événement de dépôt

Exemple de payload

Comment le traiter

Ce que vous avez construit

Où aller ensuite