Mengotomatiskan sewa energi TRON lewat API

2026-05-13

Mengapa mengotomatiskan sewa energi

Jika Anda menjalankan hot wallet, mesin penarikan exchange, atau kontrak yang memicu transfer TRC-20 atas nama pengguna, Anda tahu masalahnya: energi TRON harus sudah siap pada detik transaksi dijalankan. Mengisi energi secara manual lewat UI tidak bisa diskalakan melewati beberapa transfer sehari, dan jika jendelanya terlewat, transaksi membakar TRX dari alamat pengirim, sering kali jauh lebih mahal daripada energi yang disewa lebih dulu.

Solusinya: backend Anda memanggil API sewa tepat sebelum menyiarkan transaksi, sehingga energi disediakan secara terprogram tanpa campur tangan manusia.

Yang dilakukan API di on-chain

Sebelum menulis kode, pahami mekanisme on-chain-nya agar Anda tidak men-debug dengan mata tertutup.

Model sumber daya TRON memisahkan komputasi (energi) dari ukuran transaksi (bandwidth). Transfer USDT TRC-20 standar memakai sekitar 65,000 energi jika penerima sudah punya USDT, dan sekitar 130,000 jika saldo USDT penerima nol: transfer masuk pertama membayar biaya penyimpanan untuk membuat entri saldo, sehingga biayanya ditentukan penerima, bukan pengirim. Bandwidth untuk satu transfer sekitar 345 byte, cukup kecil sehingga kebanyakan akun menutupnya dari kuota gratis harian.

Saat Anda memanggil API sewa, layanan melakukan staking TRX miliknya sendiri dan mendelegasikan energi hasilnya ke alamat yang Anda tentukan lewat DelegateResourceContract dari Stake 2.0. Delegasinya spesifik per alamat dan dibatasi waktu; setelah masa sewa berakhir, energi ditarik kembali secara otomatis.

Satu detail penting: sewa bersifat asinkron. Pemanggilan API langsung mengembalikan orderId dan state PAID_BY_USER, sedangkan transaksi delegasi on-chain disiarkan di latar belakang dan biasanya selesai dalam beberapa detik. Perlakukan respons awal sebagai konfirmasi bahwa pesanan diterima dan dibayar, lalu periksa endpoint detail pesanan sampai state berubah menjadi ENERGY_DELEGATED.

Memilih durasi sewa

Parameter period menerima empat nilai: 1h, 1d, 3d, 30d. Harga mengikuti pasar energi on-chain dan berubah sepanjang hari, jadi angka terkini selalu ada di halaman harga. Urutan relatifnya stabil: 1h paling murah per pemanggilan, 30d paling murah jika dibagi ke banyak transfer dari alamat yang sama.

Untuk sistem berbasis event yang menyewa sekali per transfer keluar, 1h hampir selalu pilihan yang tepat: biaya absolutnya paling rendah dan energinya terpakai dalam hitungan detik setelah didelegasikan. 1d dan yang lebih panjang masuk akal untuk beban batch yang bisa diprediksi, misalnya pembayaran malam hari, saat Anda ingin menyewa satu blok energi besar sekali daripada memanggil API puluhan kali.

Jika sistem Anda rutin menjalankan lebih dari 20-30 transfer per jam dari alamat yang sama, menyewa blok 1d seukuran volume yang diperkirakan lebih rapi daripada pemanggilan per transfer. Biaya di muka naik, tetapi overhead API dan latensi konfirmasi on-chain hilang dari jalur kritis.

Autentikasi dan bentuk permintaan

Endpoint sewa:

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

Ini permintaan GET biasa dengan parameter query. Autentikasinya parameter query apiKey, yang Anda buat di dashboard setelah mendaftar dan mengisi saldo akun. Tidak ada autentikasi lewat header dan tidak ada body JSON.

Parameternya:

  • apiKey (wajib): API key Anda dari dashboard.
  • period (wajib): durasi sewa, salah satu dari 1h, 1d, 3d, 30d.
  • energyAmount (wajib): jumlah energi yang didelegasikan, minimum 15000. Untuk satu transfer USDT standar ke penerima yang sudah punya USDT, 65000 aman; untuk transfer pertama ke pemegang USDT baru, pakai 130000.
  • destinationAddress (wajib): alamat TRON (base58check, diawali T) yang menerima energi.
  • preActivateDestinationAddress (opsional, bawaan 0): setel ke 1 jika alamat tujuan belum pernah menerima TRX dan karena itu belum aktif on-chain. Layanan mengirim 1.5 TRX dari saldo prabayar Anda untuk mengaktifkannya sebelum mendelegasikan energi. Jika alamat sudah aktif, biarkan 0 agar tidak ada biaya tambahan.

Respons selalu berstatus HTTP 200, baik pesanan berhasil maupun gagal. Cabangkan logika Anda pada field status di body JSON, bukan pada status HTTP. Body sukses:

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

Body error berisi status: "ERROR", errorCode untuk mesin, dan errorDescription untuk manusia:

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

Selalu catat requestId di kedua cabang; itulah yang dicari tim support saat Anda meminta mereka melacak sewa tertentu.

Siklus status pesanan

Field state di payload melewati urutan tetap yang pendek:

  • PAID_BY_USER: state awal, pesanan sudah dibayar dari saldo Anda tetapi belum ada aksi on-chain.
  • WAITING_DELEGATION: layanan sudah mengambil pesanan dan sedang menyiapkan transaksi delegasi.
  • ENERGY_DELEGATED: transaksi delegasi sudah masuk on-chain. Alamat tujuan kini punya energi sewaan dan bisa memakainya untuk transaksi keluar berikutnya.
  • ERROR_DELEGATION: delegasi gagal. Jarang, tetapi bisa terjadi saat jaringan sangat padat.
  • CANCELLED: pesanan dibatalkan dan dananya dikembalikan ke saldo Anda.

Untuk memeriksa state saat ini:

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

Responsnya memakai envelope status / errorCode / payload yang sama, dengan state terkini di dalam payload. Periksa setiap satu atau dua detik setelah memasang pesanan dan lanjutkan transfer TRC-20 hanya setelah melihat ENERGY_DELEGATED; dalam praktiknya satu atau dua kali periksa biasanya cukup.

Integrasi Python

Pola minimal yang siap produksi: memasang sewa, memeriksa sampai delegasi masuk on-chain, dan melempar error yang jelas jika ada yang salah.

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

Beberapa catatan. Pemeriksaan eksplisit status == "SUCCESS" penting karena status HTTP selalu 200, sehingga resp.raise_for_status() saja tidak mengatakan apa pun tentang hasil sebenarnya. Loop pemeriksaan punya batas waktu tegas agar pesanan yang macet tidak memblokir pipeline transfer tanpa batas. Percabangan pada state menangani ketiga hasil akhir (ENERGY_DELEGATED, ERROR_DELEGATION, CANCELLED) secara eksplisit, bukan dengan “bukan success” yang generik.

Dalam alur transfer Anda, panggil rent_energy() dulu, baru siarkan transfer TRC-20. Urutannya penting: jika disiarkan lebih dulu, transaksi membakar TRX pengirim karena delegasi belum masuk.

Menjaga saldo prabayar

Biaya sewa dipotong dari saldo prabayar di akun tronenergyrent.com Anda. Pasang peringatan atau pengisian otomatis saat saldo turun di bawah ambang tertentu; batas bawah yang masuk akal adalah cukup untuk dua jam volume puncak.

Untuk membaca saldo saat ini secara terprogram:

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

Payload-nya berisi saldo dan state akun Anda. Sambungkan ke stack pemantauan Anda, dan saldo habis tidak akan lagi mengejutkan Anda pukul 2 pagi. Deposit minimum ke saldo tronenergyrent.com adalah 10 TRX.

Penanganan error dalam praktik

Tiga kegagalan paling sering muncul di produksi. Kode error di bawah berasal dari API yang sebenarnya dan aman dijadikan dasar percabangan.

  1. INSUFFICIENT_BALANCE: saldo prabayar tidak cukup untuk sewa yang diminta plus praaktivasi jika ada. Jangan diulang, mencoba lagi tidak akan memperbaikinya. Tangkap secara spesifik dan picu alur peringatan atau pengisian; sertakan requestId di payload peringatan.
  2. INVALID_ADDRESS: destinationAddress gagal didekode sebagai base58check di server. Jika sistem Anda menyusun alamat secara dinamis, misalnya dari input pengguna, validasi dulu secara lokal sebelum memanggil API. Library Python tronpy punya is_address() untuk ini; menolak input buruk di sisi klien lebih cepat daripada menunggu round trip.
  3. INACTIVE_DESTINATION_ADDRESS_ERROR: alamat tujuan belum pernah diaktifkan on-chain dan Anda tidak meminta layanan mengaktifkannya. Perbaiki dengan mengirim sedikit TRX ke alamat itu dari tempat lain, atau kirim preActivateDestinationAddress=1 pada pemanggilan berikutnya agar layanan mengaktifkannya seharga 1.5 TRX.

Kasus yang lebih halus: ORDER_IS_ALREADY_IN_PROGRESS bisa muncul jika beberapa worker memasang sewa untuk tujuan yang sama bersamaan. Perbaikannya di sisi proses, bukan API: ambil distributed lock (Redis cocok) dengan kunci alamat tujuan dan tahan sampai delegasi selesai.

Verifikasi on-chain

Untuk kebanyakan integrasi, memeriksa /single-order-details sampai ENERGY_DELEGATED sudah cukup. Jika ingin lapisan pengaman ekstra, Anda juga bisa bertanya langsung ke full node TRON setelah delegasi masuk:

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

Responsnya berisi state sumber daya alamat saat itu, termasuk energi yang didelegasikan dari alamat luar. Nama field persisnya mengikuti tampilan Stake 2.0 saat ini, jadi rujuk dokumentasi HTTP API TRON yang berlaku saat memasangnya. Sebagai pemeriksaan lunak yang mencatat peringatan tanpa memblokir transfer, ini penanda yang berguna untuk kasus langka ketika sesuatu di hilir API sewa tidak berjalan semestinya, dan akan menghemat berjam-jam debugging saat sewa tampak sukses di API tetapi ada yang salah di on-chain.

Ingin hemat biaya transaksi TRON? Cek harga energi sekarang. Estimasi Harga
Kembali ke Blog