Comment envoyer des tokens ERC-20 : méthodes portefeuille, code et API

Vous pouvez envoyer des tokens ERC-20 de trois manières : depuis une application de portefeuille, depuis votre propre code avec une bibliothèque telle qu’ethers.js, ou via une API REST qui signe et diffuse pour vous. Les trois font la même chose en dessous. Elles appellent la fonction transfer sur le contrat intelligent du token, et l’expéditeur paie les frais de réseau en ETH, pas en tokens. Ce guide couvre chaque méthode, les erreurs qui font perdre des fonds, et ce qui change quand on passe d’un transfert manuel à des milliers de transferts automatisés.

TL;DR

• Un transfert ERC-20 est un appel au contrat du token, pas un transfert de valeur simple comme l’ETH. L’adresse du destinataire et le montant vont dans les données d’appel.
• Le portefeuille d’envoi a besoin d’ETH pour le gas même s’il détient beaucoup de tokens. Avec zéro ETH, la transaction échoue.
• N’envoyez jamais de tokens directement dans un contrat qui n’a pas de code pour les gérer. Utilisez approve et transferFrom pour les interactions avec des contrats.
• Dans le code, gérez les décimales des tokens et les tokens qui ne renvoient pas de booléen standard. Enveloppez les appels avec une bibliothèque sécurisée.
• Si vous construisez une application qui envoie des tokens pour les utilisateurs, une API REST supprime le travail sur les nœuds, les nonces et le gas. Nous couvrons cela ci-dessous.

Table des matières

• Ce qui se passe réellement quand vous envoyez un token ERC-20
• Avant d’envoyer : une courte liste de contrôle
• Méthode 1 : Envoyer depuis un portefeuille
• Méthode 2 : Envoyer avec du code (ethers.js)
• Méthode 3 : Envoyer via une API REST
• Manières courantes dont les transferts ERC-20 tournent mal
• Transferts sans gas et méta-transactions
• Notre point de vue : traitez un transfert comme un flux de travail, pas comme un appel
• Automatiser les transferts avec Chaingateway
• Confirmer que le transfert a fonctionné
• FAQ
• Sources

Ce qui se passe réellement quand vous envoyez un token ERC-20

Envoyer de l’ETH déplace de la valeur native entre deux comptes. Envoyer un token ERC-20 modifie un registre de soldes stocké à l’intérieur du contrat du token. Votre portefeuille crée une transaction adressée au contrat du token, et ce contrat met à jour les soldes de l’expéditeur et du destinataire.

La norme ERC-20 définit les méthodes que chaque token conforme expose : totalSupply, balanceOf, transfer, transferFrom, approve et allowance. Cette interface partagée est la raison pour laquelle un portefeuille ou un morceau de code peut gérer des milliers de tokens différents. La spécification originale est EIP-20, publiée en novembre 2015.

Quelques conséquences découlent de cette conception :

• Le champ to de la transaction est le contrat du token, et non la personne que vous payez. Le véritable destinataire est encodé dans les données d’appel.
• Les données d’appel commencent par le sélecteur de fonction 0xa9059cbb (la signature transfer), suivis de l’adresse du destinataire et du montant, selon la documentation ERC-20 d’ethereum.org.
• ERC-20 est une norme de token, pas la même chose qu’Ethereum. ETH est la monnaie native du réseau. Les tokens comme USDT sont des contrats qui s’exécutent dessus. Pour une vue d’ensemble plus large sur le gas et ETH, consultez notre aperçu d’Ethereum.

Le même format existe également sur d’autres chaînes EVM. Notre article sur la norme de token ERC20 approfondit son fonctionnement, et le guide d’adresse ERC20 explique le format d’adresse et la consultation des soldes.

Avant d’envoyer : une courte liste de contrôle

La plupart des transferts perdus proviennent d’une préparation négligée, pas d’une défaillance technique. Vérifiez ces points d’abord.

1. Vous détenez le token et le bon montant. Confirmez le solde avec balanceOf ou dans votre portefeuille.
2. Vous détenez de l’ETH pour le gas. Les frais sont payés dans la monnaie native du réseau, et non déduits des tokens que vous envoyez. Sur Polygon ou BNB Chain, la même logique s’applique avec la monnaie native de cette chaîne. Un portefeuille avec des tokens mais sans ETH ne peut rien envoyer.
3. Vous avez l’adresse exacte du destinataire. Copiez-collez-la plutôt que de la taper. Le centre d’aide de MetaMask met en garde contre l’empoisonnement d’adresse, où un attaquant pollue votre historique avec une adresse sosie.
4. Vous connaissez le réseau. Le même format d’adresse fonctionne sur plusieurs chaînes EVM. Un token envoyé sur le mauvais réseau n’arrive pas là où le destinataire l’attend.
5. Le destinataire peut l’accepter. Envoyer vers une adresse de dépôt d’échange sur le mauvais réseau, ou vers un contrat incapable de gérer les tokens, peut signifier une perte permanente.
6. Vous testez d’abord avec un petit montant. Pour un nouveau destinataire ou une nouvelle intégration, envoyez un petit montant et confirmez qu’il est arrivé avant d’envoyer la somme totale.

Méthode 1 : Envoyer depuis un portefeuille

Pour les transferts ponctuels, un portefeuille est la voie la plus simple. Le guide d’Etherscan pour envoyer de l’ETH ou des tokens décrit le même flux que suivent la plupart des portefeuilles :

1. Ouvrez le portefeuille et choisissez l’option d’envoi.
2. Sélectionnez le token que vous souhaitez envoyer. Si le portefeuille ne le liste pas, ajoutez-le en collant l’adresse du contrat du token.
3. Collez l’adresse du destinataire.
4. Saisissez le montant.
5. Examinez les frais de réseau. Le portefeuille les estime pour vous.
6. Confirmez, puis suivez le hachage de la transaction sur un explorateur de blocs jusqu’à sa confirmation.

Deux détails piègent les gens. Premièrement, l’adresse du contrat du token que vous collez lors de l’ajout d’un token personnalisé doit être la vraie, car de faux tokens utilisent le même nom et le même symbole. Vérifiez-la sur le site officiel du projet. Deuxièmement, les frais affichés sont en ETH, donc le solde ETH du portefeuille doit les couvrir en plus de l’ETH que vous avez l’intention d’envoyer.

Méthode 2 : Envoyer avec du code (ethers.js)

Les développeurs qui ont besoin d’automatiser les transferts peuvent appeler le contrat directement. Le tutoriel ethereum.org sur l’envoi de tokens avec ethers.js montre le schéma de base. Une procédure pas à pas ethers.js distincte explique la différence clé avec l’ETH : la transaction n’envoie aucune valeur, elle appelle la fonction transfer du token avec une destination et un montant.

Les étapes ressemblent à ceci :

1. Créez un fournisseur connecté à un nœud Ethereum (le vôtre ou un point de terminaison hébergé).
2. Créez un signataire à partir d’une clé privée ou d’un portefeuille que vous contrôlez.
3. Instanciez le contrat du token avec son adresse et un ABI minimal contenant transfer, balanceOf et decimals.
4. Convertissez le montant humain en unités de base en utilisant les décimales du token.
5. Appelez transfer(destinataire, montant) et attendez le reçu.

Ce tutoriel ethers.js note que la bibliothèque peut envoyer une transaction EIP-1559 sans réglages de gaz manuels, en choisissant une limite de gaz et des frais de priorité par défaut. Elle peut également gérer le nonce lorsque vous utilisez un signataire.

Gérer correctement les décimales

Les tokens stockent les montants sous forme d’entiers. Un token avec 18 décimales représente 1,0 token comme 1000000000000000000 unités de base. Le champ decimals fait partie de la norme mais différents tokens définissent différentes valeurs, et le texte de l’EIP-20 le traite comme des métadonnées optionnelles. Lisez toujours decimals depuis le contrat au lieu de supposer 18. Coder en dur la mauvaise valeur envoie un montant décalé d’ordres de grandeur.

Ne pas faire aveuglément confiance à la valeur de retour

La norme dit que transfer renvoie un booléen. Tous les tokens dans la nature ne se comportent pas ainsi. Certains ne renvoient rien, et certains échouent de manière inattendue. L’interface IERC20 d’OpenZeppelin est la référence pour la norme, et la bibliothèque SafeERC20 d’OpenZeppelin existe pour encapsuler les appels afin que les tokens bizarres ne cassent pas votre logique. Si votre contrat intelligent déplace des tokens, utilisez-la. Si votre backend envoie des tokens, vérifiez le statut du reçu de transaction et l’événement Transfer émis au lieu de supposer le succès.

Limites de gaz

Un transfert d’ETH simple utilise une limite de gaz de 21 000, selon les recommandations de MetaMask. Un transfert de token est un appel de contrat, donc il en a besoin de plus. Estimez le gaz avec l’appel d’estimation de votre bibliothèque avant chaque envoi plutôt que de coder en dur un nombre, car le coût dépend du code du contrat du token et de l’état des soldes impliqués.

Méthode 3 : Envoyer via une API REST

Exécuter le chemin de code ci-dessus convient pour un script. Dans un produit, cela devient une liste de corvées : exploiter ou louer l’accès aux nœuds, gérer les clés, suivre les nonces pour que les envois concurrents ne se heurtent pas, estimer le gaz, réessayer les transactions bloquées, décoder les logs pour savoir si un paiement est arrivé, et répéter tout cela par chaîne.

Une API unifiée retire cette couche de votre équipe. Avec Chaingateway, vous créez des portefeuilles, envoyez des tokens et lisez des données de transaction décodées via de simples appels REST. Vous n’avez pas besoin de web3.js ou ethers.js dans votre pile, et vous n’exécutez pas de nœuds. Notre page API Ethereum montre comment l’envoi ERC-20 fonctionne via REST. Les requêtes sont signées HMAC, et le gaz est estimé automatiquement.

La même approche s’étend au Bitcoin, Tron, Solana, Polyggon, BNB Chain et Arbitrum, de sorte qu’une seconde chaîne ne signifie pas une seconde intégration. Si vous ajoutez ultérieurement l’USDT Tron, consultez notre explication sur TRC10 vs TRC20. Pour les adresses BNB Chain, voir le guide d’adresse BEP20.

Quand chaque méthode convient

Situation	Portefeuille	Votre propre code	API REST
Transfert personnel ponctuel	Meilleur	Exagéré	Exagéré
Script occasionnel sur une chaîne	Lent	Bon	Bon
Paiements ou retraits dans une application	Pas pratique	Possible, vous le maintenez	Meilleur choix
Plusieurs chaînes et standards de jetons	Manuel par chaîne	Un client par chaîne	Une interface
Détection de paiements entrants	Manuel	Vous construisez des écouteurs de logs	Webhooks

Erreurs courantes lors des transferts ERC-20

Envoi de jetons vers un contrat

La fonction transfer n’a pas été conçue pour déposer dans des contrats intelligents. Si un contrat n’a aucune logique pour réagir aux jetons entrants, ils restent dans son solde sans possibilité de sortie. La page ERC-20 d’ethereum.org décrit ce risque, y compris les jetons envoyés au propre contrat du jeton, et signale des millions de dollars perdus de cette façon en juin 2024. Si vous écrivez des contrats, ajoutez une fonction qui permet de récupérer les jetons envoyés par erreur. Si vous avez besoin qu’un contrat reçoive des jetons d’un utilisateur, le schéma standard est : l’utilisateur appelle approve pour le contrat, puis le contrat appelle transferFrom.

Zéro ETH pour le gas

La transaction échoue si l’expéditeur n’a pas de devise native, quel que soit le nombre de jetons dans le portefeuille. Les équipes produit découvrent souvent cela tard : un utilisateur reçoit des jetons, essaie de les déplacer, et ne peut pas. Les options sont de créditer le portefeuille avec une petite quantité d’ETH, ou de concevoir autour de cela avec des autorisations signées.

Mauvais réseau ou mauvaise adresse

Les blockchains n’annulent pas les transactions. Vérifiez le réseau et l’adresse avant de confirmer, et utilisez un petit transfert de test pour toute nouveauté.

Confondre le jeton avec le réseau

L’USDT, par exemple, existe sur plusieurs chaînes. Quand quelqu’un dit qu’il détient de l’USDT, demandez sur quel réseau. L’adresse peut sembler identique sur chacune, mais les fonds ne vivent que sur une seule chaîne.

Transferts sans gas et méta-transactions

Une option croissante pour l’intégration est de laisser l’utilisateur signer un message et de faire soumettre la transaction et payer le gas par quelqu’un d’autre. EIP-3009, Transfer With Authorization, définit des fonctions qui permettent à un détenteur de déléguer le paiement du gas et d’exécuter les transferts via des signatures EIP-712. Seuls les jetons dont les contrats l’implémentent le supportent, donc vérifiez avant de concevoir un flux autour de cela. Pour une startup, cela peut supprimer l’obstacle du premier transfert qui consiste à acquérir de l’ETH.

Notre point de vue : traitez un transfert comme un flux de travail, pas comme un appel

Nous observons le même schéma dans les équipes qui intègrent l’envoi de tokens pour la première fois. L’appel transfer lui-même prend un après-midi. Les semaines passent dans tout ce qui l’entoure : savoir quand un paiement a vraiment atterri, gérer une transaction échouée ou bloquée, estimer les frais et garder les clés en sécurité.

Notre vision est que l’envoi et la réception vont de pair. Un flux de paiement sans événements de confirmation vous oblige à faire du polling, et un flux de dépôt sans données décodées vous oblige à analyser des logs bruts. C’est pourquoi nous avons regroupé la création de portefeuilles, les transferts de tokens, l’estimation du gas, les données de transaction décodées et les notifications par webhook derrière une seule API, signée avec HMAC. Vous obtenez un seul contrat avec votre infrastructure au lieu d’un par chaîne, et vous ne gérez pas de nœuds.

Notre conseil pratique : commencez par un petit transfert sur un environnement de test, vérifiez les décimales et les reçus, abonnez-vous aux événements pour la confirmation, et seulement ensuite augmentez les volumes.

— Bitblade

Automatiser les transferts avec Chaingateway

Si vous développez des paiements sortants, des retraits ou des dépôts dans une application, vous pouvez essayer notre API Blockchain et l’associer aux Webhooks Chaingateway pour être notifié quand les paiements arrivent. Les formules sur notre page de tarification commencent à 49 EUR par mois pour Plus, 99 EUR par mois pour Pro, 249 EUR par mois pour Premium et 499 EUR par mois pour Enterprise. La facturation annuelle est de 490 EUR pour Plus, 990 EUR pour Pro, 2490 EUR pour Premium et 4990 EUR pour Enterprise. L’accès payant fait suite à un essai gratuit.

Confirmer que le transfert a fonctionné

Soumettre une transaction n’est pas la même chose que finaliser un paiement. Après l’envoi :

1. Stockez immédiatement le hash de transaction.
2. Vérifiez le statut du reçu. Une transaction minée peut quand même avoir échoué.
3. Recherchez l’événement Transfer du contrat de token avec l’expéditeur, le destinataire et le montant attendus. Cet événement fait partie de l’interface ERC-20.
4. Attendez autant de confirmations que votre politique de risque l’exige avant de livrer des biens ou de créditer un solde.
5. Rapprochez périodiquement avec balanceOf pour détecter tout ce que votre écouteur aurait manqué.

Le polling fonctionne pour un petit script. En production, s’abonner aux notifications signifie que votre système réagit aux événements au lieu de demander répétitivement.

Sources

• Standard de jeton ERC-20, ethereum.org
• EIP-20 : Standard de jeton ERC-20
• Comment envoyer des jetons depuis votre portefeuille MetaMask, Centre d’aide MetaMask
• Comment envoyer de l’ETH ou un jeton, Centre d’information Etherscan
• Envoi de jetons avec ethers.js, ethereum.org
• Ethers.js : Comment envoyer des jetons ERC-20, Centre d’aide MetaMask
• IERC20.sol, Contrats OpenZeppelin
• ERC-3009 : Transfert avec autorisation

Recommandé

• API Ethereum – Envoyer des jetons ERC-20 via REST, Sans web3.js
• Le standard de jeton ERC20