API аренды энергии TRON для ботов и бэкенд-сервисов

Автоматическая аренда энергии TRON позволяет Telegram-ботам, платёжным процессорам и сервисам автоматических выплат отправлять USDT TRC20 без ручного управления стейкингом TRX и без сжигания TRX на газ. Вместо того чтобы строить собственную инфраструктуру стейкинга или замораживать оборотные средства на 14 дней, разработчики ботов подключаются к REST API, который по запросу делегирует энергию в сети через Stake 2.0^[3].

Подключение проходит пять шагов жизненного цикла^[1]: мгновенная оценка стоимости, подпись запросов HMAC-SHA256^[2], котировка с фиксированной на 120 секунд ценой, идемпотентный заказ с собственным client_order_id и подтверждение делегирования через подписанные вебхуки.

Пять шагов подключения бота

Наш REST API даёт предсказуемый порядок работы, рассчитанный на автоматические бэкенды:

[Bot / Server]                      [Energy API]                      [TRON Chain]
       |                                   |                                |
       |--- 1. GET /v1/estimate ---------->|                                |
       |<-- Returns total SUN & price -----|                                |
       |                                   |                                |
       |--- 2. POST /v1/quotes ----------->|                                |
       |<-- Returns quote_id (120s lock) --|                                |
       |                                   |                                |
       |--- 3. POST /v1/orders ----------->|                                |
       |<-- 201 Created (ord_...) ---------|--- delegateResource ---------->|
       |                                   |                                |
       |<-- 4. Webhook: order.confirmed ---|<-- Confirmed in block ---------|
       |                                   |                                |
       |--- 5. Broadcast USDT transfer ------------------------------------>|

1. Оценка стоимости заказа без ключей

Чтобы показать пользователям бота цену сразу или рассчитать комиссию за перевод, запросите GET /v1/estimate^[1]. Этот публичный эндпоинт не требует API-ключа:

curl -sG https://api.tenergy.me/v1/estimate \
  -d resource=energy -d amount=65000 -d tier=1h \
  -d receiver=TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE

В ответе приходят total_amount_sun, price_sun_per_unit и признак того, активирован ли кошелёк получателя в сети.

2. Подпись запросов HMAC-SHA256

Все эндпоинты с аутентификацией требуют трёх HTTP-заголовков^[2]:

• X-API-KEY: идентификатор вашего ключа (ak_live_... или ak_test_...).
• X-API-TIMESTAMP: метка времени ISO 8601 в UTC (допуск 5 секунд).
• X-API-SIGN: base64(HMAC-SHA256(secret, timestamp + METHOD + path + query + body)).

3. Фиксация цены котировкой на 120 секунд

Чтобы цена не изменилась, пока пользователь общается с ботом, вызовите POST /v1/quotes^[1]. Котировка фиксирует итоговую стоимость на 120 секунд:

{
  "resource": "energy",
  "amount": 65000,
  "tier": "1h",
  "receiver": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
}

4. Идемпотентный заказ

Передайте quote_id и свой client_order_id в POST /v1/orders^[1]. Если соединение прервалось или запрос завершился по таймауту, повторите тот же вызов: система определяет client order ID и возвращает существующий заказ без повторного списания.

{
  "quote_id": "qt_01J9Z5NB2K4R",
  "client_order_id": "bot-order-94812"
}

5. Подтверждение делегирования в сети

Перед отправкой перевода USDT бот должен дождаться подтверждения:

• Вебхуки: укажите HTTPS-адрес в личном кабинете. Когда делегирование подтверждено в сети, система присылает событие order.confirmed, подписанное HMAC-SHA256^[2].
• Опрос: как запасной вариант опрашивайте GET /v1/orders/cid:bot-order-94812 каждые 1–2 секунды, пока status не станет active после delegateResource в сети^[3].

Эндпоинты API

Практики архитектуры для разработчиков ботов

1. Раздельные окружения: разрабатывайте и отлаживайте сценарии бота на нашем эндпоинте тестовой сети Nile (https://api-nile.tenergy.me/v1). Тестовые ключи имеют префикс ak_test_ и полностью изолированы от рабочих аккаунтов.
2. Ключ идемпотентности на каждый заказ: генерируйте отдельный client_order_id для каждого уникального действия пользователя. Это исключает случайное двойное списание при сетевых сбоях.
3. Проверка частичного исполнения: смотрите булево поле partial в записи заказа. Если предложения не хватает, заказ может исполниться частично; остаток возвращается автоматически.
4. Отправка после подтверждения: дождитесь вебхука order.confirmed или статуса active, прежде чем отправлять зависящую от него транзакцию USDT TRC20 в мейннете TRON.

Технические подробности — в полном руководстве Quickstart, справочнике по аутентификации и документации API.