Automatiser la location d’énergie TRON avec l’API

2026-05-13

Si vous exploitez un hot wallet, un moteur de retraits pour une plateforme d’échange ou un contrat qui déclenche des transferts TRC-20 pour le compte d’utilisateurs, vous connaissez le problème : l’énergie TRON doit être prête à la seconde où la transaction part. Recharger à la main dans une interface ne tient pas au-delà de quelques transferts par jour, et si vous ratez la fenêtre, la transaction brûle des TRX depuis l’adresse expéditrice, souvent bien plus cher que de l’énergie louée à l’avance.

La solution est d’appeler l’API de location au moment précis où votre backend s’apprête à diffuser une transaction, pour que l’énergie soit provisionnée par programme, sans intervention humaine. Voici comment faire avec tronenergyrent.com : la structure des requêtes, le cycle de vie asynchrone des commandes, le choix de la durée et un exemple Python que vous pouvez intégrer tel quel dans votre service.

Ce que l’API fait on-chain

Le modèle de ressources de TRON sépare le calcul (énergie) de la taille de la transaction (bandwidth). Un transfert USDT TRC-20 standard consomme environ 65,000 unités d’énergie quand le destinataire détient déjà des USDT, et environ 130,000 quand son solde USDT est nul : le premier transfert entrant paie le stockage de la création de l’entrée de solde, ce qui explique que le coût dépende entièrement du destinataire et pas de l’expéditeur. Le bandwidth d’un transfert est d’environ 345 octets, assez peu pour que la plupart des comptes le couvrent avec leur quota gratuit quotidien.

Quand vous appelez l’API de location, le service stake ses propres TRX et délègue l’énergie obtenue à l’adresse que vous indiquez, avec le DelegateResourceContract de Stake 2.0. La délégation est liée à une adresse et limitée dans le temps ; à l’expiration de la période de location, le service reprend l’énergie automatiquement.

Un détail important : la location est asynchrone. L’appel renvoie immédiatement un orderId et un état PAID_BY_USER, mais la transaction de délégation est diffusée en arrière-plan et confirmée en général en quelques secondes. Votre intégration doit traiter la réponse initiale comme la confirmation que la commande est acceptée et payée, puis interroger l’endpoint de détails jusqu’à ce que l’état passe à ENERGY_DELEGATED.

Choisir la durée de location

Le paramètre period accepte quatre valeurs : 1h, 1d, 3d, 30d. Les prix suivent le marché on-chain de l’énergie et bougent au cours de la journée, c’est pourquoi les chiffres du moment sont sur la page des tarifs. L’ordre relatif, lui, ne change pas : 1h est le moins cher par appel, 30d le moins cher une fois le coût amorti sur de nombreux transferts depuis la même adresse.

Pour un système événementiel qui déclenche une location par transfert sortant, le palier 1h est presque toujours le bon choix : vous payez le coût absolu le plus bas et l’énergie est consommée quelques secondes après sa délégation. Les paliers 1d et au-delà ont du sens pour des charges batch prévisibles, par exemple un job de paiement nocturne, où vous préférez louer un grand bloc d’énergie une fois plutôt qu’appeler l’API des dizaines de fois. Si votre système émet régulièrement plus de 20 à 30 transferts par heure depuis la même adresse, un bloc 1d dimensionné sur votre volume attendu est plus propre que des appels par transfert : le coût initial monte, mais la surcharge de l’API et la latence de confirmation on-chain sortent du chemin critique.

Authentification et structure de la requête

L’endpoint de location est :

GET https://api.tronenergyrent.com/place-energy-order

C’est une simple requête GET à paramètres de requête. L’authentification passe par le paramètre apiKey, que vous générez depuis votre tableau de bord après inscription et rechargement du compte. Pas d’authentification par en-tête, pas de corps JSON.

Les paramètres :

  • apiKey (obligatoire) : votre clé API, depuis le tableau de bord.
  • period (obligatoire) : la durée de location, parmi 1h, 1d, 3d, 30d.
  • energyAmount (obligatoire) : la quantité d’énergie à déléguer. Le minimum est 15000. Pour un transfert USDT standard vers un destinataire qui détient déjà des USDT, 65000 est la valeur sûre ; pour un premier transfert vers un nouveau détenteur d’USDT, prenez 130000.
  • destinationAddress (obligatoire) : l’adresse TRON (base58check, commence par T) qui recevra l’énergie déléguée.
  • preActivateDestinationAddress (facultatif, 0 par défaut) : mettez 1 si l’adresse de destination n’a jamais reçu de TRX et n’est donc pas activée on-chain. Le service envoie alors 1.5 TRX depuis votre solde prépayé pour l’activer avant de déléguer l’énergie. Si l’adresse est déjà active, laissez 0 pour éviter ce coût.

La réponse revient toujours en HTTP 200, que la commande ait réussi ou non. Branchez-vous sur le champ status du corps JSON, pas sur le code HTTP. Un corps de succès ressemble à ceci :

{
  "status": "SUCCESS",
  "errorCode": null,
  "errorDescription": null,
  "requestId": "2651eacd-2428",
  "payload": {
    "orderId": "128de799-501e-44b2-8d6f-1fa825c2deed",
    "totalPriceSun": 5662800,
    "totalPriceTrx": 5.6628,
    "state": "PAID_BY_USER"
  }
}

Un corps d’erreur contient status: "ERROR", un errorCode lisible par la machine et un errorDescription lisible par un humain :

{
  "status": "ERROR",
  "errorCode": "INVALID_ENERGY_AMOUNT",
  "errorDescription": "energyAmount is less than 15000",
  "requestId": "71431087-4",
  "payload": null
}

Journalisez le requestId dans les deux branches. Si vous devez un jour demander au support de retrouver une location, c’est cet identifiant qu’il utilisera.

Le cycle de vie d’une commande

Le champ state du payload suit une petite séquence fixe :

  • PAID_BY_USER : état initial, la commande est payée depuis votre solde mais rien ne s’est encore passé on-chain.
  • WAITING_DELEGATION : le service a pris la commande et prépare la transaction de délégation.
  • ENERGY_DELEGATED : la délégation est confirmée on-chain. L’adresse de destination dispose de l’énergie louée et peut l’utiliser pour sa prochaine transaction sortante.
  • ERROR_DELEGATION : la délégation a échoué. Rare, mais possible en cas de forte congestion du réseau.
  • CANCELLED : la commande a été annulée et les fonds remboursés sur votre solde.

Pour lire l’état courant, appelez :

GET https://api.tronenergyrent.com/single-order-details?apiKey=YOUR_API_KEY&orderId=ORDER_ID

La réponse utilise la même enveloppe status / errorCode / payload, avec le state courant dans payload. Interrogez cet endpoint toutes les une à deux secondes après la commande, et ne lancez votre transfert TRC-20 qu’après avoir vu ENERGY_DELEGATED. En pratique, cela prend une ou deux interrogations.

Une intégration Python

Voici un schéma minimal mais pensé pour la production. Il passe la location, interroge jusqu’à ce que la délégation soit on-chain et remonte une erreur claire en cas de problème.

import logging
import time
import requests

API_BASE = "https://api.tronenergyrent.com"
API_KEY = "your_api_key_here"
ENERGY_FOR_TRANSFER = 65_000   # use 130_000 if recipient has zero USDT balance
HTTP_TIMEOUT_SECS = 10
POLL_INTERVAL_SECS = 1
POLL_TIMEOUT_SECS = 30


def place_order(destination_address: str, period: str = "1h",
                energy_amount: int = ENERGY_FOR_TRANSFER) -> dict:
    resp = requests.get(
        f"{API_BASE}/place-energy-order",
        params={
            "apiKey": API_KEY,
            "period": period,
            "energyAmount": energy_amount,
            "destinationAddress": destination_address,
            "preActivateDestinationAddress": 0,
        },
        timeout=HTTP_TIMEOUT_SECS,
    )
    resp.raise_for_status()
    body = resp.json()
    if body.get("status") != "SUCCESS":
        raise RuntimeError(
            f"place-energy-order failed: {body.get('errorCode')} "
            f"({body.get('errorDescription')}) requestId={body.get('requestId')}"
        )
    return body["payload"]


def wait_for_delegation(order_id: str) -> dict:
    deadline = time.monotonic() + POLL_TIMEOUT_SECS
    while time.monotonic() < deadline:
        resp = requests.get(
            f"{API_BASE}/single-order-details",
            params={"apiKey": API_KEY, "orderId": order_id},
            timeout=HTTP_TIMEOUT_SECS,
        )
        resp.raise_for_status()
        body = resp.json()
        if body.get("status") != "SUCCESS":
            raise RuntimeError(
                f"single-order-details failed: {body.get('errorCode')} "
                f"({body.get('errorDescription')})"
            )
        state = body["payload"]["state"]
        if state == "ENERGY_DELEGATED":
            return body["payload"]
        if state == "ERROR_DELEGATION":
            raise RuntimeError(f"Delegation failed for order {order_id}")
        if state == "CANCELLED":
            raise RuntimeError(f"Order {order_id} was cancelled")
        time.sleep(POLL_INTERVAL_SECS)
    raise TimeoutError(f"Order {order_id} did not reach ENERGY_DELEGATED in {POLL_TIMEOUT_SECS}s")


def rent_energy(destination_address: str) -> dict:
    placed = place_order(destination_address)
    logging.info(
        "Order placed: id=%s priceSun=%s priceTrx=%s",
        placed["orderId"], placed["totalPriceSun"], placed["totalPriceTrx"],
    )
    delegated = wait_for_delegation(placed["orderId"])
    logging.info("Order delegated: id=%s", delegated["orderId"])
    return delegated

Quelques points à noter. La vérification explicite de status == "SUCCESS" est indispensable, parce que le code HTTP est toujours 200 : resp.raise_for_status() seul ne dit rien du résultat réel. La boucle d’interrogation a un timeout strict, pour qu’une commande bloquée ne paralyse pas votre pipeline indéfiniment. Le branchement sur state traite explicitement les trois issues terminales (ENERGY_DELEGATED, ERROR_DELEGATION, CANCELLED) plutôt qu’un « non-succès » générique.

Dans votre flux de transfert, appelez rent_energy() d’abord, puis diffusez le transfert TRC-20. L’ordre compte : si vous diffusez d’abord, la transaction brûle des TRX de l’expéditeur, parce que la délégation n’est pas encore confirmée.

Dimensionner le solde prépayé

Le coût des locations est déduit d’un solde prépayé sur votre compte tronenergyrent.com. Mettez en place une alerte ou une recharge automatique quand il passe sous un seuil ; un seuil raisonnable couvre deux heures de volume de pointe. Pour lire le solde par programme :

GET https://api.tronenergyrent.com/account-info?apiKey=YOUR_API_KEY

Le payload contient votre solde courant et l’état du compte. Branchez-le sur votre monitoring et un solde à zéro à 2h du matin ne vous surprendra plus. La recharge minimale du solde tronenergyrent.com est de 10 TRX.

Les erreurs en pratique

Trois échecs reviennent le plus souvent en production. Ces codes viennent de l’API réelle, vous pouvez brancher votre code dessus sans crainte.

  1. INSUFFICIENT_BALANCE : votre solde prépayé ne couvre pas la location demandée plus l’éventuelle préactivation. Ne réessayez pas, cela ne changera rien ; attrapez cette erreur spécifiquement et déclenchez une alerte ou un flux de recharge, avec le requestId dans le payload de l’alerte.
  2. INVALID_ADDRESS : la destinationAddress a échoué au décodage base58check côté serveur. Si votre système construit les adresses dynamiquement, par exemple à partir de saisies utilisateur, validez-les localement avant d’appeler l’API : la bibliothèque Python tronpy propose is_address() pour cela, et rejeter une entrée invalide côté client est plus rapide que d’attendre l’aller-retour.
  3. INACTIVE_DESTINATION_ADDRESS_ERROR : l’adresse de destination n’a jamais été activée on-chain et vous n’avez pas demandé au service de l’activer. Corrigez en envoyant d’abord un peu de TRX à l’adresse depuis ailleurs, ou en passant preActivateDestinationAddress=1 au prochain appel pour que le service l’active pour 1.5 TRX.

Un cas plus subtil : ORDER_IS_ALREADY_IN_PROGRESS peut revenir si plusieurs workers louent pour la même destination au même moment. La correction est côté processus, pas côté API : prenez un verrou distribué (Redis fait très bien l’affaire) indexé sur l’adresse de destination et gardé jusqu’à la fin de la délégation.

Vérification on-chain

Pour la plupart des intégrations, interroger /single-order-details jusqu’à ENERGY_DELEGATED suffit. Si vous voulez une ceinture et des bretelles, interrogez aussi directement un nœud complet TRON une fois la délégation confirmée :

GET https://api.trongrid.io/v1/accounts/{destinationAddress}

La réponse contient l’état courant des ressources de l’adresse, y compris l’énergie qui lui est déléguée depuis d’autres adresses. Le nom exact du champ dépend de la vue Stake 2.0 en vigueur, consultez donc la documentation de l’API HTTP de TRON au moment de l’intégration. Comme contrôle souple qui journalise un avertissement au lieu de bloquer le transfert, c’est un bon canari pour les rares cas où quelque chose se passe mal en aval de l’API de location. Cette vérification vous épargnera des heures de débogage le jour où la location semble réussie côté API mais où autre chose cloche on-chain.

Vous voulez économiser sur les frais TRON ? Consultez les prix de l’énergie maintenant. Estimer le prix
Retour au Blog