Aller au contenu

Frais TRC20 : TronFuel, Paymaster

Prendre en charge les frais signifie qu’un tiers paie l’energy et la bande passante d’une transaction TRON, le wallet émetteur n’a donc pas besoin de TRX. Nous recommandons TronFuel pour cela. Le Paymaster de Chaingateway remplissait la même fonction dans l’API et est obsolète : les intégrations existantes continuent de fonctionner, mais les nouvelles ne doivent pas l’utiliser.

Options pour envoyer des tokens TRC20 depuis une adresse sans TRX : louer de l'energy avec TronFuel, staker des TRX et déléguer des ressources, ou utiliser le Paymaster obsolète Transfert TRC20 depuis une adresse sansTRX échoue avec le statut 422, balance is notsufficient Recommandé : TronFuel loue de l'energy, service distinct Alternative : staker et déléguer POST /api/v2/tron/freeze et /delegate Obsolète : endpoints Paymaster uniquement pour les intégrations existantes
Pour les nouvelles intégrations, choisissez la deuxième ou la troisième option.

Pourquoi un wallet TRON avec des tokens mais sans TRX ne peut-il pas les envoyer ?

Section intitulée « Pourquoi un wallet TRON avec des tokens mais sans TRX ne peut-il pas les envoyer ? »

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

Il en résulte une situation que toute intégration TRON rencontre tôt ou tard. Un client dépose des USDT sur une adresse fraîchement créée. L’adresse contient alors des tokens et rien d’autre. Envoyer ces tokens plus loin é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 en ressources. Approvisionner d’avance chaque adresse de dépôt en TRX fonctionne, mais immobilise des TRX dans des adresses qui ne serviront peut-être jamais.

La prise en charge des frais règle cela de l’autre côté. Un tiers paie le coût en ressources, et le wallet envoie ses tokens sans jamais détenir de TRX.

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 Frais de transaction TRC-20 sur TRON expliqués.

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

Le Paymaster de Chaingateway remplissait la même fonction dans l’API : il couvrait la bande passante et l’energy, de sorte qu’un wallet n’avait pas besoin de TRX pour envoyer des tokens TRC20. Il imputait le coût sur un solde de crédit de votre compte.

Le service est obsolète. 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.

EndpointUsage
POST /api/v2/tron/paymasterCréer une demande de transaction prise en charge
GET /api/v2/tron/paymasterLister vos demandes et leur statut
GET /api/v2/tron/paymaster/{id}Lire une demande
POST /api/v2/tron/paymaster/estimateEstimer l’energy, la bande passante et les frais
GET /api/v2/tron/paymaster/balanceLire votre solde de crédit restant

L’energy et la bande passante dont une transaction a besoin dépendent du type de transaction et du contrat appelé, le montant n’est donc pas fixe. POST /api/v2/tron/paymaster/estimate prend le même corps que la demande elle-même et renvoie ce que coûterait la transaction.

Fenêtre de terminal
curl --request POST\
--url https://app.chaingateway.io/api/v2/tron/paymaster/estimate\
--header 'Accept: application/json'\
--header 'Content-Type: application/json'\
--header 'Authorization: Bearer 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 qui ne les couvre pas fait échouer la demande. GET /api/v2/tron/paymaster/balance renvoie ce qui reste.

type accepte TRX, TRC10, TRC20 et TRC721. Avec from, to et amount, il est obligatoire. Pour TRC20 et TRC721, vous passez 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 facultatif reçoit le résultat.

Fenêtre de terminal
curl --request POST\
--url https://app.chaingateway.io/api/v2/tron/paymaster\
--header 'Accept: application/json'\
--header 'Content-Type: application/json'\
--header 'Authorization: Bearer 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’identifiant de la demande :

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

Interrogez GET /api/v2/tron/paymaster/{id} avec cet identifiant, ou listez toutes les demandes avec GET /api/v2/tron/paymaster. Le champ status passe par pending pendant que la demande attend, processing pendant que la transaction est en route, et completed une fois réglée. Un échec s’écrit failed - [reason], avec la raison détaillée après le tiret. Le hash de la transaction résultante 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"
}

Puis-je staker des TRX plutôt que payer à chaque transaction ?

Section intitulée « Puis-je staker des TRX plutôt que payer à chaque transaction ? »

Si les TRX vous appartiennent de toute façon, vous pouvez les staker une fois et réutiliser les ressources au lieu de payer à chaque transaction. POST /api/v2/tron/freeze stake des TRX pour de l’energy ou de la bande passante. POST /api/v2/tron/delegate transmet ces ressources à une autre adresse. POST /api/v2/tron/undelegate et POST /api/v2/tron/unfreeze annulent ces deux étapes. Une seule adresse stakée peut alimenter les adresses de dépôt qui en dépendent, ce qui convient à un flux de paiement avec de nombreuses adresses de réception.

Les quatre endpoints de staking partagent la même forme de corps. Les champs address, amount et resource sont obligatoires, et resource vaut BANDWIDTH ou ENERGY. delegate et undelegate ajoutent un receiver obligatoire. Comme partout dans l’API, vous signez avec password ou privatekey.

Fenêtre de terminal
curl --request POST\
--url https://app.chaingateway.io/api/v2/tron/freeze\
--header 'Accept: application/json'\
--header 'Content-Type: application/json'\
--header 'Authorization: Bearer YOUR_API_TOKEN'\
--data '{
"address": "TLkkCeNdJKPNUwucdro84WjswkzM62LCTH",
"amount": 100,
"resource": "ENERGY",
"password": "test123"
}'

Un appel réussi renvoie data.result: true et le txid de la transaction de staking. Deux règles du fichier OpenAPI valent pour la délégation : le solde doit être gelé avant de pouvoir être délégué, et le receveur doit différer de l’adresse propriétaire. Un appel échoué renvoie le statut 422 avec le message du nœud. Exemples : no frozenBalance(Energy) si vous dégelez plus que vous n’avez staké, ou delegated Resource does not exist si vous retirez une délégation qui n’a jamais existé. Le modèle de ressources de TRON documente comment les TRX stakés se transforment en energy et en bande passante.

Le tableau compare les options selon ce qu’il faut et ce qu’elles coûtent.

OptionCe qu’il fautModèle de coûtStatut
Approvisionner chaque adresse en TRXdes TRX dans chaque adresse de dépôtles TRX sont brûlés à chaque transactionfonctionne, immobilise des TRX
TronFuelle service distinct TronFuel, hors de l’API Chaingatewayl’energy est louée au lieu de brûler des TRXrecommandé
Staker et déléguerdes TRX que vous pouvez bloquerles TRX stakés fournissent les ressources au lieu d’être brûlésfonctionne
Paymasterun solde de crédit sur votre compte Chaingatewayfrais déduits du solde de créditobsolète

Vérifiez le solde TRX d’une adresse avec GET /api/v2/tron/balances/{address} avant d’envoyer. Une adresse sans TRX et sans ressources déléguées échoue avec le message balance is not sufficient vu plus haut.

L’envoi du transfert lui-même est traité dans Transactions de tokens TRC20 sur TRON.