Як автоматизувати оренду енергії TRON через API

2026-05-13

Навіщо автоматизувати

Якщо ви тримаєте гарячий гаманець, сервіс виведення коштів на біржі або контракт, який робить перекази 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, на них можна розгалужуватися.

  1. INSUFFICIENT_BALANCE: балансу не вистачає на оренду плюс попередню активацію, якщо її замовлено. Не повторюйте запит, повтори тут не допоможуть. Ловіть саме цю помилку і запускайте сповіщення або поповнення; додавайте requestId у payload сповіщення.
  2. INVALID_ADDRESS: destinationAddress не пройшла декодування base58check на сервері. Якщо адреси формуються динамічно, наприклад із введення користувача, перевіряйте їх локально до виклику API: у Python-бібліотеці tronpy для цього є is_address(), і відхилити некоректний ввід на клієнті швидше, ніж чекати відповіді сервера.
  3. 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 виглядає успішною, а в мережі щось пішло не так. Саме в такий єдиний раз вона заощадить вам години розбору.

Хочете зекономити на комісіях TRON? Перевірте ціни на енергію зараз. Розрахувати ціну
Назад до блогу