Créer des transactions de token TRC20 sur TRON

Introduction

Ce tutoriel couvre les endpoints TRC20 de l’API Chaingateway V2 : créer une adresse TRON, lire un contrat de token, vérifier le solde d’un token et envoyer un transfert TRC20. Les exemples sont donnés en Shell (cURL), PHP (Guzzle), Python (Requests) et JavaScript (Axios).

Pour obtenir une clé API et en savoir plus sur l’autorisation, consultez la section Démarrage rapide de la documentation Chaingateway.

Ce que l’API fait et ne fait pas

L’API ne propose aucun endpoint permettant de compiler ou de déployer un smart contract. Aucune route ne publie un nouveau contrat TRC20 sur le réseau TRON, et aucun des endpoints TRON n’accepte de bytecode de contrat. Chaque route TRC20 prend en paramètre un contractaddress d’un token qui existe déjà sur la chaîne, que ce soit l’USDT ou tout autre token TRC20.

Si vous cherchez un moyen de déployer votre propre contrat de token, cette API n’est pas l’outil adapté à cette étape. Une fois le contrat déployé, les endpoints ci-dessous couvrent la partie dont la plupart des intégrations ont réellement besoin : adresses, soldes, transferts et notifications.

Ce que vous voulez faire	Endpoint
Créer une adresse TRON	POST /v2/tron/addresses
Importer une clé privée existante	POST /v2/tron/addresses/import
Lire le nom, le symbole, les décimales et le supply	GET /v2/tron/trc20/{contract_address}
Lire le solde d’un token	GET /v2/tron/balances/{address}/trc20/{contract_address}
Envoyer un transfert TRC20	POST /v2/tron/transactions/trc20
Construire un transfert sans le diffuser	POST /v2/tron/transactions/trc20/build
Diffuser une transaction que vous avez signée	POST /v2/tron/transactions/broadcast
Être notifié des tokens entrants	POST /v2/tron/webhooks

Étape 1 : créer une adresse TRON

L’adresse expéditrice doit être connue de Chaingateway. Créez-la via l’API ou importez une clé privée existante via POST /v2/tron/addresses/import.

Si vous transmettez un password, la clé privée est stockée chiffrée et vous signez les transactions ultérieures avec ce mot de passe. Si vous omettez le mot de passe, la réponse contient la clé privée elle-même et vous devez l’envoyer avec chaque requête de transaction. L’approche par mot de passe est décrite en détail dans Gestion des wallets.

curl

curl --request POST\
    --url https://api.chaingateway.io/v2/tron/addresses\
    --header 'Accept: application/json'\
    --header 'content-type: application/json'\
    --header 'Authorization: YOUR_API_TOKEN'\
    --data '{"password":"test123"}'

Python

import requests

url = "https://api.chaingateway.io/v2/tron/addresses"
payload = {"password": "test123"}
headers = {
    'Accept': 'application/json',
    'content-type': 'application/json',
    'Authorization': 'YOUR_API_TOKEN'
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

JavaScript

const axios = require('axios');

const url = 'https://api.chaingateway.io/v2/tron/addresses';
const payload = { password: 'test123' };
const headers = {
  'Accept': 'application/json',
  'content-type': 'application/json',
  'Authorization': 'YOUR_API_TOKEN'
};

axios.post(url, payload, { headers })
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error(error);
  });

PHP

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();
$response = $client->post('https://api.chaingateway.io/v2/tron/addresses', [
    'headers' => [
        'Accept' => 'application/json',
        'content-type' => 'application/json',
        'Authorization' => 'YOUR_API_TOKEN',
    ],
    'json' => [
        'password' => 'test123'
    ]
]);

echo $response->getBody();
?>

La réponse contient la nouvelle adresse :

{
  "status": 201,
  "ok": true,
  "message": "Address created",
  "data": [
    {
      "privateKey": "59f1c6200e01a2ca9471411f10198bfa63678d0e87cc2ca30f9c4a68dee78edc",
      "publicKey": "040fe6e677442c36f7fdd5535ba3ff1cef0110d78363420f7e24b65298990e3467aed68b9a67e1396d84753db25b32a2fa3e1fc0a673f01638e9bcfab2d8f4ceb5",
      "hexAddress": "41a56a6505ffbee78eb916dd44f4846874deddaebd",
      "address": "TR3qx91smURF3R455V1ubqtoUsZbgqikfg"
    }
  ]
}

Chaingateway ne stocke pas les mots de passe. Un mot de passe perdu signifie un wallet perdu.

Étape 2 : lire le contrat du token

Avant de déplacer un token, lisez son contrat. La valeur decimals est celle dont vous aurez le plus souvent besoin, car elle indique comment le solde brut on-chain se convertit en montant affiché à l’utilisateur.

curl --request GET\
    --url https://api.chaingateway.io/v2/tron/trc20/TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t\
    --header 'Accept: application/json'\
    --header 'Authorization: YOUR_API_TOKEN'

{
  "status": 200,
  "ok": true,
  "message": "TRC20 contract fetched",
  "data": {
    "address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "symbol": "USDT",
    "name": "TetherUSD",
    "totalSupply": "61742996582033118",
    "decimals": "6"
  }
}

Un contrat inconnu ou non-TRC20 répond avec le statut 400 et le message Error fetching TRC20 contract.

Étape 3 : vérifier le solde du token

curl --request GET\
    --url https://api.chaingateway.io/v2/tron/balances/TVF2Mp9QY7FEGTnr3DBpFLobA6jguHyMvi/trc20/TXLAQ63Xg1NAzckPwKHvzw7CSEmLMEqcdj\
    --header 'Accept: application/json'\
    --header 'Authorization: YOUR_API_TOKEN'

{
  "status": 200,
  "ok": true,
  "message": "TRC20 balance fetched",
  "data": {
    "tronaddress": "TVF2Mp9QY7FEGTnr3DBpFLobA6jguHyMvi",
    "decimals": 6,
    "balance": "1000000000000000000",
    "contractaddress": "TXLAQ63Xg1NAzckPwKHvzw7CSEmLMEqcdj"
  }
}

Le champ balance est la valeur entière brute. Divisez-la par 10 à la puissance decimals pour obtenir le montant lisible par un humain.

Étape 4 : envoyer le transfert TRC20

POST /v2/tron/transactions/trc20 requiert from, to, contractaddress et amount. Pour la signature, ajoutez soit password, si l’adresse a été créée avec un mot de passe, soit privatekey pour une adresse non sécurisée ou importée.

Paramètres

• from : l’adresse TRON de l’expéditeur.
• to : l’adresse TRON du destinataire.
• contractaddress : l’adresse du contrat du token.
• amount : le montant à envoyer.
• password : le mot de passe d’une adresse Chaingateway protégée par mot de passe. Requis lorsque privatekey n’est pas présent.
• privatekey : la clé privée de l’expéditeur, pour les adresses créées ou importées sans mot de passe.

curl

curl --request POST\
  --url https://api.chaingateway.io/v2/tron/transactions/trc20\
  --header 'Accept: application/json'\
  --header 'content-type: application/json'\
  --header 'Authorization: YOUR_API_TOKEN'\
  --data '{
    "from": "TLkkCeNdJKPNUwucdro84WjswkzM62LCTH",
    "to": "TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp",
    "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "amount": 1,
    "password": "test123"
}'

Python

import requests

url = "https://api.chaingateway.io/v2/tron/transactions/trc20"
payload = {
    "from": "TLkkCeNdJKPNUwucdro84WjswkzM62LCTH",
    "to": "TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp",
    "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "amount": 1,
    "password": "test123"
}
headers = {
    'Accept': 'application/json',
    'content-type': 'application/json',
    'Authorization': 'YOUR_API_TOKEN'
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

JavaScript

const axios = require('axios');

const url = 'https://api.chaingateway.io/v2/tron/transactions/trc20';
const payload = {
  from: 'TLkkCeNdJKPNUwucdro84WjswkzM62LCTH',
  to: 'TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp',
  contractaddress: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t',
  amount: 1,
  password: 'test123'
};
const headers = {
  'Accept': 'application/json',
  'content-type': 'application/json',
  'Authorization': 'YOUR_API_TOKEN'
};

axios.post(url, payload, { headers })
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error(error);
  });

PHP

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();
$response = $client->post('https://api.chaingateway.io/v2/tron/transactions/trc20', [
    'headers' => [
        'Accept' => 'application/json',
        'content-type' => 'application/json',
        'Authorization' => 'YOUR_API_TOKEN',
    ],
    'json' => [
        'from' => 'TLkkCeNdJKPNUwucdro84WjswkzM62LCTH',
        'to' => 'TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp',
        'contractaddress' => 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t',
        'amount' => 1,
        'password' => 'test123'
    ]
]);

echo $response->getBody();
?>

Un appel réussi renvoie le hash de la transaction :

{
  "status": 201,
  "ok": true,
  "message": "Succesfully created transaction",
  "data": {
    "txid": "0x73344d178812d4919e9002c560781f288030edf72ece88823ef1c377dfb71f27"
  }
}

Deux erreurs reviennent avec le statut 422 et méritent d’être traitées séparément. balance is not sufficient signifie que l’adresse expéditrice ne peut pas payer la transaction. Un message Validate signature error signifie que la clé ou le mot de passe ne correspondait pas à l’adresse from.

Le wallet expéditeur a besoin de TRX

Un transfert TRC20 est un appel de smart contract, et TRON facture de l’energy et du bandwidth pour cela. Une adresse qui ne détient que des tokens ne peut pas les envoyer. Soit vous approvisionnez l’adresse en TRX, soit vous stakez pour obtenir des ressources via POST /v2/tron/freeze et POST /v2/tron/delegate, soit vous faites sponsoriser les frais. La sponsorisation des frais est décrite dans Sponsoriser les frais TRC20.

Signer la transaction vous-même

Si vous préférez garder la clé privée hors de la requête, séparez le transfert en deux appels. POST /v2/tron/transactions/trc20/build renvoie l’hexadécimal brut de la transaction sans la diffuser. Vous signez cet hexadécimal dans votre propre code et transmettez la transaction signée à POST /v2/tron/transactions/broadcast.

curl --request POST\
  --url https://api.chaingateway.io/v2/tron/transactions/trc20/build\
  --header 'Accept: application/json'\
  --header 'content-type: application/json'\
  --header 'Authorization: YOUR_API_TOKEN'\
  --data '{
    "from": "TLkkCeNdJKPNUwucdro84WjswkzM62LCTH",
    "to": "TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp",
    "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "amount": 1
}'

La réponse contient raw_data et raw_data_hex. Rien n’a encore atteint le réseau à ce stade.

Être notifié des tokens entrants

Pour être informé d’un dépôt TRC20 sans faire de polling, souscrivez un webhook avec type défini sur TRC20 et le contractaddress du token. Les filtres from et to permettent de restreindre la surveillance à une seule adresse.

curl --request POST\
  --url https://api.chaingateway.io/v2/tron/webhooks\
  --header 'Accept: application/json'\
  --header 'content-type: application/json'\
  --header 'Authorization: YOUR_API_TOKEN'\
  --data '{
    "url": "https://example.com/webhook-receiver",
    "type": "TRC20",
    "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "to": "TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp"
}'

La mise en place du côté récepteur est couverte dans Créer des webhooks, et la vérification qu’une notification provient bien de Chaingateway dans Sécuriser les webhooks.

Une notification que votre serveur n’a pas acceptée n’est pas renvoyée automatiquement. Les notifications échouées sont listées sous GET /v2/tron/webhooks/notifications/failed et peuvent être redéclenchées avec POST /v2/tron/webhooks/notifications/{id}/retry.

Tester sur Nile

Tous les appels ci-dessus fonctionnent sur le testnet TRON Nile. Ajoutez l’en-tête X-Network: testnet et utilisez des tokens de test plutôt que des contrats mainnet. La liste des réseaux est documentée dans Réseaux pris en charge.