TRON API : paiements USDT-TRC20 via REST

Tether avait émis environ 190 milliards de dollars d'USDT d'ici avril 2026. TRON portait environ 45 % de cette offre, environ 85 milliards de dollars, avec Ethereum juste derrière à environ 40 % ; les deux chaînes ont échangé la tête plusieurs fois depuis fin 2025. Sur TRON elle-même, le tableau est sans ambiguïté : l'USDT représentait 98,6 % de la valeur en stablecoins de la chaîne au T1 2026. Quiconque dit que TRC-20 signifie USDT, à toutes fins pratiques.

L'offre n'est que la moitié de l'histoire. Le volume de transfert vous dit à quoi sert une chaîne, et le volume USDT de TRON a approché les 2 000 milliards de dollars au premier trimestre 2026. L'USDT d'Ethereum penche vers le collatéral DeFi et le règlement institutionnel. Celui de TRON est la version que les gens déplacent réellement : dépôts sur plateformes d'échange, envois de fonds, paiements à des contractants dans des pays où un solde en dollars vaut mieux que le compte bancaire local.

Pour une décision d'intégration, la conséquence est nette. Si vos utilisateurs choisissent un réseau de dépôt dans un menu déroulant, TRC-20 sera l'entrée la plus choisie, et les tickets de support pour mauvais réseau diminuent quand votre défaut correspond à ce que les utilisateurs attendent. Construisez TRON en premier ; le schéma de requête partagé vous permet d'ajouter les autres chaînes plus tard sans nouveau code.

TRON mesure deux ressources. Le Bandwidth couvre les transferts simples et est gratuit jusqu'à 600 points par jour. L'Energy n'a aucune allocation gratuite et s'applique dès qu'un smart contract s'exécute, ce qui explique pourquoi un transfert USDT, un appel de contrat TRC-20, coûte toujours plus cher qu'envoyer du TRX simple.

TRON n'a pas de prix de gas unique. Le réseau mesure deux ressources distinctes, et savoir laquelle votre transaction consomme fait la différence entre des frais prévisibles et des tickets de support surprises.

Le Bandwidth est facturé sur chaque transaction et suit la taille en octets. Chaque compte reçoit 600 points gratuits par jour ; un transfert TRX simple pèse 250 à 300 octets, donc des transferts TRX occasionnels ne coûtent rien du tout. Au-delà du quota gratuit, le réseau brûle 0,001 TRX par point, environ 0,35 TRX pour un transfert TRC-20 typique.

L'Energy s'applique seulement quand un smart contract s'exécute, et n'a aucune allocation quotidienne gratuite. Un transfert USDT est un appel de contrat, le contrat TRC-20 met à jour sa table de soldes interne, il nécessite donc de l'Energy en plus du Bandwidth. Depuis l'entrée en vigueur de la proposition de gouvernance #104 en août 2025, une unité d'Energy coûte 100 Sun, réduite de moitié depuis 210. Un transfert vers une adresse qui détient déjà de l'USDT nécessite environ 64 000 d'Energy, soit 6,4 TRX. Un transfert vers une adresse qui n'a jamais détenu d'USDT écrit une nouvelle entrée de stockage, et un nouvel état coûte environ le double d'Energy d'une mise à jour : environ 134 000 unités, soit 13,4 TRX.

Avant d'envoyer, deux outils rendent les chiffres concrets. Le calculateur de frais TRON calcule le Bandwidth, l'Energy et le total en TRX pour une transaction spécifique, et GET /api/v2/tron/chainparameters retourne les prix unitaires en direct pour que votre code n'intègre jamais une constante que le prochain vote de gouvernance change. Le guide des frais couvre la mécanique en profondeur.

Chaque transfert TRC-20 nécessite de l'Energy, et cette Energy doit venir de quelque part. Pour la plupart des expéditeurs, la source est leur propre solde TRX. Cette hypothèse s'effondre dans deux situations courantes, et les deux génèrent une douleur opérationnelle jusqu'à ce que vous les corrigiez structurellement.

Votre propre flotte de wallets de dépôt

Chaque wallet qui fait suivre des fonds vers un hot wallet a besoin de son propre solde TRX pour le balayage, et avec quelques milliers de wallets, la recharge devient un travail à part entière, avec ses propres coûts de frais pour les transferts de recharge. Les frais sponsorisés éliminent ce travail. La façon recommandée de configurer cela aujourd'hui est TronFuel, qui loue de l'Energy sourcée en masse auprès des stakers — le même mécanisme que le guide des frais décrit comme réduisant les coûts de frais jusqu'à 60 % par rapport à la combustion de TRX au prix du marché. Les endpoints Paymaster legacy de Chaingateway font la même chose et restent disponibles pour les intégrations existantes.

Vos clients finaux

Un utilisateur détient 200 USDT dans un wallet en self-custody et zéro TRX ; l'USDT est arrivé d'une plateforme d'échange ou d'une autre personne, et personne ne lui a dit qu'une seconde monnaie est nécessaire pour le déplacer. Quand il essaie de vous payer ou de retirer, le transfert échoue. Du point de vue de l'utilisateur, l'argent est bloqué. Du point de vue de votre file de support, c'est un ticket récurrent qu'aucune entrée de FAQ ne tue complètement, parce que la solution, « va d'abord acheter du TRX sur une plateforme d'échange », est exactement la friction que le client voulait éviter en utilisant des stablecoins. Un transfert sponsorisé met fin à cela : vous soumettez le transfert, le sponsor couvre l'Energy et le Bandwidth, le coût atterrit sur votre compte, et le client n'apprend jamais ce qu'est le TRX. Pour les flux de checkout et de retrait, ce seul changement supprime le mode d'échec le plus courant des paiements TRC-20.

Tarifer et créer un transfert sponsorisé

Tarifez d'abord une transaction sponsorisée, puis créez-la :

# 1. Estimer les frais
curl -X POST https://app.chaingateway.io/api/v2/tron/paymaster/estimate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "TRC20", "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "from": "TDepositWallet", "to": "THotWallet", "amount": "500"}'

# 2. Créer la demande Paymaster
curl -X POST https://app.chaingateway.io/api/v2/tron/paymaster \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "TRC20", "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "from": "TDepositWallet", "to": "THotWallet", "amount": "500", "password": "YourWalletPassword"}'

GET /api/v2/tron/paymaster liste chaque demande que vous avez créée et rapporte son statut de pending à completed ou failed, et GET /api/v2/tron/paymaster/balance montre le crédit de sponsoring qu'il vous reste — ensemble, ils couvrent la réconciliation.

Importer une clé privée est le chemin le plus rapide vers la production, mais certaines équipes ne peuvent absolument pas expédier de matériel de clé à un tiers. La raison peut être une politique interne, un régulateur, ou un module de sécurité matériel dont les clés ne peuvent physiquement pas être exportées. L'API TRON a un second mode construit exactement pour cette contrainte.

Le flux a trois étapes. Appelez POST /api/v2/tron/transactions/trc20/build, ou /api/v2/tron/transactions/build pour du TRX simple, avec les mêmes champs que vous utiliseriez pour un envoi normal. L'API retourne la transaction brute non signée. Signez ce payload là où vivent vos clés : un HSM, une machine air-gapped, un service de signature derrière votre propre pare-feu. Puis soumettez le résultat signé via POST /api/v2/tron/transactions/broadcast, qui le pousse vers le réseau et retourne le hash de transaction.

# 1. Construire la transaction non signée
curl -X POST https://app.chaingateway.io/api/v2/tron/transactions/trc20/build \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "from": "TColdWallet", "to": "TRecipient", "amount": 1000}'

# 2. Signer localement avec votre propre outillage, puis diffuser
curl -X POST https://app.chaingateway.io/api/v2/tron/transactions/broadcast \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"signed_transaction": "<la transaction signée sous forme de chaîne JSON>"}'

Deux choses à savoir avant de choisir ce mode. Une transaction TRON construite expire après une courte fenêtre, donc l'étape signer-et-diffuser doit se produire rapidement plutôt que de rester dans une file toute la nuit. Et la responsabilité opérationnelle se déplace : votre côté possède la bibliothèque de signature et ses mises à jour. Ce que vous gagnez, c'est que Chaingateway ne voit jamais de secret. La surveillance des dépôts n'est pas affectée dans un cas comme dans l'autre, puisque surveiller une adresse ne nécessite aucune clé. Beaucoup de configurations de production mélangent les deux modes, clés importées pour les wallets opérationnels de faible valeur, auto-signature pour le chemin de trésorerie.

Sonder un explorateur pour les transferts entrants gaspille des requêtes et se trompe quand même sur le timing. Chaingateway pousse à la place. Enregistrez un webhook et votre backend reçoit un POST pour le statut de transaction, les confirmations et les changements de solde. Définissez un secret personnel dans votre compte et chaque livraison porte un en-tête X-Signature — un HMAC-SHA256 encodé en base64 du txid du payload — pour que vous puissiez vérifier l'expéditeur. Les livraisons échouées atterrissent dans une liste de notifications échouées, et POST /api/v2/tron/webhooks/notifications/{id}/retry en renvoie n'importe laquelle.

GET /api/v2/tron/webhooks/notifications retourne les notifications passées, pratique quand vous devez rejouer des événements après un mauvais déploiement. La configuration prend quelques minutes avec le guide des webhooks.

Les expéditeurs à haut volume ne devraient pas brûler du TRX indéfiniment. Gelez du TRX via POST /api/v2/tron/freeze et le réseau accorde du Bandwidth ou de l'Energy en retour ; routez ces ressources vers votre hot wallet avec POST /api/v2/tron/delegate. Unfreeze et undelegate inversent les deux étapes quand vous voulez récupérer le capital.

Les prix actuels des ressources proviennent de GET /api/v2/tron/chainparameters. Depuis la proposition #104, le prix unitaire de l'Energy est de 100 Sun, réduit depuis 210, ce qui a changé le point d'équilibre entre staking et combustion. Vérifiez la valeur en direct avant de dimensionner un stake.

L'arithmétique favorise le staking à mesure que le volume croît, car le TRX brûlé a disparu tandis que le TRX staké est simplement garé. Comme chiffre approximatif de mi-2026, un stake de l'ordre de 5 000 TRX générait environ l'Energy d'un transfert USDT par jour. Une entreprise envoyant 50 transferts par jour aurait besoin d'un stake dans les basses centaines de milliers de TRX pour couvrir entièrement son Energy par le staking. Traitez ces chiffres comme des ordres de grandeur plutôt que des devis : votre rendement quotidien dépend de la quantité de TRX que tout le réseau a staké, et ce ratio dérive. Le calculateur de frais et l'endpoint des paramètres de chaîne vous donnent les entrées d'aujourd'hui pour le calcul.

La délégation est ce qui rend le staking opérationnellement propre. Gardez le stake sur une adresse de trésorerie qui ne touche jamais le trafic client, puis delegatez son Energy vers les hot wallets qui font les envois réels. Quand un wallet est retiré, undelegatez et pointez les ressources vers son successeur ; le TRX staké lui-même ne bouge jamais. Une mise en garde pour la planification de trésorerie : après le unfreeze, le TRX reste verrouillé pour une période d'attente d'environ deux semaines avant d'être à nouveau dépensable, donc un stake n'est pas une réserve à accès instantané. Dimensionnez-le à partir du volume en régime permanent et couvrez les pics avec de l'Energy louée à la place.

Chaingateway supporte les types de tokens standards sur TRON. USDT, USDC et DAI fonctionnent d'emblée avec une gestion automatique des décimales. Pour un token que vous avez lancé vous-même, passez son adresse de contrat et l'API le traite comme n'importe quel autre TRC-20. Le schéma de requête est partagé entre les chaînes, donc l'appel ERC-20 sur Ethereum, BNB Smart Chain, Polygon ou Arbitrum ressemble exactement à votre appel TRC-20, avec un segment de chemin différent.

Le réseau est conçu pour environ 2 000 transactions par seconde, ce qui convient aux charges de travail de paiement composées de nombreux petits transferts. Les frais restent assez bas pour que les micropaiements demeurent viables, quelques TRX par transfert de token plutôt que des frais qui dévorent le paiement. TRON détient une part plus grande de l'USDT en circulation que toute autre chaîne, donc les contreparties de vos utilisateurs y sont déjà, et l'écosystème de wallets autour du TRC-20 est assez mature pour que l'outillage se mette rarement en travers.

Les intégrations typiques ressemblent à ceci : un flux de checkout qui accepte l'USDT et crédite la commande après confirmation ; un backend de plateforme d'échange qui surveille des milliers d'adresses de dépôt et traite les retraits depuis un hot wallet ; des systèmes de paiement sortant qui exécutent des airdrops ou des calendriers de vesting ; une facturation d'abonnement qui prélève en stablecoins chaque mois ; des services d'envoi de fonds qui déplacent de la valeur à travers les frontières en quelques minutes. La même API couvre chaque schéma. Ce qui change, c'est quels endpoints vous combinez.

Chaque endpoint de cette page accepte l'en-tête X-Network: testnet. Avec lui, la requête identique tourne contre le testnet TRON : mêmes chemins, mêmes payloads, mêmes formes de réponse. Le TRX de test est gratuit via des faucets publics, donc une répétition complète ne coûte rien — créer une adresse de dépôt, y envoyer un transfert TRC-20, recevoir le webhook, vérifier la signature HMAC, balayer vers un hot wallet.

Répétez le chemin webhook au moins une fois de bout en bout. Les erreurs d'intégration classiques, une vérification de signature contre le mauvais encodage de payload ou un pare-feu qui abandonne silencieusement la livraison, apparaissent sur testnet exactement comme elles le feraient en production, où elles coûtent de vrais dépôts au lieu de tokens de test. Passer en production ensuite consiste à supprimer un en-tête ; le quickstart montre le cycle complet.

Deux classes d'échec veulent un traitement opposé. Une réponse 4xx signifie que la requête elle-même est erronée : un jeton Bearer manquant ou expiré, une adresse malformée, un montant que le wallet expéditeur ne peut couvrir. Loguez-la et corrigez la cause, mais ne réessayez pas sans changement, car une entrée identique produit un rejet identique. Une réponse 5xx ou un timeout réseau ne dit rien sur votre entrée ; réessayez ceux-ci avec un backoff exponentiel et un plafond.

Le cas limite qui mérite d'être conçu est le timeout après un envoi. Votre client HTTP a abandonné, pourtant la transaction a peut-être quand même été diffusée. Retirer le même transfert par réflexe est ainsi que des paiements en double se produisent. Vérifiez d'abord ce qui est réellement sorti : GET /api/v2/tron/transactions liste les transferts créés via votre compte. Renvoyez seulement si la première tentative a manifestement échoué. Pour les échecs liés aux frais, il existe un schéma encore moins coûteux : vérifiez GET /api/v2/tron/chainparameters et les ressources du wallet avant d'envoyer, transformant une erreur d'exécution en une vérification préalable.