Как автоматизировать аренду энергии TRON через API
Если у вас горячий кошелёк, движок вывода средств биржи или контракт, который переводит TRC-20 от имени пользователей, энергия TRON нужна ровно в ту секунду, когда уходит транзакция. Пополнять её вручную через интерфейс получается разве что для пары переводов в день; не успели, и транзакция сожжёт TRX с адреса отправителя, обычно заметно дороже, чем стоила бы заранее арендованная энергия. Выход: вызывать API аренды в момент, когда бэкенд собирается отправить транзакцию, чтобы энергия выделялась программно, без человека в цепочке. Ниже структура запроса к tronenergyrent.com, жизненный цикл заказа, выбор срока и рабочий пример на Python.
Что 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-запрос с query-параметрами. Аутентификация через параметр 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, а не по статусу. Успешный ответ:
{
"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 приходит текущий баланс и состояние аккаунта. Подключите это к мониторингу, и пустой баланс в 2 ночи больше не станет сюрпризом. Минимальное пополнение баланса tronenergyrent.com составляет 10 TRX.
Ошибки на практике
В продакшене чаще всего встречаются три. Коды ниже приходят из реального API, по ним можно ветвить логику.
INSUFFICIENT_BALANCE: предоплаченного баланса не хватает на аренду плюс возможную преактивацию. Повтор запроса не поможет: ловите этот код отдельно и запускайте оповещение или пополнение, добавив в негоrequestId.INVALID_ADDRESS:destinationAddressне прошёл декодирование base58check на сервере. Если адреса приходят динамически, например из пользовательского ввода, проверяйте их локально перед вызовом: у библиотекиtronpyдля Python есть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, так что при подключении сверяйтесь с актуальной документацией TRON HTTP API. Как мягкая проверка, которая пишет предупреждение в лог, а не блокирует перевод, она сэкономит часы отладки в тот редкий раз, когда аренда в API выглядит успешной, а в блокчейне что-то пошло не так.