TronBid Quick Rent API

Обзор: что это и кому нужно

Quick Rent API — это способ автоматически, без ручной работы, арендовать энергию сети TRON. Энергия нужна, чтобы переводы USDT (TRC-20) и другие операции со смарт-контрактами стоили дешевле, чем при сжигании TRX.

Простыми словами: ваша программа (сайт, бот, сервис) сама покупает энергию тогда, когда она нужна — например, перед каждым переводом USDT вашего клиента.

Представьте автомат с напитками: смотрите цену, кидаете деньги, получаете товар. API — это те же кнопки автомата, только нажимает их ваша программа.

Словарь терминов

Короткие объяснения слов, которые встречаются в этой документации.

Перед стартом

Что нужно подготовить, прежде чем делать первый запрос.

Введение

Quick Rent API позволяет вашему сервису автоматически арендовать TRON Energy, чтобы переводы USDT TRC-20 и другие вызовы смарт-контрактов обходились дешевле, чем сжигание TRX.

Все эндпоинты используют один base URL.

https://tronbid.com/api/v2/quick-rent

Авторизация

Каждый запрос должен содержать ваш API-ключ как Bearer-токен в заголовке Authorization.

Храните ключ только на своей стороне (сервер, секреты CI). Не вставляйте его во фронтенд и публичные репозитории. Ключ привязан к одному аккаунту TronBid (кошелёк, указанный при выдаче доступа); списание с баланса возможно только с этого аккаунта.

При превышении лимита запросов API отвечает HTTP 429.

Authorization: Bearer <API_KEY>

Режимы оплаты

Оплатить заказ можно двумя способами. On-chain — по умолчанию, не требует настройки. Оплата с баланса — опциональна и должна быть включена для вашего ключа.

Без активации запрос с payment_mode: balance вернёт 403 BALANCE_PAYMENT_NOT_ENABLED. Для подключения обратитесь в поддержку TronBid.

Каталог пакетов

energy_amount и duration_minutes должны соответствовать активному пакету Quick Rent — обычно 65000 или 131000 энергии и 15 или 60 минут.

Актуальный каталог можно получить в любой момент (без авторизации):

curl -sS https://tronbid.com/api/public/quick-rent/skus

Быстрый старт: от нуля до энергии

Полный сквозной пример на самом простом сценарии (on-chain). Четыре шага — и энергия на кошельке.

Ниже — что происходит на каждом шаге и что возвращает API. Подставьте свой API-ключ, адреса и ID заказа.

{
  "price_trx": "3.200000",
  "available": true,
  "save_percent": 62,
  "expires_in_sec": 30
}

{
  "id": "uuid",
  "status": "pending_payment",
  "payment_mode": "onchain",
  "pay_address": "TDeposit...",
  "amount_trx": "3.200000",
  "energy_amount": 131000,
  "duration_minutes": 15,
  "expires_at": "2026-04-29T13:15:00.000Z",
  "qr_payload": "tron:TDeposit...?amount=3.200000",
  "duplicate": false,
  "target_address": "TTarget..."
}

# poll every 3s until the order is done
while true; do
  STATUS=$(curl -sS "$BASE_URL/api/v2/quick-rent/orders/$ORDER_ID" \
    -H "Authorization: Bearer $API_KEY" | jq -r .status)
  echo "status: $STATUS"
  case "$STATUS" in
    delegated|failed|expired|cancelled) break ;;
  esac
  sleep 3
done

{
  "id": "uuid",
  "status": "delegated",
  "payment_mode": "onchain",
  "amount_trx": "3.200000",
  "energy_amount": 131000,
  "effective_energy_amount": 131000,
  "duration_minutes": 15,
  "pay_address": "TDeposit...",
  "payer_address": "TPayer...",
  "target_address": "TTarget...",
  "error_code": null,
  "error_message": null
}

Сценарий on-chain

Шаг 1 — POST /quote, узнать цену. Шаг 2 — POST /orders, создать заказ и получить pay_address, amount_trx и expires_at. Шаг 3 — отправить ровно amount_trx TRX на pay_address с вашего payer_address. Шаг 4 — периодически опрашивать GET /orders/:id до статуса delegated (или failed / expired / cancelled).

target_address опционален — если не передан, энергия делегируется на payer_address.

Для одного payer_address одновременно допустим только один незакрытый on-chain заказ (pending_payment), иначе — 409 PENDING_PAYMENT_INTENT_EXISTS. При недоплате/переплате итоговый объём может отличаться — смотрите effective_energy_amount в GET /orders/:id.

{
  "energy_amount": 131000,
  "duration_minutes": 15,
  "idempotency_key": "your-unique-key-001",
  "payer_address": "TPayerWalletXXXXXXXXXXXXXXXXXXXXXX",
  "target_address": "TTargetWalletXXXXXXXXXXXXXXXXXXXXX"
}

{
  "id": "uuid",
  "status": "pending_payment",
  "payment_mode": "onchain",
  "pay_address": "TDeposit...",
  "amount_trx": "3.200000",
  "energy_amount": 131000,
  "duration_minutes": 15,
  "expires_at": "2026-04-29T13:15:00.000Z",
  "qr_payload": "tron:TDeposit...?amount=3.200000",
  "duplicate": false,
  "target_address": "TTarget..."
}

Сценарий с баланса

Шаг 1 — GET /balance, проверить остаток TRX. Шаг 2 — POST /quote, узнать цену. Шаг 3 — POST /orders с payment_mode: balance — списание и старт делегирования. Шаг 4 — опрашивать GET /orders/:id до delegated (при ошибке делегирования статус failed, TRX возвращается на баланс).

payer_address не нужен — платит аккаунт, привязанный к вашему API-ключу. energy_amount в ответе может быть выше заказанного SKU (бонус матрицы цен).

{
  "energy_amount": 131000,
  "duration_minutes": 15,
  "idempotency_key": "your-unique-key-balance-001",
  "payment_mode": "balance",
  "target_address": "TTargetWalletXXXXXXXXXXXXXXXXXXXXX"
}

{
  "id": "uuid",
  "status": "delegating",
  "payment_mode": "balance",
  "pay_address": null,
  "amount_trx": "3.200000",
  "energy_amount": 132310,
  "duration_minutes": 15,
  "expires_at": null,
  "qr_payload": null,
  "duplicate": false,
  "target_address": "TTarget..."
}

Статусы заказа

Каждый заказ проходит через эти статусы. Отслеживайте его через GET /orders/:id.

Идемпотентность

idempotency_key (8–128 символов) — уникальный ID заказа на вашей стороне. Повтор POST /orders с тем же ключом (для того же API-клиента) вернёт тот же заказ с "duplicate": true.

Не используйте один idempotency_key для разных режимов оплаты (onchain vs balance) — будет 409 IDEMPOTENCY_PAYMENT_MODE_MISMATCH.

Калькулятор

Оцените, сколько энергии нужно адресу для перевода. Передайте кошелёк получателя и признак наличия у него USDT.

{
  "wallet_address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "has_usdt": true
}

curl -sS -X POST "$BASE_URL/api/v2/quick-rent/calculator" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"wallet_address":"TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX","has_usdt":true}'

Расчёт цены

Возвращает текущую цену пакета: price_trx, доступность, save_percent и срок действия расчёта (expires_in_sec).

{
  "price_trx": "3.200000",
  "available": true,
  "save_percent": 62,
  "expires_in_sec": 30
}

export BASE_URL="https://tronbid.com"
export API_KEY="your_api_key"

curl -sS -X POST "$BASE_URL/api/v2/quick-rent/quote" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"energy_amount":131000,"duration_minutes":15}'

Создание заказа

Создаёт заказ на аренду. Для on-chain передайте payer_address и оплатите полученный amount_trx на pay_address. Для баланса добавьте payment_mode: balance — привязанный аккаунт списывается сразу.

target_address опционален (по умолчанию payer_address). Учитывайте правила 409: один незакрытый on-chain заказ на payer и отсутствие активной делегации Quick Rent на target (ACTIVE_DELEGATION_EXISTS).

{
  "id": "uuid",
  "status": "pending_payment",
  "payment_mode": "onchain",
  "pay_address": "TDeposit...",
  "amount_trx": "3.200000",
  "energy_amount": 131000,
  "duration_minutes": 15,
  "expires_at": "2026-04-29T13:15:00.000Z",
  "qr_payload": "tron:TDeposit...?amount=3.200000",
  "duplicate": false,
  "target_address": "TTarget..."
}

{
  "id": "uuid",
  "status": "delegating",
  "payment_mode": "balance",
  "pay_address": null,
  "amount_trx": "3.200000",
  "energy_amount": 132310,
  "duration_minutes": 15,
  "expires_at": null,
  "qr_payload": null,
  "duplicate": false,
  "target_address": "TTarget..."
}

curl -sS -X POST "$BASE_URL/api/v2/quick-rent/orders" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "energy_amount": 131000,
    "duration_minutes": 15,
    "idempotency_key": "partner-onchain-001",
    "payer_address": "TPayer...",
    "target_address": "TTarget..."
  }'

curl -sS -X POST "$BASE_URL/api/v2/quick-rent/orders" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "energy_amount": 131000,
    "duration_minutes": 15,
    "idempotency_key": "partner-balance-001",
    "payment_mode": "balance",
    "target_address": "TTarget..."
  }'

Статус заказа

Возвращает актуальный статус, payment_mode, суммы, адреса и error_code / error_message при сбое. effective_energy_amount отражает реально делегированную энергию после недоплаты/переплаты.

{
  "id": "uuid",
  "status": "delegated",
  "payment_mode": "onchain",
  "amount_trx": "3.200000",
  "energy_amount": 131000,
  "effective_energy_amount": 131000,
  "duration_minutes": 15,
  "pay_address": "TDeposit...",
  "payer_address": "TPayer...",
  "target_address": "TTarget...",
  "error_code": null,
  "error_message": null
}

curl -sS "$BASE_URL/api/v2/quick-rent/orders/$ORDER_ID" \
  -H "Authorization: Bearer $API_KEY"

Отмена заказа

Отменяет заказ, который ещё в статусе pending_payment (только on-chain). После делегирования энергии заказ отменить уже нельзя.

curl -sS -X POST "$BASE_URL/api/v2/quick-rent/orders/$ORDER_ID/cancel" \
  -H "Authorization: Bearer $API_KEY"

Смена плательщика

Меняет кошелёк оплаты для on-chain заказа в статусе pending_payment — удобно, если клиент решил заплатить с другого кошелька до отправки TRX.

curl -sS -X POST "$BASE_URL/api/v2/quick-rent/orders/$ORDER_ID/set-payer" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payer_address":"TNewPayer..."}'

Баланс

Возвращает баланс TRX аккаунта TronBid, привязанного к вашему API-ключу (баланс в кабинете, не on-chain кошелёк). Требует заголовок Authorization.

{ "balance_trx": "150.500000" }

curl -sS "$BASE_URL/api/v2/quick-rent/balance" \
  -H "Authorization: Bearer $API_KEY"

Коды ошибок

Ошибки возвращают HTTP-статус и поле error. Ниже — те, что вы можете встретить.

Если что-то пошло не так

Частые ситуации и что делать простыми словами.

Поддержка

Нужен доступ к API, повышенные лимиты или включение оплаты с баланса? Напишите нам — поможем.