Frais TRC20 : TronFuel et Paymaster

Le problème : des tokens sans TRX ne peuvent pas bouger

Un transfert TRC20 est un appel de smart contract. TRON facture de l’energy et du bandwidth pour cela, et une adresse paie ces ressources soit en brûlant du TRX, soit en utilisant des ressources qu’elle a stakées ou qui lui ont été déléguées. Le token lui-même ne paie jamais.

Cela produit une situation que toute intégration TRON rencontre tôt ou tard. Un client dépose de l’USDT sur une adresse fraîchement créée. Cette adresse détient désormais des tokens et rien d’autre. Envoyer ces tokens à leur tour échoue avec le statut 422 et le message balance is not sufficient, car il n’y a pas de TRX pour couvrir le coût des ressources. Approvisionner à l’avance chaque adresse de dépôt en TRX fonctionne, mais cela immobilise du TRX dans des adresses qui ne serviront peut-être jamais.

Sponsoriser les frais résout le problème depuis l’autre côté. Un tiers paie le coût des ressources, et le wallet envoie ses tokens sans jamais détenir de TRX.

TronFuel est la méthode recommandée

TronFuel est ce que nous recommandons aujourd’hui pour cela. Le service loue de l’energy en gros auprès de stakers plutôt que de brûler du TRX, ce qui est la source de l’économie par rapport à un simple brûlage. Le contexte est détaillé dans Économisez jusqu’à 60 % sur les frais de transaction TRC-20 sur TRON.

TronFuel est un service distinct. Il n’a aucun endpoint au sein de l’API Chaingateway, et cette documentation ne décrit donc pas comment l’appeler. Suivez le lien ci-dessus pour sa propre documentation.

Le Paymaster est abandonné

Le Paymaster de Chaingateway remplissait la même fonction au sein de l’API : il couvrait le bandwidth et l’energy pour qu’un wallet n’ait pas besoin de TRX avant d’envoyer des tokens TRC20, et il facturait le coût sur un solde de crédit de votre compte.

Ce service est abandonné (deprecated). Les intégrations qui appellent déjà les endpoints Paymaster continuent de fonctionner, et les endpoints sont documentés ci-dessous pour cette raison. Ne construisez pas de nouvelles intégrations dessus.

Endpoint	Fonction
POST /v2/tron/paymaster	Créer une demande de transaction sponsorisée
GET /v2/tron/paymaster	Lister vos demandes et leur statut
GET /v2/tron/paymaster/{id}	Lire une demande
POST /v2/tron/paymaster/estimate	Estimer l’energy, le bandwidth et les frais
GET /v2/tron/paymaster/balance	Lire votre solde de crédit restant

Estimer d’abord le coût

La quantité d’energy et de bandwidth dont une transaction a besoin dépend du type de transaction et du contrat qu’elle appelle ; ce montant n’est donc pas fixe. POST /v2/tron/paymaster/estimate prend le même corps que la demande elle-même et renvoie ce que la transaction coûterait.

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

{
  "status": 200,
  "ok": true,
  "message": "Successfully estimated the fees",
  "data": {
    "energy_consumption": 32000,
    "bandwidth_consumption": 368,
    "paymaster_fee": 0.15
  }
}

Les frais sont déduits du solde de crédit une fois la demande réglée. Un solde insuffisant fait échouer la demande. GET /v2/tron/paymaster/balance renvoie ce qu’il en reste.

Créer une demande sponsorisée

type accepte TRX, TRC10, TRC20 et TRC721. Avec from, to et amount, ce champ est requis. Pour TRC20 et TRC721, ajoutez aussi contractaddress, et pour TRC721 et TRC10, le tokenid. La signature fonctionne comme partout ailleurs dans l’API : password pour une adresse Chaingateway protégée par mot de passe, privatekey sinon. Un callback_url optionnel reçoit le résultat.

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

La réponse n’est pas un hash de transaction mais l’id de la demande :

{
  "status": 200,
  "ok": true,
  "message": "Successfully created paymaster request",
  "data": {
    "id": "9c72d676-8180-4cd2-a406-f0f1cd097506"
  }
}

Suivre une demande

Interrogez GET /v2/tron/paymaster/{id} avec cet id, ou listez toutes vos demandes avec GET /v2/tron/paymaster. Le champ status passe par pending pendant que la demande attend, processing pendant que la transaction est en cours, et completed une fois qu’elle est réglée. Un échec se lit failed - [reason], avec la raison précisée après le tiret. Le hash de transaction résultant apparaît dans l’enregistrement une fois la transaction terminée.

{
  "id": "9cfbfcaf-68b2-47e9-bf55-5b6b4875e84d",
  "type": "TRC20",
  "from": "THG9nncwASg3ub5rvVquocAHwwQbnKZxpH",
  "to": "TPUjdnMrS7XDUFp5W6zgh4QDCW34nXa2x1",
  "contract_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "amount": "200",
  "token_id": null,
  "transaction_hash": "80a223e0cb20ef692fbd23d3cbaf3cc1dfa2b9667aaef70c7da8ca8f707ec28b",
  "status": "success",
  "used_credits": "2.178413",
  "callback_url": "https://api.chaingateway.io/receiver/webhooks/tron",
  "created_at": "2024-09-11T15:28:57.000000Z"
}

Le staking comme troisième option

Si le TRX vous appartient de toute façon, vous pouvez le staker une fois et réutiliser les ressources au lieu de payer à chaque transaction. POST /v2/tron/freeze stake du TRX pour de l’energy ou du bandwidth, POST /v2/tron/delegate transmet ces ressources à une autre adresse, et POST /v2/tron/undelegate ainsi que POST /v2/tron/unfreeze inversent les deux étapes. Une seule adresse stakée peut alimenter les adresses de dépôt qui en dépendent, ce qui correspond au schéma adapté à un flux de paiement comptant de nombreuses adresses réceptrices.

L’envoi du transfert lui-même est couvert dans Créer des transactions de token TRC20.