Як автоматизувати оренду енергії TRON через API
Навіщо автоматизувати
Якщо ви тримаєте гарячий гаманець, сервіс виведення коштів на біржі або контракт, який робить перекази TRC-20 від імені користувачів, ви знаєте цей біль: енергія має бути на адресі в ту саму секунду, коли йде транзакція. Поповнювати її руками через інтерфейс можна лише до кількох переказів на день. Пропустили момент, і транзакція спалить TRX з адреси відправника, зазвичай значно дорожче за орендовану наперед енергію. Рішення: викликати API оренди в той момент, коли бекенд збирається транслювати транзакцію, щоб енергія приходила програмно, без людини.
Що API робить у мережі
Модель ресурсів TRON розділяє обчислення (енергія) і розмір транзакції (bandwidth). Стандартний переказ USDT TRC-20 споживає приблизно 65,000 енергії, якщо в одержувача вже є USDT, і близько 130,000, якщо його баланс USDT нульовий: перший вхідний переказ оплачує запис балансу у сховищі, тому вартість залежить лише від одержувача, а не від відправника. Bandwidth переказ бере близько 345 байтів, і більшості акаунтів вистачає безкоштовного денного ліміту.
Коли ви викликаєте API, сервіс стейкає власні TRX і делегує отриману енергію на вказану адресу через DelegateResourceContract зі Stake 2.0. Делегування прив’язане до адреси та обмежене в часі; коли термін оренди минає, сервіс автоматично забирає енергію назад.
Важлива деталь: оренда асинхронна. Виклик одразу повертає orderId і стан PAID_BY_USER, а транзакція делегування транслюється у фоні і зазвичай потрапляє в блок за кілька секунд. Першу відповідь сприймайте як підтвердження, що замовлення прийняте й оплачене, і далі опитуйте деталі замовлення, доки стан не стане ENERGY_DELEGATED.
Яку тривалість обрати
Параметр period приймає чотири значення: 1h, 1d, 3d, 30d. Ціни рухаються разом із ринком енергії протягом дня, тому актуальні цифри завжди на сторінці цін. Порядок сталий: 1h найдешевший за один виклик, 30d найдешевший у перерахунку на багато переказів з однієї адреси.
Для системи на подіях, де одна оренда припадає на один вихідний переказ, 1h майже завжди правильний вибір: найменша абсолютна ціна, а енергія витрачається за секунди після делегування. 1d і довші тарифи потрібні для передбачуваних пакетних навантажень, наприклад нічних виплат, коли простіше один раз орендувати великий блок, ніж робити десятки викликів. Якщо з однієї адреси стабільно йде понад 20-30 переказів на годину, блок 1d під очікуваний обсяг чистіший за виклик на кожен переказ: початкова вартість вища, але накладні витрати API і очікування підтвердження в мережі зникають з гарячого шляху.
Автентифікація і структура запиту
Ендпоінт оренди:
GET https://api.tronenergyrent.com/place-energy-order
Це звичайний GET-запит з параметрами в рядку запиту. Автентифікація це параметр apiKey, який ви генеруєте в особистому кабінеті після реєстрації та поповнення балансу. Авторизації через заголовки немає, JSON-тіла теж. Параметри:
apiKey(обов’язковий): ваш API-ключ з особистого кабінету.period(обов’язковий): тривалість оренди, одне з1h,1d,3d,30d.energyAmount(обов’язковий): скільки енергії делегувати, мінімум15000. Для одного стандартного переказу USDT одержувачу, який вже має USDT, безпечне значення65000; для першого переказу новому власнику USDT беріть130000.destinationAddress(обов’язковий): TRON-адреса (base58check, починається зT), яка отримає енергію.preActivateDestinationAddress(необов’язковий, за замовчуванням0): поставте1, якщо адреса призначення ніколи не отримувала TRX і тому не активована в мережі. Сервіс надішле на неї1.5 TRXз вашого балансу перед делегуванням. Якщо адреса вже активна, залиште0, щоб не платити зайвого.
HTTP-статус відповіді завжди 200, успішне замовлення чи ні. Розгалужуйтеся за полем status у JSON, а не за HTTP-статусом. Успішна відповідь:
{
"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"
}
}
Відповідь з помилкою має status: "ERROR", машинний errorCode і людський errorDescription:
{
"status": "ERROR",
"errorCode": "INVALID_ENERGY_AMOUNT",
"errorDescription": "energyAmount is less than 15000",
"requestId": "71431087-4",
"payload": null
}
Логуйте requestId в обох гілках: саме за ним підтримка шукатиме конкретну оренду, якщо доведеться звернутися.
Життєвий цикл замовлення
Поле state у payload проходить коротку фіксовану послідовність:
PAID_BY_USER: замовлення оплачене з вашого балансу, у мережі ще нічого не сталося.WAITING_DELEGATION: сервіс узяв замовлення і готує транзакцію делегування.ENERGY_DELEGATED: делегування потрапило в блок; адреса призначення тримає орендовану енергію і може витратити її на наступну транзакцію.ERROR_DELEGATION: делегування не вдалося. Рідко, але трапляється під час сильного перевантаження мережі.CANCELLED: замовлення скасоване, кошти повернуто на баланс.
Поточний стан:
GET https://api.tronenergyrent.com/single-order-details?apiKey=YOUR_API_KEY&orderId=ORDER_ID
Відповідь має ту саму оболонку status / errorCode / payload, а поточний state лежить у payload. Опитуйте щосекунди або кожні дві секунди після замовлення і надсилайте переказ TRC-20 лише після ENERGY_DELEGATED; на практиці це одне-два опитування.
Інтеграція на Python
Мінімальний, але придатний для продакшну шаблон: розміщує оренду, чекає, доки делегування потрапить у блок, і дає зрозумілу помилку, якщо щось пішло не так.
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
На що звернути увагу. Явна перевірка status == "SUCCESS" потрібна, бо HTTP-статус завжди 200 і сам resp.raise_for_status() про результат нічого не каже. Цикл опитування має жорсткий таймаут, щоб застрягле замовлення не блокувало конвеєр переказів назавжди. Розгалуження за state явно обробляє три кінцеві стани (ENERGY_DELEGATED, ERROR_DELEGATION, CANCELLED) замість загального «не успіх». У процесі переказу спершу викликайте rent_energy(), потім транслюйте переказ TRC-20. Порядок важливий: транслюєте першим, і транзакція спалить TRX відправника, бо делегування ще не в блоці.
Баланс
Вартість оренди списується з балансу вашого акаунта tronenergyrent.com. Налаштуйте сповіщення або автоматичне поповнення, коли баланс падає нижче порогу; розумний поріг це сума на дві години пікового обсягу. Прочитати баланс програмно:
GET https://api.tronenergyrent.com/account-info?apiKey=YOUR_API_KEY
Payload містить поточний баланс і стан акаунта. Підключіть це до моніторингу, і порожній баланс не здивує вас о другій ночі. Мінімальне поповнення балансу tronenergyrent.com становить 10 TRX.
Обробка помилок
У продакшні найчастіше трапляються три відмови. Коди нижче приходять з реального API, на них можна розгалужуватися.
INSUFFICIENT_BALANCE: балансу не вистачає на оренду плюс попередню активацію, якщо її замовлено. Не повторюйте запит, повтори тут не допоможуть. Ловіть саме цю помилку і запускайте сповіщення або поповнення; додавайтеrequestIdу payload сповіщення.INVALID_ADDRESS:destinationAddressне пройшла декодування base58check на сервері. Якщо адреси формуються динамічно, наприклад із введення користувача, перевіряйте їх локально до виклику API: у Python-бібліотеціtronpyдля цього єis_address(), і відхилити некоректний ввід на клієнті швидше, ніж чекати відповіді сервера.INACTIVE_DESTINATION_ADDRESS_ERROR: адреса призначення ніколи не активувалася в мережі, а ви не попросили сервіс її активувати. Або поповніть адресу невеликою сумою TRX з іншого джерела, або передайтеpreActivateDestinationAddress=1у наступному виклику, і сервіс активує її за1.5 TRX.
Тонший випадок: ORDER_IS_ALREADY_IN_PROGRESS повертається, коли кілька воркерів одночасно замовляють оренду на одну адресу. Це виправляється на вашому боці, не в API: візьміть розподілене блокування (підійде Redis) за адресою призначення і тримайте його до завершення делегування.
Перевірка в мережі
Більшості інтеграцій достатньо опитувати /single-order-details до ENERGY_DELEGATED. Для підстраховки після делегування можна звернутися і до повної ноди TRON:
GET https://api.trongrid.io/v1/accounts/{destinationAddress}
Відповідь містить стан ресурсів адреси, разом з енергією, делегованою їй іншими адресами. Точна назва поля залежить від поточного подання Stake 2.0, тому звіряйтеся з актуальною документацією HTTP API TRON. Як м’яка перевірка, яка пише попередження в лог, а не блокує переказ, це корисний індикатор для рідкісного випадку, коли оренда в API виглядає успішною, а в мережі щось пішло не так. Саме в такий єдиний раз вона заощадить вам години розбору.