Bitcoin API : accepter les paiements BTC sans faire tourner de node

Le JSON-RPC de Bitcoin Core veut une node synchronisée avant la première réponse utile. Une API REST veut une clé API. La différence se voit dans votre calendrier : le téléchargement initial des blocs prend des jours sur du matériel typique, et ensuite la node consomme disque et bande passante, et nécessite toujours une surveillance, aussi longtemps que votre produit existe. Notre article sur blockchain API vs. blockchain node compare les deux approches en détail. Faites tourner votre propre node quand vous avez besoin d'un contrôle au niveau des règles sur votre vue du réseau ; utilisez l'API quand les paiements sont l'objectif.

Les appels du quotidien se traduisent proprement dans le modèle REST. Là où une intégration à base de node enveloppe getnewaddress et listtransactions et sonde les changements, l'API assigne des adresses et laisse le webhook faire la surveillance. Les boucles de polling disparaissent, et avec elles les tâches cron qui échouent silencieusement un week-end.

Il existe une seconde différence. Les méthodes RPC brutes retournent des données brutes. Chaingateway retourne du JSON structuré avec des champs lisibles, si bien qu'une réponse peut aller directement dans votre base de données plutôt que passer par une couche de parsing.

Le côté REST du chemin d'envoi tient en trois endpoints. POST /api/v2/bitcoin/wallets crée un wallet, chiffré avec un mot de passe que Chaingateway ne stocke pas — perdez-le et personne ne peut restaurer le wallet, ce qui est précisément l'objectif. POST /api/v2/bitcoin/wallets/{wallet}/addresses dérive autant d'adresses sous lui que nécessaire ; un wallet les porte toutes. Et POST /api/v2/bitcoin/transactions envoie :

curl -X POST https://app.chaingateway.io/api/v2/bitcoin/transactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
    "amount": 0.0015,
    "walletname": "treasury",
    "password": "wallet-password",
    "speed": "medium"
  }'

La réponse porte le txid de la transaction diffusée. speed accepte fast, medium ou slow et fixe le niveau de frais — le compromis entre coût et délai jusqu'à la première confirmation. Un subtractfee: true optionnel déduit les frais réseau du montant plutôt que de les ajouter, ce que vous voulez quand un client retire la totalité de son solde.

Bitcoin ajoute un bloc environ toutes les dix minutes, bien que les écarts individuels varient largement. Chaque nouveau bloc miné par-dessus celui contenant votre transaction ajoute une confirmation, et chaque confirmation rend un renversement plus difficile.

Six confirmations — environ une heure — sont le standard de facto pour « réglé » depuis les débuts des plateformes d'échange, et cela tient toujours mi-2026.

Dix minutes sont une moyenne, pas un horaire

L'ajustement de difficulté la maintient dans le temps, mais les écarts individuels se dispersent largement autour — deux blocs en une minute arrivent, tout comme des sécheresses de quarante minutes. L'UX de paiement doit en tenir compte : « environ dix minutes » est une moyenne, pas une promesse, donc votre page de checkout devrait dire « généralement dans l'heure » plutôt que faire tourner un compte à rebours qu'elle ne peut pas tenir.

Pourquoi ne pas créditer à zéro confirmation ?

Parce que tant qu'une transaction n'est pas dans un bloc, elle reste dans le mempool, où elle peut être remplacée ou faire l'objet d'une double dépense, et même le bloc le plus récent peut sortir de la chaîne lors d'une réorganisation. L'API scinde ce travail en deux. Le webhook se déclenche une fois la transaction réglée on-chain — le payload porte montant, adresse, txid et numéro de bloc — pour que votre UI puisse réagir immédiatement. À partir de là, GET /api/v2/bitcoin/transactions/{txid}/decoded retourne le nombre de confirmations actuel, si bien que votre registre ne crédite que l'argent ayant atteint votre seuil. Montrez la progression tôt, réglez tard.

Bitcoin n'a pas de soldes de compte. Ce que la chaîne stocke, ce sont des unspent transaction outputs — UTXO —, chacun un morceau discret de valeur verrouillé sur une adresse. Le « solde » d'un wallet est un nombre que votre logiciel dérive en additionnant chaque UTXO que ses adresses contrôlent ; le protocole ne stocke jamais cette somme nulle part. Dépenser consomme des UTXO entiers et en crée de nouveaux, y compris une sortie de monnaie rendue vers vous-même, de la même façon que payer une facture de 7 euros avec un billet de 10 euros rend de la monnaie.

Ethereum fonctionne selon le modèle opposé. Un compte a un solde, la chaîne le stocke directement, et un dépôt est un incrément. Sur les chaînes EVM, il est normal de donner une adresse à un client et de laisser une centaine de dépôts s'y accumuler au fil des années.

Pour la gestion des dépôts, le modèle UTXO a un avantage pratique : il vous pousse vers une adresse par client ou par facture, ce qui est de toute façon le design le plus propre. Chaque paiement entrant est une nouvelle sortie vers une adresse que vous surveillez, donc l'attribution est sans ambiguïté — pas de parsing de mémo, pas de correspondance par montant. Cela signifie aussi que « le solde d'une adresse » est une question à laquelle répond un indexeur plutôt que la chaîne elle-même — précisément la comptabilité que vous externalisez en utilisant une API avec des webhooks plutôt qu'en faisant tourner la machinerie vous-même. La notification vous dit : ce montant, cette adresse, cette transaction, ce bloc. Votre registre fait le reste.

Ajoutez l'en-tête X-Network: testnet et chaque appel de cette page tourne contre le réseau de test de Bitcoin : mêmes routes, mêmes formes de réponse, pièces sans valeur. Les faucets distribuent gratuitement du BTC de test, si bien que tout le flux de dépôt — adresse, paiement, webhook, confirmations — peut être répété de bout en bout sans dépenser un satoshi.

Gardez l'en-tête derrière la configuration plutôt que dispersé dans le code, et donnez à votre environnement de staging une URL de callback séparée pour que les dépôts de test ne puissent pas fuiter dans le registre de production. Quand la répétition fonctionne, retirez l'en-tête. Rien d'autre ne change dans l'intégration, ce qui est le but : le premier dépôt mainnet devrait être ennuyeux.

Un backend de paiement gagne sa place dans les mauvais jours, planifiez donc explicitement les chemins d'échec.

Au niveau HTTP, les règles sont du REST standard. Un 401 signifie que le jeton Bearer est faux ou manquant ; corrigez la clé plutôt que de réessayer. Les autres réponses 4xx pointent vers la requête elle-même — loguez le corps, qui nomme le problème, et traitez-le comme un bug. Les réponses dans la plage 5xx et les timeouts sont transitoires ; réessayez-les avec un backoff.

Les modes d'échec spécifiques à Bitcoin vivent au-dessus de HTTP. Un dépôt qui ne confirme jamais a généralement payé trop peu de frais et reste coincé dans le mempool ; il peut confirmer des heures plus tard ou disparaître entièrement, c'est pourquoi detected et settled doivent rester des états séparés dans votre système. Une notification pour un montant inférieur à la facture est une décision métier, pas une erreur — gérez-la dans le code, pas dans une file de support. Et si votre endpoint webhook était en panne, les livraisons échouées vous attendent : GET /api/v2/bitcoin/webhooks/notifications/failed les liste, POST /api/v2/bitcoin/webhooks/notifications/{id}/retry renvoie chacune, et la liste complète sous GET /api/v2/bitcoin/webhooks/notifications vous permet de comparer avec le registre et de combler les écarts. Faites tourner cette comparaison chaque nuit même quand rien ne semble anormal. Une réconciliation qui ne tourne qu'après des incidents trouve ses bugs en production.

Bitcoin lui-même n'a pas d'USDT ni d'USDC — les stablecoins vivent sur d'autres chaînes. Ce que la plateforme partagée vous donne, c'est une longueur d'avance : votre intégration Bitcoin parle déjà la même API que nos endpoints Ethereum et TRON. Acceptez le BTC aujourd'hui, ajoutez l'USDT sur TRON au prochain sprint avec la même clé et le même handler de webhook. L'aperçu de la blockchain API liste les sept chaînes supportées.

L'ordre pratique pour la plupart des équipes : lancer d'abord les dépôts BTC, car c'est ce que les clients demandent nommément, puis laisser les données de paiement indiquer quel rail stablecoin ajouter en second. Chez Chaingateway, ce second rail réutilise votre vérification de signature, votre tâche de réconciliation et votre machine à états de dépôt sans changement.

• Il a le plus long historique de toutes les blockchains, en fonctionnement depuis 2009, et la reconnaissance la plus large parmi les utilisateurs finaux.
• Le réseau règle en continu. Il n'y a ni horaires bancaires ni coupures régionales.
• Les confirmations suivent un rythme prévisible, avec un nouveau bloc environ toutes les dix minutes, ce qui garde les flux de paiement faciles à raisonner.
• L'adoption est la plus large de tous les réseaux crypto, donc « acceptez-vous Bitcoin ? » reste la première question que posent les clients.

Aucune de ces propriétés ne vient d'une mise à jour de roadmap ; ce sont les mêmes garanties avec lesquelles le réseau a été livré. Cette stabilité est l'argument en faveur du BTC dans les produits à long horizon : une intégration construite cette année ne sera pas rendue obsolète par un virage de protocole l'année prochaine, ce qui est plus que ce que peuvent prétendre la plupart des piles de paiement.

Le cas évident est le checkout : un client choisit Bitcoin et votre app assigne une adresse ; le webhook confirme le paiement. Les mêmes briques portent aussi des charges plus lourdes. Les plateformes d'échange et de gaming font tourner une adresse de dépôt par utilisateur et créditent les soldes à la confirmation. Les flux de paiement et d'envoi de fonds poussent des transferts transfrontaliers sans banques correspondantes au milieu. Les entreprises par abonnement génèrent une nouvelle adresse de facture à chaque cycle et laissent le webhook la clôturer.

Ce que ces cas partagent, c'est la forme du travail. Bitcoin gère le règlement ; votre application gère l'état. L'API se situe entre les deux et transforme les événements on-chain en appels HTTP que votre framework sait déjà router — c'est pourquoi le cas du checkout et le cas de la plateforme d'échange tournent sur la même poignée d'endpoints.