Jinsi ya Kuendesha Kiotomatiki Ukodishaji wa Nishati ya TRON kwa kutumia API

2026-05-13

Kwa Nini Kuendesha Kiotomatiki Ukodishaji wa Nishati

Ikiwa unaendesha hot wallet, injini ya kutoa fedha ya exchange, au mkataba unaochochea uhamisho wa TRC-20 kwa niaba ya watumiaji, tayari unajua tatizo: unahitaji nishati ya TRON tayari sekunde ambayo muamala unaanza. Kuongeza nishati kwa mkono kupitia kiolesura cha mtumiaji haiwezekani kupanua zaidi ya uhamisho michache kwa siku. Ukikosa nafasi, muamala utachoma TRX kutoka anwani ya mtumaji badala yake, mara nyingi kwa gharama kubwa zaidi kuliko nishati iliyokodishwa mapema.

Suluhisho ni kuita API ya ukodishaji wakati ule ule ambao backend yako iko karibu kutangaza muamala, ili nishati itolewe kwa njia ya programu bila binadamu kuhusika. Makala hii inaonyesha jinsi ya kufanya hivyo dhidi ya tronenergyrent.com: muundo halisi wa ombi, mzunguko wa maisha wa agizo usio wa sambamba, uchaguzi wa muda unaofaa, na mfano wa Python unaofanya kazi ambao unaweza kuingiza kwenye huduma yako.

Kile API Inafanya Hasa On-Chain

Kabla ya kuandika msimbo, ni vyema kuelewa mienendo ya on-chain ili usiwe unatatua bila kuona.

Mfano wa rasilimali wa TRON unagawanya hesabu (nishati) kutoka ukubwa wa muamala (bandwidth). Uhamisho wa kawaida wa USDT TRC-20 unatumia takribani 65,000 ya nishati wakati mpokeaji tayari anashikilia USDT, na takribani 130,000 wakati salio la USDT la mpokeaji ni sufuri. Uhamisho wa kwanza unaoingia hulipa gharama ya kuhifadhi ya kuunda kiingilio cha salio, ndio maana gharama inategemea kabisa mpokeaji, sio mtumaji. Matumizi ya bandwidth kwa uhamisho ni karibu 345 baiti, ambayo ni ndogo vya kutosha kwamba akaunti nyingi hulipia kutoka kwa posho yao ya bure ya kila siku.

Unapoita API ya ukodishaji, huduma inaweka TRX yake mwenyewe na kukabidhi nishati inayotokana kwa anwani unayobainisha, kwa kutumia DelegateResourceContract kutoka Stake 2.0. Ukabidhi ni mahususi kwa anwani na umefungwa kwa wakati. Mara baada ya kipindi cha ukodishaji kuisha, nishati inarejeshwa na mtoa huduma kiotomatiki.

Maelezo moja muhimu: ukodishaji si wa sambamba. Wito wa API unarudi mara moja na orderId na hali ya PAID_BY_USER, lakini muamala wa ukabidhi wa on-chain unatangazwa nyuma na kwa kawaida unafika ndani ya sekunde chache. Ujumuishaji wako unapaswa kushughulikia jibu la awali kama uthibitisho kwamba agizo limekubaliwa na kulipwa, kisha kuangalia kwa mara kwa mara kiunzi cha maelezo ya agizo hadi hali ihamie kwa ENERGY_DELEGATED.

Kuchagua Muda Sahihi wa Ukodishaji

API inakubali kigezo cha period chenye maadili manne yanayoruhusiwa: 1h, 1d, 3d, 30d. Bei zinaelea pamoja na soko la nishati la on-chain na zinabadilika wakati wa mchana, kwa hivyo nambari za moja kwa moja huishi daima kwenye ukurasa wa bei. Mpangilio wa jamaa ni thabiti: 1h ni ya bei ya chini kabisa kwa kila wito, 30d ni ya bei ya chini kabisa inapogawanywa kwa uhamisho mwingi kutoka anwani moja.

Kwa mfumo unaoendeshwa na matukio ambapo unachochea ukodishaji mmoja kwa kila uhamisho unaotoka, ngazi ya 1h karibu kila wakati ni chaguo sahihi. Unalipa gharama ya chini kabisa na nishati inatumika ndani ya sekunde za kukabidhiwa. Ngazi za 1d na ndefu zaidi zinafaa wakati unaendesha kazi za makundi zinazoweza kutabirika, kwa mfano kazi ya kulipa ya kila usiku, na unataka kukodi kizuizi kikubwa cha nishati mara moja badala ya kuita API mara dazeni.

Ikiwa mfumo wako kwa kawaida unaanzisha zaidi ya uhamisho 20-30 kwa saa kutoka anwani moja, kukodi kizuizi cha 1d chenye ukubwa wa kufunika kiasi unachotarajia ni safi zaidi kuliko wito wa kila uhamisho. Gharama ya awali inaongezeka lakini gharama za ziada za API na ucheleweshaji wa uthibitisho wa on-chain unatoweka kwenye njia ya moto.

Uthibitishaji na Muundo wa Ombi

Kiunzi cha ukodishaji kinapatikana hapa:

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

Ni ombi rahisi la GET lenye vigezo vya hoja. Uthibitishaji ni kigezo cha hoja cha apiKey, ambacho unazalisha kutoka dashibodi yako baada ya kujisajili na kufadhili akaunti yako. Hakuna uthibitishaji unaotokana na kichwa na hakuna mwili wa ombi wa JSON kwa kiunzi hiki.

Vigezo ni:

  • apiKey (kinahitajika): ufunguo wa API kutoka dashibodi yako.
  • period (kinahitajika): muda wa ukodishaji, mmoja kati ya 1h, 1d, 3d, 30d.
  • energyAmount (kinahitajika): kiasi gani cha nishati ya kukabidhi. Kima cha chini ni 15000. Kwa uhamisho mmoja wa kawaida wa USDT kwa mpokeaji ambaye tayari anashikilia USDT, 65000 ni nambari salama; kwa uhamisho wa kwanza kwa mshikiliaji mpya wa USDT, tumia 130000.
  • destinationAddress (kinahitajika): anwani ya TRON (base58check, inaanza na T) ambayo itapokea nishati iliyokabidhiwa.
  • preActivateDestinationAddress (hiari, chaguo-msingi 0): weka kwa 1 ikiwa anwani lengwa haijawahi kupokea TRX yoyote na kwa hivyo haijaamilishwa on-chain. Huduma kisha inatuma 1.5 TRX kutoka kwa salio lako la awali kuamilisha anwani kabla ya kukabidhi nishati. Ikiwa anwani tayari iko hai, acha hii kwa 0 ili kuepuka gharama ya ziada.

Jibu daima linarejeshwa na hali ya HTTP 200, bila kujali kama agizo limefanikiwa au limefeli. Tawi kwenye uga wa status wa mwili wa JSON badala ya hali ya HTTP. Mwili wa mafanikio unaonekana hivi:

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

Mwili wa kosa una status: "ERROR", errorCode inayoweza kusomwa na mashine, na errorDescription inayoweza kusomwa na binadamu:

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

Daima rekodi requestId kwenye matawi yote mawili. Ikiwa utahitaji kuomba huduma ya msaada kufuatilia ukodishaji mahususi, kitambulisho hicho ndicho wanachotafuta.

Mzunguko wa Maisha wa Agizo

Uga wa state kwenye payload unaendelea kupitia mfululizo mdogo uliowekwa:

  • PAID_BY_USER: hali ya awali, agizo limelipwa kutoka kwa salio lako lakini hakuna hatua ya on-chain bado.
  • WAITING_DELEGATION: huduma imechukua agizo na inaandaa muamala wa ukabidhi.
  • ENERGY_DELEGATED: muamala wa ukabidhi umefika on-chain. Anwani lengwa sasa inashikilia nishati iliyokodishwa na inaweza kuitumia kwenye muamala unaofuata unaotoka.
  • ERROR_DELEGATION: ukabidhi umefeli kwa sababu fulani. Nadra, lakini inawezekana wakati wa msongamano mzito wa mtandao.
  • CANCELLED: agizo limefutwa na fedha zimerejeshwa kwenye salio lako.

Kuangalia hali ya sasa, ita:

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

Jibu linatumia bahasha ile ile ya status / errorCode / payload, na state ya sasa ndani ya payload. Angalia hii kila sekunde moja au mbili baada ya kuweka agizo na uendelee na uhamisho wako wa TRC-20 tu baada ya kuona ENERGY_DELEGATED. Kwa vitendo hii kawaida ni angalio moja au mawili.

Ujumuishaji wa Python Unaofanya Kazi

Hapa kuna mfumo wa chini lakini wenye umbo la uzalishaji. Unaweka ukodishaji, unaangalia hadi ukabidhi uko on-chain, na unaonyesha kosa wazi ikiwa kitu chochote kitakwenda 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 machache yenye thamani ya kuangaziwa. Ukaguzi wa wazi wa status == "SUCCESS" ni muhimu kwa sababu hali ya HTTP daima ni 200, kwa hivyo resp.raise_for_status() peke yake haikuambii chochote kuhusu matokeo halisi. Kitanzi cha kuangalia kina muda mgumu wa kuisha ili agizo lililokwama lisiweze kuzuia bomba lako la uhamisho milele. Matawi kwenye state yanashughulikia matokeo matatu ya mwisho (ENERGY_DELEGATED, ERROR_DELEGATION, CANCELLED) waziwazi badala ya kutegemea "sio mafanikio" ya jumla.

Katika mtiririko wako wa kazi wa uhamisho, ita rent_energy() kwanza, kisha tangaza uhamisho wa TRC-20. Mpangilio wa shughuli ni muhimu: tangaza kwanza na muamala utachoma TRX kutoka kwa mtumaji kwa sababu ukabidhi haujafika bado.

Kupima Ukubwa wa Salio Lako la Awali

Gharama ya ukodishaji inakatwa kutoka kwa salio la awali unaloshikilia kwenye akaunti yako ya tronenergyrent.com. Weka tahadhari au ujazaji wa kiotomatiki wakati salio linapungua chini ya kizingiti. Sakafu inayofaa ni chochote kinachofunika saa mbili za kiasi cha kilele.

Kusoma salio la sasa kwa njia ya programu:

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

Payload inajumuisha salio lako la sasa na hali ya akaunti. Unganisha hiyo kwenye mfumo wako wa ufuatiliaji na hutashangaa kamwe na salio lililoisha saa 2 asubuhi. Kumbuka kwamba kima cha chini cha ujazaji kwa salio lako la tronenergyrent.com ni 10 TRX.

Kushughulikia Makosa Katika Vitendo

Hali tatu za kufeli zinajitokeza mara nyingi katika uzalishaji. Misimbo ya makosa hapa chini inatoka kwa API halisi na unaweza kutawi juu yake kwa usalama.

  1. INSUFFICIENT_BALANCE: salio lako la awali ni la chini sana kufunika ukodishaji ulioombwa pamoja na uamilishaji wowote wa mapema. Usijaribu tena, kujaribu hakutarekebisha. Shika hii mahususi na anzisha mtiririko wa tahadhari au ujazaji. Ongeza requestId kwa payload ya tahadhari yako.
  2. INVALID_ADDRESS: destinationAddress imefeli usimbuaji wa base58check kwenye seva. Ikiwa mfumo wako unaunda anwani kwa nguvu, kwa mfano kutoka kwa ingizo lililotolewa na mtumiaji, zithibitishe ndani ya nchi kabla ya kuita API. Maktaba ya Python ya tronpy ina is_address() kwa hili; 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 hukuomba huduma kuiamilisha. Rekebisha kwa kufadhili anwani mapema na kiasi kidogo cha TRX kutoka mahali pengine, au kwa kupitisha preActivateDestinationAddress=1 kwenye wito unaofuata ili huduma iamilishe kwa 1.5 TRX.

Hali ndogo zaidi: ORDER_IS_ALREADY_IN_PROGRESS inaweza kurudi ikiwa una wafanyakazi wengi wanaoweka ukodishaji kwa anwani lengwa moja kwa wakati mmoja. Suluhisho ni upande wa mchakato, sio upande wa API. Chukua kufuli iliyosambazwa (Redis inafanya kazi vizuri) iliyowekwa funguo kwenye anwani lengwa na kushikiliwa hadi ukabidhi ukamilike.

Kuthibitisha On-Chain

Kwa ujumuishaji mwingi, kuangalia /single-order-details hadi ENERGY_DELEGATED ni ya kutosha. Ikiwa unataka uthibitishaji wa mkanda na suruali, unaweza pia kuuliza node kamili ya TRON moja kwa moja baada ya ukabidhi kufika:

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

Jibu lina hali ya sasa ya rasilimali ya anwani, ikijumuisha nishati iliyokabidhiwa kwake kutoka kwa anwani za nje. Jina kamili la uga linategemea mtazamo wa sasa wa Stake 2.0, kwa hivyo shauriana na hati za moja kwa moja za TRON HTTP API unapounganisha hii. Kama ukaguzi laini ambao unarekodi onyo badala ya kuzuia uhamisho, ni canary muhimu kwa hali nadra wakati kitu kitakapokwenda vibaya chini ya API ya ukodishaji yenyewe.

Ukaguzi huo wa ziada utaokoa saa za utatuzi mara moja ambapo ukodishaji unaonekana kufanikiwa kwenye API lakini kitu kingine kitakwenda vibaya on-chain.

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

Wasiliana na Msaada wa Kodi Nguvu ya TRON

Kurasa Muhimu