API d'adresse TRC20 : générer des adresses et les surveiller pour les dépôts
Une adresse TRC20 est une adresse de compte TRON standard : 34 caractères en Base58Check, commençant par T. Elle détient du TRX et tous les tokens TRC-20 comme l'USDT. La même adresse a une écriture hexadécimale de 42 caractères qui commence par 41. Envoyer depuis elle consomme de l'Energy et de la Bandwidth, alors que recevoir est gratuit.
Pour générer une adresse TRC20 via une API, appelez POST /api/v2/tron/addresses. La réponse est une adresse Base58Check qui commence par T. Un webhook enregistré avec POST /api/v2/tron/webhooks signale ensuite chaque dépôt USDT-TRC20 reçu. Cette page explique d'abord le format, puis la création, la surveillance et l'envoi, avec les endpoints et les corps de requête.
Tout ce qui suit s'exécute sur https://app.chaingateway.io avec un token Bearer dans l'en-tête Authorization. L'en-tête X-Network: testnet, ajouté à n'importe quel appel, le fait passer sur le testnet TRON : tout le flux peut donc être répété avec des TRX de test gratuits. Pour une explication plus longue du format, lisez Qu'est-ce qu'une adresse TRC20 ? sur le blog.
À quoi ressemble une adresse TRC20 ?
Une adresse TRC20 est l'adresse d'un compte TRON sous sa forme Base58Check, par exemple TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL. Elle compte 34 caractères et commence par T. La documentation des comptes de TRON définit la valeur sous-jacente comme 21 octets : un octet de préfixe 0x41, puis 20 octets identiques à l'adresse Ethereum dérivée de la même clé publique.
La même adresse a donc une écriture hexadécimale de 42 caractères qui commence par 41. Les API de nodes renvoient souvent cette forme, tandis que les wallets et les explorateurs affichent la forme Base58Check. TronWeb convertit de l'une à l'autre avec tronWeb.address.toHex() et fromHex().
« TRC20 » désigne le standard de token, pas l'adresse. TRC-20 est le standard de tokens fongibles de TRON, compatible avec l'ERC-20 d'Ethereum au niveau de l'interface. Une adresse TRON détient du TRX et tous les tokens TRC-20.
- La forme Base58Check affichée dans les wallets et les explorateurs : 34 caractères, commençant par T.
- L'octet de préfixe 41 indique que la valeur est une adresse TRON.
- Les 20 octets restants sont identiques à l'adresse Ethereum dérivée de la même clé publique.
- La forme hexadécimale : 42 caractères au total, telle que la renvoient beaucoup d'API de nodes.
Une adresse TRC20 est-elle la même chose que l'adresse d'un contrat TRC20 ?
Non. Une adresse de wallet est un compte contrôlé par une clé privée. L'adresse d'un contrat appartient à du code déployé, et personne n'en détient la clé. La documentation de TRON présente les deux comme des types de compte, et les deux s'écrivent en chaînes T, donc rien dans la chaîne ne les distingue.
L'adresse du contrat indique quel token circule. Elle n'est jamais la destination d'un transfert. Le contrat TRC-20 de l'USDT est TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t, et des tokens envoyés à une adresse de contrat sont, dans presque tous les cas, irrécupérables. Le guide du blog explique la différence plus en détail.
Pourquoi une nouvelle adresse TRC20 n'apparaît-elle pas sur Tronscan ?
Parce que TRON ne reconnaît un compte qu'après son activation. D'après la documentation des comptes de TRON, une paire de clés fraîchement générée existe en local, mais l'adresse ne peut pas être consultée via l'API ni dans un explorateur de blocs tant qu'elle n'est pas activée.
L'activation a lieu quand un compte existant envoie à la nouvelle adresse un montant quelconque de TRX ou d'un token TRC-10, et que l'expéditeur paie des frais de création de compte. La documentation indique ces frais à 1 TRX sur le mainnet au moment de la rédaction, vérifiez donc la valeur actuelle avant de bâtir un flux de paiement dessus. Une adresse générée convient pour les dépôts et les webhooks, mais n'attendez pas d'un explorateur qu'il l'affiche avant sa première activation.
Endpoints d'adresse TRC20 : créer, lire, surveiller, envoyer
Quatre tâches, et les routes qui les réalisent. La création d'adresse et l'enregistrement de webhook ne demandent aucune clé privée. Seul l'envoi en demande une.
| Endpoint | Ce qu'il fait |
|---|---|
POST /api/v2/tron/addresses | Générer une nouvelle adresse TRON |
POST /api/v2/tron/addresses/import | Importer une clé privée existante pour que l'API puisse signer pour cette adresse |
POST /api/v2/tron/addresses/{address} | Changer le mot de passe qui chiffre une clé enregistrée |
DELETE /api/v2/tron/addresses/{address} | Retirer une adresse de votre compte |
GET /api/v2/tron/balances/{address} | Solde en TRX de l'adresse |
GET /api/v2/tron/balances/{address}/trc20/{contract_address} | Solde d'un token TRC-20, USDT compris |
GET /api/v2/tron/balances/{address}/trc10/{token_id} | Solde d'un token TRC-10 |
POST /api/v2/tron/webhooks | S'abonner aux transferts de TRX, TRC-10, TRC-20 ou TRC-721 pour l'adresse |
GET /api/v2/tron/webhooks/notifications | Lister les notifications déjà livrées, pour la réconciliation |
POST /api/v2/tron/transactions/trc20 | Envoyer un token TRC-20 comme l'USDT depuis l'adresse |
C'est toute la surface qu'un système de dépôt utilise. La référence TRON complète, soit 40 opérations dont le staking et la signature locale, se trouve sur la page API TRON. Le champ type d'un webhook et la route distincte /transactions/trc10 existent parce que TRON porte deux standards de token. La comparaison TRC10 vs TRC20 indique lequel choisir si vous lancez un token plutôt que d'en accepter un existant.
Comment générer une adresse TRC20 en REST ?
POST /api/v2/tron/addresses en crée une. Le corps accepte un seul champ facultatif, password, et ce champ détermine le modèle de garde. Si vous envoyez un mot de passe, la clé privée est stockée chiffrée derrière lui, et les transferts suivants s'authentifient avec le mot de passe plutôt qu'avec la clé. Si vous l'omettez, la réponse vous remet directement la clé privée, à ranger dans votre propre coffre. La référence est explicite : les mots de passe ne sont pas stockés, et si vous le perdez, le wallet ne peut pas être restauré. Personne d'autre ne peut non plus le déverrouiller.
curl -X POST https://app.chaingateway.io/api/v2/tron/addresses \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"password": "a-strong-password-per-wallet"}'
Si votre plateforme génère déjà ses clés elle-même, la seconde route convient mieux : POST /api/v2/tron/addresses/import enregistre une adresse dérivée ailleurs, avec sa clé privée et un mot de passe de chiffrement, et l'API peut ensuite signer pour elle. Les adresses que vous voulez seulement surveiller n'ont besoin d'aucun de ces appels, car un abonnement webhook référence une adresse par sa chaîne.
Deux routes d'entretien complètent l'ensemble. POST /api/v2/tron/addresses/{address} change le mot de passe de chiffrement d'une clé enregistrée. DELETE /api/v2/tron/addresses/{address} retire l'adresse de votre compte, ce qui, selon la référence, réduit aussi le nombre d'adresses utilisées. Branchez-la sur la tâche qui retire les adresses de dépôt expirées si vous êtes proche de la limite de votre plan.
Comment surveiller une adresse TRC20 pour les USDT entrants ?
Interroger Tronscan pour détecter les dépôts est la version qui casse en silence. POST /api/v2/tron/webhooks est la version qui passe à l'échelle. url est le seul champ que la référence marque comme obligatoire. to restreint l'abonnement aux dépôts sur votre adresse, from aux transferts qui en sortent, et contractaddress à un seul token. type choisit la classe d'actif et accepte TRX, TRC10, TRC20 ou TRC721. reference contient jusqu'à 255 caractères de votre texte : c'est là que va l'identifiant de commande ou de client, pour que la notification arrive avec votre clé de recherche.
curl -X POST https://app.chaingateway.io/api/v2/tron/webhooks \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-backend.example/hooks/tron",
"to": "TYourDepositAddress",
"type": "TRC20",
"contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"reference": "customer-4711"
}'
Définissez un secret personnel dans votre compte et chaque livraison porte un en-tête X-Signature, un HMAC-SHA256 encodé en base64 calculé sur le txid du payload. Vérifiez-le avant de lire quoi que ce soit d'autre. Rien ne renvoie de lui-même une livraison échouée. GET /api/v2/tron/webhooks/notifications/failed liste ce qui n'est jamais arrivé, et POST /api/v2/tron/webhooks/notifications/{id}/retry en renvoie une. Une entrée quitte la liste des échecs quand son renvoi démarre, et n'y revient que si ce renvoi échoue lui aussi.
Comme un renvoi livre le même événement une seconde fois, stockez le hash de transaction de chaque dépôt crédité sous une contrainte d'unicité et laissez la base rejeter le doublon. Le code de signature et la forme des payloads figurent dans le guide des webhooks.
Comment envoyer des USDT-TRC20 depuis l'adresse ?
POST /api/v2/tron/transactions/trc20 exige quatre champs : from, to, contractaddress et amount. Le montant est un nombre simple en unités de token, donc 25 USDT s'écrivent 25, et non une valeur multipliée par les six décimales du contrat. En plus, vous envoyez soit password, pour une clé que l'API conserve chiffrée, soit privatekey, si vous avez gardé la clé vous-même.
Le champ contractaddress transforme la distinction entre adresse de wallet et adresse de contrat en règle d'intégration concrète : l'adresse du contrat indique quel token circule, elle n'est jamais la destination. Celle de l'USDT est TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t, et elle va dans contractaddress, jamais dans to. Des tokens envoyés à une adresse de contrat sont, dans presque tous les cas, irrécupérables. Le guide du blog explique pourquoi les deux se ressemblent : ce sont deux chaînes T, et rien dans la chaîne ne les distingue.
L'envoi consomme de l'Energy et de la Bandwidth, alors que la réception est gratuite : un système de dépôt paie donc au balayage, pas au dépôt. Le calculateur de frais TRON chiffre un transfert précis, et GET /api/v2/tron/chainparameters renvoie les prix actuels des ressources, pour que votre code ne fige jamais une constante qu'un vote de gouvernance peut invalider.
Comment valider une adresse TRC20 avant d'envoyer ?
Vérifiez la destination dès que l'utilisateur la soumet, pas après la diffusion. Une adresse TRC-20 compte 34 caractères, commence par T et porte un checksum Base58Check qu'un seul caractère mal saisi invalide. On distingue donc une chaîne bien formée d'une faute de frappe sans toucher au réseau. Le validateur d'adresses exécute ce contrôle pour TRC-20, ERC-20 et BEP-20 dans le navigateur, quand vous voulez vérifier une adresse à la main.
Le contrôle ne risque pas de confondre par accident une adresse TRON et une adresse EVM, car les formats diffèrent à l'œil : une chaîne T échoue à la validation d'Ethereum, et une chaîne 0x échoue à celle de TRON. La TVM de TRON exécute une grande partie du Solidity écrit pour l'EVM, mais c'est un runtime distinct, avec sa propre mesure des ressources, Energy et Bandwidth à la place du gas, et son propre encodage d'adresse. Prendre « TRON EVM » au pied de la lettre est l'origine des bugs d'adresses entre chaînes.
Sources
Vous construisez un checkout ou un backend d'exchange qui demande des adresses TRC20 en volume ? Créez un compte gratuit et générez un lot sur testnet. Essai de 7 jours, sans carte, sans KYC.
FAQ : l'API d'adresse TRC20
Prêt à créer votre première adresse TRC20 ?
Créez un compte et générez dès aujourd'hui une adresse TRC20 de testnet. Essai de 7 jours, sans carte, sans KYC. La référence complète des endpoints se trouve sur la page API TRON, la question du format est traitée dans Qu'est-ce qu'une adresse TRC20 ?, et les sept chaînes passent par le même schéma dans l'API blockchain multi-chaînes.