Paano I-automate ang TRON Energy Rental gamit ang API

2026-05-13

Bakit Kailangan I-automate ang Energy Rental

Kung nagpapatakbo ka ng hot wallet, exchange withdrawal engine, o contract na nag-tri-trigger ng TRC-20 transfers para sa mga user, alam mo na ang sakit ng ulo: kailangan mong handa ang TRON energy sa mismong segundo na mag-fi-fire ang transaction. Hindi mag-i-scale ang manu-manong pag-top up ng energy gamit ang UI lampas sa ilang transfers kada araw. Kapag na-miss mo ang window, susunugin ng transaction ang TRX mula sa sending address sa halip, kadalasan sa mas mataas na cost kaysa sa pre-rented na energy.

Ang solusyon ay tawagan ang rental API sa sandaling malapit nang mag-broadcast ng transaction ang iyong backend, para ma-provision ang energy programmatically nang walang taong nakikialam. Ipapakita ng artikulong ito kung paano eksaktong gawin iyon kontra sa tronenergyrent.com: ang totoong request shape, ang asynchronous na order lifecycle, makatuwirang duration tradeoffs, at gumaganang Python example na pwede mong ilagay sa iyong service.

Ano ba Talaga ang Ginagawa ng API On-Chain

Bago mag-code, makakatulong na maintindihan ang on-chain mechanics para hindi ka nagde-debug nang patay-malisya.

Hinahati ng resource model ng TRON ang computation (energy) mula sa transaction size (bandwidth). Isang standard na USDT TRC-20 transfer ay kumukunsumo ng humigit-kumulang 65,000 energy kapag may hawak nang USDT ang recipient, at humigit-kumulang 130,000 kapag ang USDT balance ng recipient ay zero. Ang unang papasok na transfer ay nagbabayad ng storage cost para sa paggawa ng balance entry, kaya ang cost ay umaasa nang buo sa recipient, hindi sa sender. Ang bandwidth usage para sa isang transfer ay nasa paligid ng 345 bytes, na sapat na maliit para mai-cover ito ng karamihan sa mga account mula sa kanilang araw-araw na libreng allowance.

Kapag tinawag mo ang rental API, ina-stake ng service ang sarili nitong TRX at idine-delegate ang resulting energy sa address na ina-specify mo, gamit ang DelegateResourceContract mula sa Stake 2.0. Address-specific at time-bounded ang delegation. Kapag nag-expire ang rental period, awtomatikong nababawi ng provider ang energy.

Isang mahalagang detalye: asynchronous ang rental. Agad nagre-return ang API call ng orderId at state na PAID_BY_USER, pero ang on-chain delegation transaction ay nai-broadcast sa background at karaniwang naka-land sa loob ng ilang segundo. Dapat tratuhin ng iyong integration ang initial response bilang kumpirmasyon na natanggap at nabayaran ang order, tapos i-poll ang order details endpoint hanggang lumipat ang state sa ENERGY_DELEGATED.

Pagpili ng Tamang Rental Duration

Tumatanggap ang API ng period parameter na may apat na pinapayagang values: 1h, 1d, 3d, 30d. Lumulutang ang mga presyo kasabay ng on-chain energy market at nagbabago sa loob ng araw, kaya ang live na numero ay laging nasa pricing page. Stable ang relative ordering: 1h ang pinakamura kada call, 30d ang pinakamura kapag na-amortize sa maraming transfers mula sa parehong address.

Para sa event-driven system kung saan nagti-trigger ka ng isang rental kada outgoing transfer, ang 1h tier ay halos palaging tamang pagpipilian. Babayaran mo ang pinakamababang absolute cost at nakukunsumo ang energy sa loob ng ilang segundo pagkatapos ng delegation. Ang 1d at mas mahabang tier ay may saysay kapag nagpapatakbo ka ng predictable batch workloads, halimbawa isang nightly payout job, at gusto mong umarkila ng malaking energy block nang minsanan sa halip na tumawag sa API nang dose-dosena beses.

Kung ang iyong system ay palagiang nag-fi-fire ng higit sa 20-30 transfers kada oras mula sa parehong address, ang pag-rent ng 1d block na sukat ng inaasahan mong volume ay mas malinis kaysa sa per-transfer calls. Tumataas ang upfront cost pero nawawala mula sa hot path ang API overhead at on-chain confirmation latency.

Authentication at Request Structure

Nakatira ang rental endpoint sa:

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

Isa itong simpleng GET request na may query parameters. Ang authentication ay ang apiKey query parameter, na ginagawa mo mula sa iyong dashboard pagkatapos magparehistro at magbayad sa iyong account. Walang header-based na auth at walang JSON request body para sa endpoint na ito.

Ang mga parameter ay:

  • apiKey (required): ang iyong API key mula sa dashboard.
  • period (required): rental duration, isa sa 1h, 1d, 3d, 30d.
  • energyAmount (required): kung gaano karaming energy ang ide-delegate. Minimum ay 15000. Para sa isang standard na USDT transfer sa recipient na may hawak nang USDT, 65000 ay safe na bilang; para sa unang transfer sa fresh na USDT holder, gamitin ang 130000.
  • destinationAddress (required): ang TRON address (base58check, nagsisimula sa T) na tatanggap ng delegated energy.
  • preActivateDestinationAddress (optional, default 0): itakda sa 1 kung ang destination address ay hindi pa nakatanggap ng anumang TRX at samakatuwid ay hindi aktibo on-chain. Magpapadala ang service ng 1.5 TRX mula sa iyong prepaid balance para i-activate ang address bago mag-delegate ng energy. Kung aktibo na ang address, iwan ito sa 0 para maiwasan ang dagdag na cost.

Ang response ay laging ibinabalik na may HTTP status 200, kahit na nagtagumpay o nabigo ang order. Mag-branch sa status field ng JSON body sa halip na sa HTTP status. Ang success body ay ganito ang hitsura:

{
  "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"
  }
}

Ang error body ay may status: "ERROR", machine-readable na errorCode, at human-readable na errorDescription:

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

Lagi mong i-log ang requestId sa parehong branches. Kapag kailangan mong hilingin sa support na i-trace ang isang partikular na rental, iyon ang ID na hinahanap nila.

Ang Order Lifecycle

Ang state field sa payload ay sumusulong sa maliit na fixed sequence:

  • PAID_BY_USER: initial state, bayad na ang order mula sa iyong balance pero wala pang nangyayaring on-chain action.
  • WAITING_DELEGATION: nakuha na ng service ang order at inihahanda na ang delegation transaction.
  • ENERGY_DELEGATED: naka-land na on-chain ang delegation transaction. May hawak nang rented energy ang destination address at maaari na itong gastusin sa susunod na outbound transaction.
  • ERROR_DELEGATION: nabigo ang delegation sa kung anong dahilan. Bihira, pero posible kapag may malalang network congestion.
  • CANCELLED: na-cancel ang order at na-refund ang funds sa iyong balance.

Para tingnan ang kasalukuyang state, tawagan ang:

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

Ginagamit ng response ang parehong status / errorCode / payload envelope, na may kasalukuyang state sa loob ng payload. I-poll ito bawat isa o dalawang segundo pagkatapos i-place ang order at magpatuloy sa iyong TRC-20 transfer pagkatapos mo lang makita ang ENERGY_DELEGATED. Sa praktika ito ay karaniwang isa o dalawang polls.

Isang Gumaganang Python Integration

Narito ang minimal pero production-shaped na pattern. Ina-place nito ang rental, nag-po-poll hanggang nasa on-chain na ang delegation, at nagpapakita ng malinaw na error kung may mali.

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

Ilang bagay na dapat bigyang-diin. Ang explicit na status == "SUCCESS" check ay mahalaga dahil ang HTTP status ay laging 200, kaya ang resp.raise_for_status() lamang ay walang sinasabi sa iyo tungkol sa aktwal na resulta. Ang polling loop ay may hard timeout para ang stuck na order ay hindi makaharang sa iyong transfer pipeline nang walang katapusan. Ang branching sa state ay explicit na hina-handle ang tatlong terminal outcomes (ENERGY_DELEGATED, ERROR_DELEGATION, CANCELLED) sa halip na umasa sa generic na "not success".

Sa iyong transfer workflow, tawagan muna ang rent_energy(), tapos i-broadcast ang TRC-20 transfer. Mahalaga ang pagkakasunod-sunod ng operasyon: kung mag-broadcast ka muna, susunugin ng transaction ang TRX mula sa sender dahil hindi pa naka-land ang delegation.

Pag-Size ng Iyong Prepaid Balance

Ang rental cost ay ibinabawas mula sa prepaid balance na pinananatili mo sa iyong tronenergyrent.com account. Mag-set up ng alert o automated top-up kapag bumaba ang balance sa ibaba ng threshold. Ang makatuwirang floor ay kung anuman ang pumapatong sa dalawang oras ng peak volume.

Para basahin ang kasalukuyang balance programmatically:

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

Kasama sa payload ang iyong kasalukuyang balance at account state. I-wire iyon sa iyong monitoring stack at hindi ka kailanman magugulat sa naubos na balance ng alas-dos ng madaling-araw. Tandaan na ang minimum na top-up sa iyong tronenergyrent.com balance ay 10 TRX.

Error Handling sa Praktika

Tatlong failure modes ang madalas lumitaw sa production. Ang mga error codes sa ibaba ay nanggaling sa totoong API at maaari kang mag-branch sa mga ito nang ligtas.

  1. INSUFFICIENT_BALANCE: masyadong mababa ang iyong prepaid balance para masaklaw ang hiniling na rental kasama ang anumang pre-activation. Huwag mag-retry, hindi ito aayusin ng pag-retry. I-catch ito nang specific at mag-trigger ng alert o top-up flow. Idagdag ang requestId sa iyong alert payload.
  2. INVALID_ADDRESS: nabigo ang destinationAddress sa base58check decode sa server. Kung ang iyong system ay gumagawa ng addresses nang dynamically, halimbawa mula sa user-supplied na input, i-validate ang mga ito locally bago tumawag sa API. May is_address() ang tronpy Python library para dito; mas mabilis i-reject ang masamang input sa client-side kaysa maghintay ng round trip.
  3. INACTIVE_DESTINATION_ADDRESS_ERROR: hindi pa kailanman na-activate on-chain ang destination address at hindi mo hiniling sa service na i-activate ito. Ayusin sa pamamagitan ng pre-funding ng address na may maliit na halaga ng TRX mula sa ibang lugar, o sa pamamagitan ng pagpasa ng preActivateDestinationAddress=1 sa susunod na call para i-activate ito ng service sa halagang 1.5 TRX.

Isang mas banayad na kaso: maaaring bumalik ang ORDER_IS_ALREADY_IN_PROGRESS kung may maraming workers na nag-pi-place ng rentals para sa parehong destination sa parehong oras. Ang ayos ay process-side, hindi API-side. Kumuha ng distributed lock (gumagana nang ayos ang Redis) na naka-key sa destination address at hinahawakan hanggang makumpleto ang delegation.

Pag-verify On-Chain

Para sa karamihan ng integrations, sapat na ang pag-poll ng /single-order-details hanggang ENERGY_DELEGATED. Kung gusto mo ng belt-and-braces na verification, maaari mo ring i-query ang TRON full node nang direkta pagkatapos mag-land ang delegation:

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

Naglalaman ang response ng kasalukuyang resource state ng address, kabilang ang energy na naka-delegate dito mula sa external addresses. Umaasa ang eksaktong field name sa kasalukuyang Stake 2.0 view, kaya kumonsulta sa live na TRON HTTP API docs kapag inaayos ito. Bilang soft check na nagla-log ng warning sa halip na harangin ang transfer, kapaki-pakinabang itong canary para sa bihirang kaso kapag may mali sa downstream ng mismong rental API.

Ang dagdag na check na iyon ay makakapagligtas sa iyo ng oras ng pag-debug sa minsanang pagkakataon kapag mukhang matagumpay ang rental sa API pero may ibang nangyaring mali on-chain.

Gusto mo bang makatipid sa bayarin ng TRON? Tingnan ang presyo ng energy ngayon. Presyo Estimate
Bumalik sa Blog

Makipag-ugnayan sa TRON Energy Rent Support

Mga Kapaki-pakinabang na Pahina