Jinsi ya kukodisha TRON energy kiotomatiki kupitia API

2026-05-13

Kama unaendesha hot wallet, mfumo wa uondoaji wa exchange au smart contract inayotuma uhamishaji wa TRC-20 kwa niaba ya watumiaji, unahitaji TRON energy iwe tayari sekunde ile ile muamala unapoanza. Kujaza kwa mikono kupitia kiolesura hakupanuki zaidi ya uhamishaji mchache kwa siku, na ukikosa wakati muamala unachoma TRX kutoka kwenye anwani inayotuma, kwa kawaida kwa gharama kubwa zaidi kuliko energy iliyokodishwa. Suluhisho ni kuita API ya kukodisha kabla tu backend yako haijatangaza, ili energy itolewe bila mtu kuhusika.

API inafanya nini on-chain

TRON inatenganisha hesabu (energy) na ukubwa wa muamala (bandwidth). Uhamishaji wa kawaida wa USDT TRC-20 unachukua takriban 65,000 energy wakati mpokeaji tayari ana USDT na takriban 130,000 wakati salio la USDT la mpokeaji ni sifuri, kwa sababu uhamishaji wa kwanza unaoingia unalipia kuunda rekodi ya salio; gharama inategemea mpokeaji, si mtumaji. Bandwidth ni karibu baiti 345, kiasi kidogo cha kutosha kwamba akaunti nyingi zinakilipia kutoka kwenye mgao wa bure wa kila siku.

Unapoita API ya kukodisha, huduma inafunga TRX yake mwenyewe na kukabidhi energy inayotokana kwa anwani unayotaja, kwa DelegateResourceContract ya Stake 2.0. Ukabidhi umefungwa kwa anwani hiyo na kwa kipindi cha ukodishaji, na kipindi kikiisha huduma inairejesha energy kiotomatiki.

Ukodishaji si wa papo hapo. Mwito unarudi mara moja na orderId na hali ya PAID_BY_USER; muamala wa ukabidhi unatangazwa nyuma na kwa kawaida unafika ndani ya sekunde chache. Chukulia jibu la kwanza kama uthibitisho kwamba oda imekubaliwa na kulipwa, kisha angalia endpoint ya maelezo ya oda hadi hali iwe ENERGY_DELEGATED.

Kuchagua muda

period inapokea moja kati ya thamani nne: 1h, 1d, 3d, 30d. Bei zinafuata soko la energy la on-chain na zinabadilika mchana kutwa, kwa hivyo bei za sasa ziko kwenye ukurasa wa bei. Mpangilio haubadiliki: 1h ndiyo nafuu zaidi kwa kila mwito, 30d ndiyo nafuu zaidi ikigawanywa kwa uhamishaji mwingi kutoka anwani moja.

Kwa mfumo unaoendeshwa na matukio unaokodisha mara moja kwa kila uhamishaji unaotoka, 1h karibu kila mara ndiyo sahihi: gharama ya chini zaidi, na energy inatumika sekunde chache baada ya kukabidhiwa. 1d na virefu zaidi vinafaa kazi za makundi zinazotabirika kama malipo ya kila usiku, ambapo unakodisha kizuizi kimoja kikubwa badala ya kuita API mara nyingi. Kama anwani moja inatuma zaidi ya uhamishaji 20 hadi 30 kwa saa mfululizo, kizuizi cha 1d kilichopimwa kwa kiasi unachotarajia ni safi zaidi kuliko miito ya kila uhamishaji: gharama ya awali ni kubwa zaidi, lakini safari za API na ucheleweshaji wa uthibitisho wa on-chain vinatoka kwenye njia ya haraka.

Muundo wa ombi

Endpoint ya kukodisha ni:

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

Ombi la kawaida la GET lenye query parameters. Uthibitishaji ni parameter ya apiKey, unayotengeneza kwenye dashibodi yako baada ya kujisajili na kujaza salio. Hakuna uthibitishaji wa header na hakuna JSON body.

Parameters:

  • apiKey (inahitajika): API key yako kutoka dashibodi.
  • period (inahitajika): moja kati ya 1h, 1d, 3d, 30d.
  • energyAmount (inahitajika): kiasi cha energy cha kukabidhi, kiwango cha chini 15000. Kwa uhamishaji mmoja wa kawaida wa USDT kwa mpokeaji ambaye tayari ana USDT, 65000 ni kiasi salama; kwa uhamishaji wa kwanza kwa mpokeaji mpya wa USDT, tumia 130000.
  • destinationAddress (inahitajika): anwani ya TRON (base58check, inaanza na T) inayopokea energy.
  • preActivateDestinationAddress (hiari, chaguo-msingi 0): weka 1 kama anwani lengwa haijawahi kupokea TRX na kwa hivyo haijaamilishwa on-chain. Huduma inatuma 1.5 TRX kutoka kwenye salio lako lililolipiwa mapema kuiamilisha kabla ya kukabidhi. Iache 0 kwa anwani iliyo hai ili kuepuka gharama ya ziada.

Hali ya HTTP daima ni 200, oda imefanikiwa au haijafanikiwa, kwa hivyo tegemea sehemu ya status ya JSON body. Jibu la mafanikio:

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

Jibu la kosa lina status: "ERROR", errorCode inayosomwa na mashine na errorDescription inayosomwa na mtu:

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

Rekodi requestId katika matawi yote mawili; hicho ndicho msaada unachotafuta unapowaomba wafuatilie oda.

Mzunguko wa oda

Sehemu ya state inapitia mfululizo mfupi uliowekwa:

  • PAID_BY_USER: oda imelipwa kutoka kwenye salio lako; hakuna kilichotokea on-chain bado.
  • WAITING_DELEGATION: huduma imeichukua oda na inaandaa muamala wa ukabidhi.
  • ENERGY_DELEGATED: ukabidhi uko on-chain. Anwani lengwa ina energy na inaweza kuitumia kwenye muamala wake unaofuata.
  • ERROR_DELEGATION: ukabidhi umeshindwa. Nadra, lakini inawezekana wakati wa msongamano mkubwa wa mtandao.
  • CANCELLED: oda imefutwa na fedha zimerejeshwa kwenye salio lako.

Kuangalia hali ya sasa:

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

Jibu linatumia muundo ule ule wa status / errorCode / payload, na state ndani ya payload. Angalia kila sekunde moja au mbili baada ya kuweka oda na utume uhamishaji wa TRC-20 tu baada ya kuona ENERGY_DELEGATED; kwa vitendo huo ni ukaguzi mmoja au miwili.

Ujumuishaji wa Python

Mfano mdogo lakini wenye umbo la production: unaweka oda, unaangalia hadi ukabidhi uko on-chain na unatoa kosa wazi kitu chochote kikienda vibaya.

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

Mambo matatu yanajalisha. Ukaguzi wa wazi wa status == "SUCCESS", kwa sababu hali ya HTTP daima ni 200 na resp.raise_for_status() peke yake haisemi chochote kuhusu matokeo. Muda wa kuisha usiobadilika kwenye kitanzi cha ukaguzi, ili oda iliyokwama isizuie mfumo wako wa uhamishaji. Na matawi ya wazi ya state kwa matokeo matatu ya mwisho (ENERGY_DELEGATED, ERROR_DELEGATION, CANCELLED) badala ya “si mafanikio” ya jumla.

Katika mtiririko wa uhamishaji, ita rent_energy() kwanza na utangaze uhamishaji wa TRC-20 baada ya kurudi. Ukitangaza kwanza, muamala unachoma TRX kutoka kwa mtumaji, kwa sababu ukabidhi haujafika bado.

Salio lililolipiwa mapema

Ukodishaji unalipwa kutoka kwenye salio lililolipiwa mapema la akaunti yako ya tronenergyrent.com. Weka tahadhari au ujazaji wa kiotomatiki salio linaposhuka chini ya kizingiti; sakafu nzuri ni saa mbili za kiasi cha kilele. Kiwango cha chini cha kujaza ni 10 TRX. Kusoma salio kwa programu:

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

Payload inajumuisha salio la sasa na hali ya akaunti. Iunganishe kwenye ufuatiliaji wako na salio lililoisha usiku wa manane linaacha kuwa mshangao.

Makosa utakayoyaona

Hali tatu za kushindwa ndizo za kawaida zaidi katika production. Misimbo ni ya API halisi, kwa hivyo unaweza kuitegemea kwenye matawi.

  1. INSUFFICIENT_BALANCE: salio lililolipiwa mapema halitoshi kwa ukodishaji pamoja na uamilishaji wowote wa mapema. Kujaribu tena hakusaidii; ishike, toa tahadhari au anzisha ujazaji, na uweke requestId kwenye tahadhari.
  2. INVALID_ADDRESS: destinationAddress imeshindwa kusimbuliwa kwa base58check kwenye seva. Kama unaunda anwani kutoka kwenye ingizo la mtumiaji, zithibitishe kwanza upande wako; maktaba ya tronpy ina is_address(), na kukataa ingizo baya upande wa mteja ni haraka kuliko kusubiri safari ya kwenda na kurudi.
  3. INACTIVE_DESTINATION_ADDRESS_ERROR: anwani lengwa haijawahi kuamilishwa on-chain na hukuiomba huduma ifanye hivyo. Ama ipe anwani TRX kidogo kutoka mahali pengine, au pitisha preActivateDestinationAddress=1 kwenye mwito unaofuata na huduma inaiamilisha kwa 1.5 TRX.

Kosa la hila zaidi: ORDER_IS_ALREADY_IN_PROGRESS linarudi wakati workers kadhaa zinaweka ukodishaji kwa anwani lengwa ile ile kwa wakati mmoja. Litatue upande wako kwa kufuli iliyosambazwa (Redis inatosha) yenye ufunguo wa anwani lengwa na inayoshikiliwa hadi ukabidhi ukamilike.

Kuthibitisha on-chain

Kwa ujumuishaji mwingi, kuangalia /single-order-details hadi ENERGY_DELEGATED kunatosha. Ukitaka ukaguzi wa ziada, uliza full node ya TRON baada ya ukabidhi kufika:

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

Jibu lina hali ya sasa ya rasilimali za anwani, pamoja na energy iliyokabidhiwa kwake kutoka anwani nyingine. Jina halisi la sehemu linategemea mtazamo wa sasa wa Stake 2.0, kwa hivyo angalia nyaraka za sasa za TRON HTTP API unapoiunganisha. Iendeshe kama ukaguzi laini unaorekodi onyo badala ya kuzuia uhamishaji. Inanasa hali nadra ambapo ukodishaji unaonekana sawa kwenye API lakini kitu kilienda vibaya on-chain, na mara hiyo moja itakuokoa saa nyingi za utatuzi.

Unataka kuokoa ada za muamala wa TRON? Angalia bei za energy sasa. Makadirio ya Bei
Rudi kwenye Blogu