Intégration blockchain multi-chaînes avec une API REST
Comment intégrer plusieurs blockchains via une API REST : réseaux, endpoints de tokens par chaîne, flux de dépôt et retrait, et différences qui subsistent.
Relu par Maurice Sobiera
L’intégration multi-blockchain signifie qu’un seul backend dialogue avec plusieurs chaînes via une interface unique, au lieu d’une bibliothèque client par chaîne. Avec Chaingateway, vous appelez des endpoints REST avec un jeton. Le même schéma couvre Ethereum, BNB Smart Chain, Polygon, Arbitrum, Tron, Bitcoin et Solana, dans les limites que chaque chaîne fixe.
Quelles blockchains et quels standards de tokens l’API couvre-t-elle ?
L’API couvre sept chaînes, chacune avec un testnet. Basculez sur le testnet avec l’en-tête X-Network: testnet. La page des réseaux pris en charge liste les réseaux de test. Les transferts de tokens ont un endpoint par chaîne :
| Chaîne | Endpoints de tokens et NFT dans le fichier OpenAPI | Testnet |
|---|---|---|
| Ethereum | transactions/erc20, transactions/erc721 | Sepolia |
| BNB Smart Chain | transactions/bep20, transactions/bep721 | Testnet BSC |
| Polygon | transactions/erc20, transactions/erc721 | Amoy |
| Arbitrum | transactions/erc20, transactions/erc721 | Arbitrum Sepolia |
| Tron | transactions/trc20, transactions/trc721, transactions/trc10 | Nile |
| Solana | transactions/SPL | Devnet |
| Bitcoin | transactions (monnaie native uniquement) | Testnet3 |
Chaque chemin commence par /api/v2/<chain>/. La liste complète figure dans le fichier OpenAPI.
Comment construire un service de dépôt et de retrait ?
Un flux de type dépositaire comporte trois parties : une adresse par client, un webhook par adresse et un appel de retrait. Chaque partie correspond à une requête, et chacune a la même forme sur chaque chaîne qui la prend en charge.
- Créez une adresse de dépôt. Sur les chaînes EVM et Tron, il s’agit de
POST /api/v2/<chain>/addresses, et la réponse contient l’adresse. Passez unpasswordpour que la clé soit stockée chiffrée. Sans mot de passe, la réponse contient la clé privée et vous devez la stocker vous-même. - Enregistrez un webhook pour l’adresse.
POST /api/v2/<chain>/webhooksprend l’urldu récepteur, l’adresse dansto, untypecommeERC20ouTRC20, et, en option, unecontractaddresset unereferencede 255 caractères au maximum. - Effectuez le paiement. Un retrait de token ERC20 est une seule requête :
curl -X POST https://app.chaingateway.io/api/v2/ethereum/transactions/erc20 \ -H "Authorization: Bearer $CHAINGATEWAY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "from": "0xHotWalletAddress", "to": "0xCustomerAddress", "contractaddress": "0xTokenContract", "amount": 100, "password": "hot-wallet-password" }'Sur BNB Smart Chain, remplacez ethereum/transactions/erc20 par bsc/transactions/bep20. Sur Tron, utilisez tron/transactions/trc20, qui prend les mêmes champs à part les réglages de gas. Solana fait exception : solana/transactions/SPL exige la privatekey de l’expéditeur et n’accepte pas de mot de passe de portefeuille. L’article sur les secrets personnels explique comment vérifier les notifications que vous recevez.
Que se passe-t-il quand une requête échoue ?
L’API renvoie un corps JSON avec status, ok et message. Un 401 avec le message « Wrong password provided » signifie que le mot de passe du portefeuille ne correspond pas. Un 422 transporte l’erreur du nœud elle-même, par exemple insufficient funds for gas * price + value. La partie propre à la chaîne en donne la raison : un transfert ERC20 sur Ethereum a besoin d’ETH pour le gas sur l’adresse expéditrice, et un transfert TRC20 a besoin d’énergie, de bande passante ou de TRX à brûler. Vérifiez les soldes avant de réessayer, car une nouvelle tentative ne corrige pas des frais manquants.
Les notifications de webhook échouées ne sont pas renvoyées automatiquement. Listez-les avec GET /api/v2/<chain>/webhooks/notifications/failed et renvoyez chacune avec l’endpoint de nouvelle tentative. Une notification renvoyée peut arriver après d’autres : rendez donc votre récepteur idempotent sur txid.
Qu’est-ce qui reste différent entre les chaînes ?
Plusieurs points restent différents, et l’API ne les masque pas :
- Frais : Ethereum, BNB Smart Chain, Polygon et Arbitrum utilisent le gas, avec un endpoint
gaspricepour chacun. Tron utilise l’énergie et la bande passante. - Webhooks : toutes les chaînes sauf Solana.
- Portefeuilles : Bitcoin fonctionne avec des portefeuilles nommés qui regroupent plusieurs adresses, créés par
POST /api/v2/bitcoin/wallets. - Actifs : un même token sur deux chaînes est deux actifs distincts, et l’API ne fait pas de pont entre eux.
Par quelle chaîne commencer ?
Commencez par la chaîne qu’utilisent déjà vos clients, et ajoutez les autres en réutilisant les mêmes gestionnaires. Les formulaires de retrait des plateformes d’échange indiquent le réseau, par exemple ERC-20, BEP-20 ou TRC-20. Demandez à vos premiers clients sur quel réseau ils détiennent de l’USDT avant de construire la deuxième intégration.
Que faut-il stocker par chaîne ?
Un service multi-chaînes doit inscrire la chaîne dans chaque enregistrement, car une même chaîne de caractères peut être valide sur plusieurs chaînes. Conservez au minimum ces champs :
| Champ | Pourquoi il est nécessaire |
|---|---|
chain et network | Les adresses 0x sont valides sur Ethereum, BNB Smart Chain, Polygon et Arbitrum, et le mainnet et le testnet se ressemblent |
address au format propre à la chaîne | Tron utilise des adresses Base58 qui commencent par T, et la forme hexadécimale avec un préfixe 41 apparaît dans les données brutes des nœuds |
contractaddress et type | Un même token a un contrat différent sur chaque chaîne |
txid | La clé pour dédupliquer les notifications de webhook et pour les recherches |
reference | Votre identifiant de commande ou de client, défini à l’enregistrement du webhook |
| Montant dans l’unité de base de la chaîne | Les décimales diffèrent selon le token : ne convertissez qu’au niveau de l’affichage |
Ajoutez une contrainte d’unicité sur (chain, network, txid). Rapprochez les données avec une seconde source selon un calendrier, par exemple la liste des notifications échouées et un explorateur de blocs.
Comment commencer ?
Commencez sur les testnets. Créez une adresse sur Sepolia et une sur Nile, enregistrez un webhook pour chacune, envoyez un transfert de test et vérifiez que votre récepteur traite les deux notifications. L’essai gratuit de 7 jours ne demande ni carte ni KYC.
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.