API de surveillance d'adresses : principe et mise en œuvre
Fonctionnement d'une API de surveillance d'adresses crypto : webhooks pour dépôts et retraits, confirmations, relances et sécurité des notifications.
Relu par Maurice Sobiera

Une API de surveillance d’adresses observe des adresses blockchain et prévient votre application d’un événement : dépôt, sortie de fonds, mouvement de token ou confirmation. Vous enregistrez une adresse et une URL de rappel. Le service envoie un webhook avec les détails de la transaction, sans interrogation de nœuds ni décodage de logs.
« Surveillance d’adresses » désigne deux tâches différentes. La première est opérationnelle : savoir quand de l’argent arrive à une adresse que votre application contrôle, ou en sort, afin de créditer un client ou de libérer une commande. La seconde relève de la conformité : analyser le comportement des adresses dans le temps pour repérer une activité risquée. Cet article traite la première, dont la plupart des équipes produit ont besoin, et montre où commence la seconde.
TL;DR
- Une API de surveillance d’adresses suit les adresses blockchain choisies et envoie les événements à votre serveur par webhook. Vous n’avez donc ni à faire tourner de nœuds, ni à interroger la chaîne.
- Les événements doivent arriver décodés : expéditeur, destinataire, token, montant et statut, et non des logs hexadécimaux bruts.
- Vérifiez la signature de chaque webhook, dédoublonnez par identifiant de transaction, et ne créditez les fonds qu’au niveau de confirmation choisi.
- Les webhooks Chaingateway ne sont pas relancés automatiquement. Réconciliez avec l’API pour retrouver les événements manqués.
- La surveillance opérationnelle (paiements) diffère de la surveillance de conformité (schémas de risque dans le temps). Beaucoup d’équipes ont besoin des deux, avec des outils différents.
- Chaingateway propose portefeuilles, transferts, données de transaction décodées et webhooks signés pour Ethereum, Bitcoin, Tron, Polygon, BNB Smart Chain et Arbitrum. Solana est pris en charge, mais n’a pas de webhooks.
Table des matières
- Ce que fait réellement une API de surveillance d’adresses
- Pourquoi ne pas simplement faire tourner ses propres nœuds et interroger la chaîne ?
- Comment fonctionne la surveillance d’adresses par webhook ?
- Quels réseaux et quels types d’adresses doit-elle prendre en charge ?
- Confirmations, délais et réorganisations : quand un paiement est-il réel ?
- Gérer les relances et les notifications en double
- Sécurité, authentification et limites de débit
- Que chercher dans une API de surveillance d’adresses ?
- Faut-il construire sa propre surveillance ou utiliser une API ?
- Essayer sur vos propres adresses
- Liste de contrôle minimale pour l’implémentation
- FAQ
- Sources
Ce que fait réellement une API de surveillance d’adresses
Une blockchain est un registre public, mais elle ne vous appelle pas lorsqu’un événement se produit. Aucun mécanisme du protocole ne transmettra un message à votre backend parce que l’adresse 0xABC... a reçu 250 USDT. Quelqu’un doit lire les nouveaux blocs, les filtrer pour les adresses qui vous intéressent, décoder le résultat en données exploitables et vous prévenir. Une API de surveillance d’adresses remplit ce rôle, sous forme de service.
En pratique, l’API fait cinq choses :
- Elle enregistre des adresses. Vous ajoutez les adresses à surveiller, généralement celles que vous avez générées pour des clients, des factures ou des portefeuilles internes.
- Elle lit la chaîne. Le fournisseur fait tourner des nœuds ou des indexeurs pour chaque réseau et parcourt chaque nouveau bloc.
- Elle repère l’activité. Elle trouve les transferts de la monnaie native et les transferts de tokens qui touchent vos adresses surveillées.
- Elle décode les données. Les transactions brutes et les logs d’événements deviennent des champs lisibles : sens, symbole du token, montant avec les bonnes décimales, frais, bloc, statut.
- Elle livre les événements. Elle les envoie à votre endpoint, généralement sous forme de webhook HTTPS en POST, et vous permet aussi d’interroger les mêmes données à la demande.
Ce qu’elle détecte dépend de la chaîne. Sur Bitcoin, ce sont les sorties payées à une adresse. Sur Ethereum et les autres réseaux EVM, ce sont les transferts natifs et les événements de tokens, comme les logs Transfer ERC-20. Sur Tron, elle couvre TRX et les tokens TRC-20. Notre page API d’adresses TRC20 montre comment la génération et la surveillance d’adresses s’articulent sur ce réseau.
Surveillance opérationnelle et surveillance de conformité
L’expression existe aussi dans l’univers de la conformité, et il ne faut pas confondre les deux. Les fournisseurs orientés conformité décrivent la surveillance des transactions comme une analyse continue de l’activité blockchain dans le temps. Ils recherchent des schémas tels que le fractionnement (structuring), le blanchiment par couches (layering), une vitesse de mouvement inhabituelle, l’usage de mixeurs, le contournement de sanctions ou l’activité de portefeuilles dormants. Le risque apparaît dans le comportement sur de nombreuses transactions, et des humains examinent les alertes.
Une API de surveillance opérationnelle répond à une question plus simple : « Le paiement que j’attends est-il arrivé, et est-il final ? » Si vous exploitez une activité réglementée, vous aurez probablement besoin des deux couches. La couche opérationnelle alimente votre grand livre et l’expérience client. La couche de conformité alimente votre équipe risques. Lorsqu’une alerte demande un examen plus poussé, comme le traçage de fonds sur plusieurs sauts, ce travail revient à des spécialistes, et non à un webhook de paiement.

Pourquoi ne pas simplement faire tourner ses propres nœuds et interroger la chaîne ?
La question est légitime, et pour quelques équipes la réponse est précisément de le faire. Voici ce que vous prenez en charge dans ce cas.
- Exploitation des nœuds. Chaque chaîne demande son propre nœud ou un point d’accès hébergé, avec les mises à jour, la croissance du stockage et la disponibilité à gérer. Chaque réseau supplémentaire implique une nouvelle installation.
- Logique propre à chaque chaîne. Le modèle UTXO de Bitcoin, les logs d’Ethereum, le modèle de ressources de Tron et le modèle de comptes de Solana demandent chacun leur propre code d’analyse.
- Décodage. Les montants de tokens arrivent sous forme d’entiers qui nécessitent les bonnes décimales. Les événements de contrats nécessitent des ABI. Les transferts internes et les transactions groupées sont faciles à manquer.
- Gestion des réorganisations. Les blocs récents peuvent être remplacés. Votre scanner doit le détecter et se corriger lui-même.
- Livraison. Une fois un événement détecté, il vous faut encore une file d’attente, des relances et un schéma de signature pour le remettre en sécurité à vos propres services.
Une API de surveillance regroupe l’essentiel de cela dans une seule intégration. Le compromis est la dépendance envers un fournisseur : jugez-le donc sur sa fiabilité, la qualité de ses données et la clarté avec laquelle il vous remet les événements. Pour un panorama plus large des alternatives, voir notre comparaison des six types d’API blockchain et quand utiliser chacun.
Comment fonctionne la surveillance d’adresses par webhook ?
Le flux type comporte quatre étapes, qu’on le construise soi-même ou qu’on l’achète.
1. Créer ou enregistrer l’adresse
Pour les paiements, le modèle le plus propre consiste à utiliser une adresse par client, par facture ou par commande. Lorsqu’un paiement arrive sur une adresse unique, vous savez qui a payé sans demander de mémo ni de référence. Avec Chaingateway, vous créez des portefeuilles via l’API et utilisez directement les adresses obtenues. Si des clients fournissent leurs propres adresses pour les retraits, validez-les d’abord. Notre validateur d’adresses crypto, gratuit, couvre les formats Tron, Ethereum et BSC, et sert de référence pendant la construction de vos propres contrôles.
2. S’abonner aux événements
Vous indiquez à l’API les adresses et les types d’événements qui comptent, ainsi que l’endroit où les envoyer : votre endpoint HTTPS. Les abonnements peuvent être aussi étroits qu’une adresse et un token, ou aussi larges que toutes les adresses de votre compte. Le détail de ce modèle figure sur la page des webhooks blockchain et notifications d’événements.
3. Recevoir une charge utile décodée
Une charge utile exploitable vous indique, sans recherche supplémentaire, l’expéditeur, le destinataire, l’actif, le montant, le bloc et le hash de la transaction. Un webhook Chaingateway pour un transfert TRC-20 ressemble à ceci (guide des webhooks) :
{ "id": "9d18457f-c71c-4be4-ae7c-ce04e48359ed", "webhook_id": "9ced86a9-b8d9-4bc2-bbd8-5ffe5b456bc8", "from": "TTd9qHyjqiUkfTxe3gotbuTMpjU8LEbpkN", "to": "DScWVXehzWdV2YS8fA2ryNsiHpKiLgAxM", "blocknumber": "65542464", "datetime": "2024-09-25 14:48:27", "tokenid": null, "type": "TRC20", "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "txid": "18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988", "amount": 108935}L’id identifie la notification, et txid identifie la transaction. C’est la différence entre des données décodées et des données brutes de la chaîne : avec des données brutes, vous écrivez l’analyseur ; avec des données décodées, vous lisez un champ. La charge utile ne contient pas de compteur de confirmations : votre propre code décide donc à partir de quand une transaction compte comme finale.
4. Accuser réception, vérifier et agir
Votre serveur vérifie la signature, enregistre l’événement, renvoie rapidement une réponse 2xx, puis traite la logique métier de manière asynchrone. Tout le reste, comme créditer un compte ou expédier une commande, dépend des règles de confirmation que vous avez définies.

Quels réseaux et quels types d’adresses doit-elle prendre en charge ?
Avant de vous engager, listez ce que votre produit va toucher dans l’année à venir, pas seulement aujourd’hui. Un paiement qui démarre en USDT sur un seul réseau est souvent réclamé sur un autre quelques mois plus tard.
Vérifiez la couverture :
- Monnaies natives et tokens. Bitcoin, ETH, TRX, SOL, actifs du réseau MATIC et de la chaîne BNB, ainsi que des standards de tokens comme ERC-20, BEP-20 et TRC-20.
- NFT. Si vous émettez ou acceptez des objets de collection ou des billets, vous avez aussi besoin d’événements de transfert de type ERC-721.
- Formats d’adresse. Bitcoin possède plusieurs formats. Les chaînes EVM partagent un même format entre réseaux, ce qui peut provoquer des erreurs lorsqu’un client envoie sur le mauvais réseau. Votre application doit indiquer le réseau attendu à côté de chaque adresse de dépôt.
- Activité sortante. De nombreux outils ne détectent que les dépôts. Si vous envoyez des paiements, vous voulez la même vue décodée des transactions sortantes et de leur statut.
Chaingateway couvre Ethereum, Bitcoin, Tron, Solana, Polygon, BNB Smart Chain et Arbitrum derrière une seule API blockchain, y compris les principaux standards de tokens et les transferts de NFT. Des webhooks existent pour toutes les chaînes sauf Solana. Une intégration Solana doit interroger les soldes ou les transactions de ses adresses.
Confirmations, délais et réorganisations : quand un paiement est-il réel ?
La première notification n’est pas le dernier mot. Une transaction peut être vue dans le mempool, incluse dans un bloc, puis atteindre plus tard un niveau de finalité que vous jugez sûr. Les chaînes diffèrent fortement sur ce point : les temps de bloc, les conventions de confirmation et les modèles de finalité ne sont pas les mêmes sur Bitcoin, Ethereum, Tron ou Solana. Vos seuils doivent donc être définis par réseau et par montant.
| Réseau | Ce que dit la documentation | Source |
|---|---|---|
| Bitcoin | Des blocs concurrents peuvent apparaître à la même hauteur, et les nœuds abandonnent les blocs obsolètes de la branche la plus courte. Il n’existe pas de point de finalité fixe : vous choisissez une profondeur de confirmation. | Guide développeur Bitcoin |
| Ethereum | Un bloc prend environ 15 minutes pour être finalisé. | ethereum.org |
| Tron | Un bloc devient irréversible après confirmation par les super-représentants, soit environ 19 blocs. | Hub développeur TRON |
Une politique pratique ressemble à ceci :
| Étape | Ce que cela signifie | Ce que votre application doit faire |
|---|---|---|
| Détectée | La transaction est vue mais n’est pas encore dans un bloc | Afficher « paiement en attente » ; ne pas libérer la commande |
| Incluse | Elle est dans un bloc, avec peu de confirmations | Créditer un solde en attente pour de petits montants, si votre risque le permet |
| Confirmée | Elle a atteint la profondeur de confirmation choisie | Créditer le compte, libérer la commande |
| Échouée ou abandonnée | Elle a été remplacée, annulée ou n’a jamais été minée | Annuler l’état en attente et en informer le client |
Deux règles vous évitent des ennuis. D’abord, adaptez l’exigence de confirmation à la valeur en jeu : un petit paiement d’abonnement peut supporter un seuil plus bas qu’un gros retrait. Ensuite, rendez explicite la machine d’états dans votre base de données. « En attente », « confirmé » et « échoué » doivent être des états stockés, et non déduits.
Attendez-vous aussi à ce que les événements arrivent en retard ou dans le désordre. Une notification de confirmation peut vous parvenir avant qu’un gestionnaire lent ait fini de traiter la notification de détection. Utilisez le hash de transaction et le statut comme source de vérité, et non l’ordre d’arrivée.
Gérer les relances et les notifications en double
Chaingateway ne relance pas automatiquement les webhooks. Si votre serveur dépasse le délai ou renvoie une erreur, la notification est enregistrée comme échouée. Vous listez les notifications échouées par chaîne, par exemple avec GET /api/v2/tron/webhooks/notifications/failed, puis vous les renvoyez avec POST /api/v2/tron/webhooks/notifications/{id}/retry. Tant que vous ne le faites pas, votre système ne connaît pas cet événement.
Des doublons peuvent tout de même survenir, par exemple lorsque vous renvoyez une notification que votre serveur avait déjà traitée. Prévoyez les deux cas dès le premier jour. D’autres fournisseurs peuvent relancer eux-mêmes, si bien que la même conception de gestionnaire fonctionne avec tous les fournisseurs.
- Rendez les gestionnaires idempotents. Stockez une clé unique par événement, par exemple le hash de transaction associé à l’index du log ou à l’identifiant de livraison, avec une contrainte d’unicité en base. Si la clé existe déjà, renvoyez un succès et ne faites rien d’autre.
- Répondez vite. Écrivez l’événement brut dans une file ou une table, renvoyez un statut 2xx, puis traitez-le. Les gestionnaires lents provoquent des dépassements de délai, et chaque dépassement devient une notification échouée.
- Réconciliez. Des webhooks peuvent être manqués pendant votre propre indisponibilité. Lancez une tâche périodique qui liste les notifications échouées et les notifications récentes (
GET /api/v2/<chain>/webhooks/notifications), puis les compare à vos enregistrements. Une notification perdue devient ainsi un correctif différé, et non un incident. - Journalisez tout. Conservez la charge utile brute, l’en-tête de signature et le résultat de votre traitement. Lorsqu’un client affirme avoir payé, vous voulez la preuve en une minute, et non en une heure.
- Alertez sur le silence. Si une adresse qui reçoit normalement du trafic ne produit aucun événement pendant une période inhabituelle, vérifiez le pipeline.
Sécurité, authentification et limites de débit
Un endpoint qui crédite de l’argent sur demande est une cible. Traitez-le comme telle.
Vérifier chaque webhook
Quiconque trouve votre URL peut envoyer un faux message « paiement reçu ». Exigez donc une signature. Une fois un secret personnel défini dans votre profil, Chaingateway ajoute un en-tête X-Signature à chaque webhook. Cet en-tête est un HMAC-SHA256 encodé en Base64 de l’identifiant de transaction, calculé avec votre secret personnel. Votre serveur le recalcule et rejette tout ce qui ne correspond pas (guide de signature).
Comparez les valeurs avec une fonction à temps constant, comme hmac.compare_digest en Python. HMAC lui-même est défini dans la RFC 2104.
Protéger vos clés API
Conservez les clés dans un gestionnaire de secrets ou des variables d’environnement, jamais dans du code côté client ni dans des dépôts. Utilisez des clés distinctes par environnement, et renouvelez-les selon un calendrier ainsi qu’après tout changement de personnel. Nous avons rassemblé d’autres bonnes pratiques de ce type dans nos six conseils de sécurité pour utiliser une API blockchain.
Durcir l’endpoint
- Servez-le uniquement en HTTPS.
- Utilisez un chemin difficile à deviner et, lorsque votre fournisseur publie ses plages d’adresses IP sources, n’autorisez que celles-ci.
- Rejetez les corps de requête trop volumineux et les types de contenu inattendus.
- Ne faites jamais confiance à un montant ou à une adresse provenant d’un webhook que vous n’avez pas rapprochés de vos propres enregistrements. L’adresse doit être une adresse que vous avez émise, et le montant doit être cohérent avec la commande.
Anticiper les limites de débit
Lorsque vous interrogez l’API pour la réconciliation ou des recherches d’adresses par lot, vous rencontrerez des limites de requêtes chez tout fournisseur. Mettez en cache ce qui ne change pas, regroupez les requêtes lorsque l’API le permet, appliquez un backoff exponentiel en cas de réponses de limitation, et répartissez les tâches planifiées au lieu de les lancer toutes à l’heure pile. Connaissez les limites de votre forfait avant le lancement, et non pendant votre premier pic de trafic.
Que chercher dans une API de surveillance d’adresses ?
Utilisez cette liste de contrôle pour comparer des fournisseurs ou décider si vous construisez vous-même.
| Critère | Pourquoi c’est important | Question à poser |
|---|---|---|
| Couverture des chaînes | Évite une seconde intégration lorsque vous vous étendez | Toutes les chaînes et tous les standards de tokens dont j’ai besoin sont-ils dans une seule API ? |
| Données décodées | Réduit le code d’analyse et les bugs | Les événements incluent-ils le token, le montant, le sens et le statut ? |
| Garanties de livraison | Détermine votre travail d’idempotence et de réconciliation | Les livraisons échouées sont-elles relancées automatiquement ou sur demande, et existe-t-il un identifiant de notification ? |
| Signatures | Empêche les paiements usurpés | Chaque webhook est-il signé, et comment le vérifier ? |
| Aide sur les frais et le gas | Les transferts sortants échouent sans les bons frais | L’API estime-t-elle automatiquement le gas et les frais ? |
| Outils de portefeuille | Évite d’assembler plusieurs services | Puis-je créer des portefeuilles et envoyer des transferts depuis la même API ? |
| Modèle de tarification | Prévisibilité à grande échelle | La tarification repose-t-elle sur des paliers d’usage que je peux anticiper ? |
Posez aussi une question directe : avez-vous besoin d’un produit de surveillance seul, ou de la boucle complète (créer un portefeuille, recevoir, envoyer et réconcilier) ? Beaucoup de projets de paiement commencent par la seule surveillance et finissent par vouloir le reste. Notre aperçu des cas d’usage d’une API blockchain montre comment ces briques se combinent, et l’article sur le e-commerce détaille un exemple de paiement.
Faut-il construire sa propre surveillance ou utiliser une API ?
Analyser soi-même la chaîne fonctionne dans une première version. Les problèmes apparaissent ensuite : une réorganisation crédite un paiement qui disparaît ensuite, un token aux décimales inhabituelles affiche un mauvais montant, un nœud prend du retard pendant une heure de pointe, et le support poursuit un client qui affirme avoir payé.
Avec Chaingateway, vous créez un portefeuille, un webhook pour son adresse, et vous recevez des événements décodés et signés. Les formes de requête sont identiques sur Ethereum, Bitcoin, Tron, Polygon, BNB Smart Chain et Arbitrum : ajouter un réseau revient donc à modifier une configuration. Vous ne faites tourner aucun nœud.
Trois habitudes comptent plus que le fournisseur choisi : décidez tôt de votre politique de confirmation, écrivez des gestionnaires idempotents avant votre premier paiement réel, et réconciliez selon un calendrier. Une API de surveillance doit les rendre faciles, sans remplacer leur nécessité.
Essayer sur vos propres adresses
Si vous développez des paiements, des dépôts ou des fonctions de portefeuille, vous pouvez voir comment la surveillance s’intègre dans une intégration complète avec Chaingateway. Les webhooks, la création de portefeuilles, les transferts de tokens et de NFT et les données de transaction décodées proviennent d’une seule API REST. Les forfaits sont échelonnés selon l’usage et les fonctions : Plus coûte 49 € par mois (ou 490 € par an), Pro 99 € par mois (990 € par an), Premium 249 € par mois (2 490 € par an) et Enterprise 499 € par mois (4 990 € par an). Vous commencez par un essai gratuit, et la page tarifs donne les détails actuels. Pour voir comment les événements arrivent jusqu’à votre application, lisez la présentation des webhooks Chaingateway.
Liste de contrôle minimale pour l’implémentation
Avant votre premier paiement réel, parcourez cette liste.
- Générez une adresse par facture ou par client, et affichez à côté le réseau attendu.
- Abonnez ces adresses aux événements entrants et sortants.
- Exposez un endpoint HTTPS qui vérifie l’en-tête
X-Signature. - Enregistrez chaque événement avec une clé unique, et ignorez les répétitions.
- Faites passer les paiements par des états stockés : en attente, confirmé, échoué.
- Définissez les seuils de confirmation par réseau et par montant.
- Planifiez une tâche de réconciliation avec l’historique des transactions de l’API.
- Alertez sur les livraisons échouées, les longs silences et les échecs de signature.
- Testez avec de petits montants réels sur chaque réseau et chaque token pris en charge, y compris un dépôt sur le mauvais réseau, afin de connaître à l’avance votre réponse au support.
Sources
- Qu’est-ce que la surveillance des transactions crypto ? | Elliptic
- RFC 2104 : HMAC, hachage à clé pour l’authentification des messages
- Définition OpenAPI de Chaingateway
Recommandés
Questions fréquentes
C’est un service qui observe des adresses blockchain et transmet l’activité les concernant à votre application, généralement par webhooks et par un endpoint de requête. Vous obtenez des événements décodés, comme un transfert de token entrant ou un retrait confirmé, sans faire tourner de nœuds vous-même.
Non. La surveillance opérationnelle d’adresses indique à votre application qu’un paiement est arrivé ou est parti. La surveillance des transactions à des fins de conformité analyse le comportement dans le temps pour signaler des schémas risqués, et des personnes examinent les alertes. Les entreprises réglementées utilisent souvent les deux.
Cela dépend du réseau et de la valeur en jeu, il n’existe donc pas de chiffre unique. Définissez un seuil par chaîne, relevez-le pour les montants plus élevés, et stockez « en attente » et « confirmé » comme deux états distincts dans votre base de données.
Donnez à chaque événement une clé unique, par exemple le hash de transaction associé à l’index du log ou à un identifiant de livraison, et imposez-la par une contrainte d’unicité. Si votre gestionnaire rencontre une clé déjà enregistrée, il renvoie un succès et ne fait rien d’autre.
Oui, si l’API est multi-chaînes. Chaingateway couvre Ethereum, Bitcoin, Tron, Solana, Polygon, BNB Smart Chain et Arbitrum via une seule API REST. Les webhooks couvrent toutes ces chaînes sauf Solana.
Comment nous rédigeons ces articles
Prêt à le construire vous-même ? Obtenir votre clé API — essai de 7 jours, sans carte bancaire — ou consultez API Blockchain pour la référence complète des endpoints.