Ethereum API : transferts ERC-20 en un seul appel REST

JSON-RPC est le protocole natif de chaque node Ethereum, et pour certaines tâches (outillage de consensus, indexation personnalisée) vous voulez ce niveau d'accès. Notre guide sur l'interaction avec les nodes via JSON-RPC montre à quoi cela ressemble en PHP, Python et JavaScript.

Compter les allers-retours illustre bien le propos. Un transfert de token via JSON-RPC brut touche au moins quatre méthodes — eth_gasPrice, eth_estimateGas, eth_getTransactionCount et eth_sendRawTransaction — avec de l'encodage ABI et de la signature de transaction entre les deux.

Pour les paiements, l'abstraction est rentable. Dans la requête de transaction de Chaingateway, la limite de gas, le prix du gas et le nonce sont des champs optionnels — omettez-les et l'API les renseigne lors de la construction et de la diffusion de la transaction ; passez-les explicitement quand vous voulez le contrôle. Votre côté de l'échange est une seule requête HTTP que vous pouvez écrire dans n'importe quel langage avec une bibliothèque standard.

Si vous maintenez aujourd'hui une intégration web3.js, voici la comparaison honnête. Un transfert ERC-20 via la bibliothèque ressemble à peu près à ceci :

// web3.js contre votre propre endpoint RPC
const { Web3 } = require("web3");
const web3 = new Web3("https://your-rpc-endpoint");

const token = new web3.eth.Contract(ERC20_ABI, "0xdAC17F958D2ee523a2206206994597C13D831ec7");
const data = token.methods.transfer(recipient, amountInBaseUnits).encodeABI();

const tx = {
  from: sender,
  to: token.options.address,
  data,
  gas: await web3.eth.estimateGas({ from: sender, to: token.options.address, data }),
  gasPrice: await web3.eth.getGasPrice(),
  nonce: await web3.eth.getTransactionCount(sender),
};

const signed = await web3.eth.accounts.signTransaction(tx, PRIVATE_KEY);
await web3.eth.sendSignedTransaction(signed.rawTransaction);

Au-delà de ce qui tient dans l'extrait, ce code possède un fichier ABI, convertit manuellement des montants humains en unités de base (trompez-vous sur les décimales et vous envoyez un millionième de la somme prévue, ou un million de fois plus), et garde une clé privée brute en mémoire d'application. La version REST est le seul POST ci-dessus : montant en chaîne décimale, décimales gérées côté serveur, clé chiffrée au repos derrière un mot de passe.

La migration ne nécessite pas un week-end de réécriture. Les deux styles sont de simples appels, faites-les donc tourner côte à côte : routez les nouveaux flux de paiement via REST, laissez les interactions de contrat personnalisées sur web3.js, et retirez la bibliothèque partout où elle ne justifie plus sa complexité. Les équipes qui n'utilisaient web3.js que pour les transferts et les vérifications de solde tendent à supprimer entièrement la dépendance.

Chaque transaction Ethereum brûle du gas, payé en ETH par l'adresse expéditrice, jamais le destinataire. Un wallet détenant des milliers d'USDT mais zéro ETH ne peut envoyer aucun token, car le contrat ERC-20 n'a aucun moyen de couvrir son propre coût d'exécution. Recevoir des tokens ne coûte rien au destinataire.

Ce détail fait trébucher plus d'intégrations ERC-20 que tout autre. Si vos transferts pilotés par API proviennent d'un wallet de trésorerie, ce wallet a besoin d'un solde ETH en plus de ses tokens, et le recharger a sa place sur la checklist opérationnelle à côté des renouvellements de certificats.

Combien coûte le gas

Un simple transfert ETH coûte exactement 21 000 de gas — une constante du protocole. Un transfert ERC-20 exécute du code de contrat et coûte un multiple de cela, le chiffre exact variant selon le contrat de token. Le prix par unité flotte avec la demande : depuis la mise à niveau London de 2021, les frais se divisent en des frais de base que le réseau brûle et un pourboire de priorité au proposeur de bloc, et les deux augmentent sous congestion. La conséquence pratique : le même transfert USDT coûte des centimes un dimanche calme et considérablement plus pendant un mint populaire.

Ce que l'API gère pour vous

La limite de gas, le prix du gas et les plafonds EIP-1559 (maxFeePerGas, maxPriorityFeePerGas) sont des champs de requête optionnels — omettez-les et l'API les renseigne lors de la construction de votre transaction, ou fixez-les par requête quand vous voulez le contrôle. Deux choses restent de votre responsabilité : garder de l'ETH sur les wallets expéditeurs, et décider où les petits transferts ont un sens économique — quand les frais mainnet approchent le montant du transfert, le même appel sur Polygon ou Arbitrum n'est qu'un changement de chemin.

Recevoir est gratuit

Une adresse de dépôt n'a besoin d'aucun ETH pour accepter des tokens. Le gas ne devient votre problème que lorsque des fonds sortent — y compris quand vous balayez les dépôts clients vers un wallet de trésorerie, ce qui est en soi une transaction sortante depuis chaque adresse de dépôt.

Depuis le passage au proof of stake, le timing d'Ethereum est fixe plutôt que statistique. Les blocs arrivent dans des slots de douze secondes, 32 slots forment une époque de 6,4 minutes, et un bloc est finalisé après environ deux époques — disons 13 minutes — une fois que deux tiers de l'ETH staké l'ont attesté (paramètres du protocole mi-2026). Finalisé signifie que le réseau ne peut pas annuler le bloc sans détruire une part importante de tout l'ETH staké, ce qui le place dans une catégorie différente du règlement probabiliste de Bitcoin.

Pour la logique de paiement, la chronologie se lit ainsi : un transfert est typiquement inclus dans un bloc en quelques secondes à une minute ; chaque slot supplémentaire ajoute de l'assurance ; après environ 13 minutes il est final au sens strict. La plupart des applications créditent les dépôts bien avant la finalité — l'inclusion plus une poignée de blocs couvre les montants du quotidien — tandis que les plateformes d'échange retiennent généralement les gros retraits jusqu'à la finalisation. Le webhook de dépôt vous donne l'événement on-chain ; où vous placez la barre de crédit est une ligne de politique dans votre configuration, pas la nôtre.

USDT, USDC, DAI et les autres tokens établis fonctionnent d'emblée, avec des montants en unités de token plutôt qu'en unités de base brutes. Vous lancez votre propre ERC-20 ? Fournissez l'adresse du contrat et le même endpoint l'envoie. Aucun processus de listing, aucune attente. Le contexte sur le standard lui-même est dans notre guide du token ERC-20.

• C'est la plateforme de smart contracts la plus largement adoptée, éprouvée depuis 2015.
• L'écosystème DeFi est le plus grand de toutes les chaînes, avec des milliers de dApps à intégrer.
• La tarification du gas est dynamique, basée sur la demande réseau ; vous pouvez laisser les champs de frais à l'API ou les plafonner par requête avec les paramètres EIP-1559.
• Le travail de scaling continue, et Polygon et Arbitrum sont disponibles via la même API quand les frais mainnet mordent.

Le schéma de route ERC-20 se répète sur les réseaux EVM : /api/v2/polygon/transactions/erc20, /api/v2/arbitrum/transactions/erc20, et /api/v2/bsc/transactions/bep20 pour BNB Smart Chain. Du code écrit pour Ethereum se transpose en éditant le chemin. Quand le gas mainnet devient trop cher pour les petits transferts, les déplacer vers Polygon est un changement d'une ligne. La liste complète des chaînes est sur l'aperçu de la blockchain API.

Les briques ci-dessus couvrent la plupart des schémas de production que nous voyons : flux de checkout acceptant l'USDT ou l'USDC, plateformes d'échange qui créditent des dépôts et traitent des retraits à grande échelle, projets de tokens distribuant via airdrops ou calendriers de vesting, et entreprises par abonnement facturant en stablecoins chaque mois. Tous se réduisent aux deux mêmes appels : envoyer une transaction, recevoir un webhook.

Checkout en stablecoin pour une boutique web

Le client choisit « payer en USDT » et votre backend assigne une adresse de dépôt pour la commande — une adresse par facture, si bien que l'attribution ne dépend jamais de la correspondance des montants. Affichez l'adresse avec le montant, puis attendez le webhook. Quand la notification arrive, basculez la commande sur « paiement détecté » pour que l'acheteur voie une réaction rapidement ; créditez-la une fois que la transaction a la profondeur exigée par votre politique (la section finalité ci-dessus vous donne les chiffres). Un cas limite mérite sa place dans le code dès le premier jour : les wallets qui déduisent les frais du montant saisi produisent de légers sous-paiements, et votre tolérance à cela devrait être une valeur de configuration, pas un ticket de support.

Retraits pour une plateforme de trading

Les utilisateurs demandent des paiements sortants ; votre tâche est d'envoyer de nombreux transferts ERC-20 de manière fiable. Mettez chaque retrait en file dans votre base de données avec une colonne d'état, puis traitez la file avec POST /api/v2/ethereum/transactions/erc20 — une requête par paiement, en enregistrant la réponse avant de passer à la suivante. La règle qui satisfait les auditeurs : un appel HTTP en timeout n'est pas une transaction échouée. Vérifiez contre vos enregistrements et GET /api/v2/ethereum/transactions, qui liste chaque transaction créée via l'API, avant de renvoyer quoi que ce soit, sinon vous payez quelqu'un deux fois. Surveillez aussi le solde ETH du wallet de trésorerie, puisque chaque transfert sortant brûle du gas, et alertez bien avant qu'il ne s'épuise plutôt que quand la file se bloque.

Deux couches d'échec existent ici : les erreurs HTTP de l'API, et les conditions on-chain que votre logique doit absorber.

Le côté HTTP suit la convention. Un 401 signifie que la clé est manquante ou invalide — un problème de configuration, pas un candidat au nouvel essai. D'autres réponses 4xx indiquent que la requête est erronée : une adresse malformée, un contrat inconnu, un champ manquant. Loguez le corps de la réponse et corrigez l'appelant. Les nouveaux essais avec backoff n'appartiennent qu'aux réponses 5xx et aux timeouts réseau.

Le côté chaîne est là où le code de paiement gagne son salaire. Un transfert depuis un wallet sans assez d'ETH pour le gas échoue même si le solde de token est abondant — surveillez proactivement les soldes de gas plutôt que de les découvrir vides dans un message d'erreur. La congestion peut retarder l'inclusion ; c'est un délai, pas un échec, et votre UI devrait distinguer les deux. Et la règle du pas à pas sur les retraits mérite d'être répétée, car elle protège contre l'erreur la plus coûteuse dans ce domaine : ne renvoyez jamais un transfert juste parce que la réponse HTTP n'est jamais arrivée. Confirmez d'abord que cela ne s'est vraiment pas produit.

Pour les dépôts, construisez une habitude de réconciliation. GET /api/v2/ethereum/webhooks/notifications liste ce qui a été livré ; un diff nocturne contre votre registre capture tout ce qu'un bug ou une panne a englouti, pendant que la correction est encore peu coûteuse.

Ajoutez X-Network: testnet à n'importe quelle requête et elle s'exécute sur le réseau de test. Routes, corps de requête et formats de réponse restent identiques au mainnet, ce qui signifie que vos tests d'intégration exercent le vrai chemin de code plutôt que des mocks. Alimentez un wallet de test depuis un faucet public, exécutez des transferts, recevez des webhooks — toute la boucle ne coûte rien.

Structurez cela pour que l'en-tête provienne de la configuration : le staging le définit, la production non, et aucune différence de code n'existe entre les deux. Donnez aussi au staging une URL de callback séparée, sinon les dépôts de test atterriront dans votre handler webhook de production. Passer en production consiste alors à retirer un en-tête, délibérément anticlimatique.