Ваш продукт. Наша энергия.

1. Рассчитайте цену

POST https://api.tronteo.com/api/v1/quotes
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{"receiver":"YOUR_TRON_ADDRESS","resource":"ENERGY","quantity":65000,"duration":3600,"currency":"TRX"}

duration — срок в секундах: Energy — 3600; Bandwidth — 3600, 86400 или 259200. По умолчанию 3600. Котировка действует 60 секунд. total — десятичная строка в TRX. Оплата только с баланса TRX. Адрес должен быть активирован в TRON.

2. Подтвердите аренду

POST https://api.tronteo.com/api/v1/orders
Authorization: Bearer YOUR_API_KEY
Idempotency-Key: unique-order-001
Content-Type: application/json

{"quote_id":"QUOTE_ID","max_amount":5000000}

max_amount задаётся в SUN: 1 TRX = 1 000 000 SUN. Повтор с тем же ключом и неизменными quote_id и max_amount возвращает исходный заказ.

3. Проверьте результат

GET https://api.tronteo.com/api/v1/orders/ORDER_ID
Authorization: Bearer YOUR_API_KEY

Делегирование завершено только при status=confirmed. При review средства остаются в резерве до сверки; не повторяйте покупку новым ключом.

Telegram-боты и приложения

API предназначен для интеграций приложений и ботов, в том числе аренды ресурсов на адреса конечных пользователей. Специальной технической роли reseller или отдельной активации таких заказов нет. API-ключ и сервисный баланс принадлежат вашему аккаунту; храните ключ только на сервере. Стандартные условия допустимого использования распространяются на вас и адреса получателей. Отдельные коммерческие гарантии, SLA или специальные условия перепродажи требуют согласования с поддержкой.

4. Бесплатный sandbox

Для тестирования используйте отдельный базовый URL и свой обычный API-ключ. Sandbox выдаёт виртуальные 1000 TRX на аккаунт. Реальные средства, заказы, поставщики и блокчейн не используются. Цены фиксированы для примера и не являются предложением аренды.

https://api.tronteo.com/api/v1/sandbox

POST /quotes
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{"receiver":"YOUR_TRON_ADDRESS","resource":"ENERGY","quantity":65000,"duration":3600,"scenario":"confirmed"}

POST /orders
Idempotency-Key: telegram-test-001
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{"quote_id":"SANDBOX_QUOTE_ID","max_amount":2000000}

GET /orders/ORDER_ID
GET /orders?idempotency_key=telegram-test-001
GET /balance

Методы совпадают с обычной арендой. scenario: confirmed, failed или review. Созданный заказ имеет reserved; первый запрос деталей переводит его в pending, второй — в выбранный результат. Список заказов состояние не меняет. Все ответы котировок и заказов имеют simulated=true; txid пустой, txids=[], delegation_verified=false даже при simulated confirmed.

Начальный баланс не пополняется и не сбрасывается автоматически. До 1000 заказов и 1000 неистёкших котировок на аккаунт. При failed резерв возвращается, при review остаётся. Для повторения используйте новый тестовый заказ; не переключайтесь на production.

Форматы ответов

Примеры ниже вымышленные. Денежные значения total, available, reserved — строки TRX с 6 знаками после точки. max_amount и поля *_sun — целые SUN: 1 TRX = 1 000 000 SUN. quantity — целое число единиц ресурса; duration — секунды. created, updated, expires, resets_at — Unix-время UTC в секундах. Не используйте float для денежных расчётов.

POST /quotes → 200

{
  "id": "quote_example",
  "receiver": "YOUR_TRON_ADDRESS",
  "resource": "ENERGY",
  "quantity": 65000,
  "currency": "TRX",
  "total": "2.000000",
  "expires": 1793635260,
  "duration": 3600,
  "simulated": false
}

POST /orders · GET /orders/ORDER_ID → 200

{
  "id": "order_example",
  "receiver": "YOUR_TRON_ADDRESS",
  "resource": "ENERGY",
  "quantity": 65000,
  "duration": 3600,
  "currency": "TRX",
  "total": "2.000000",
  "status": "reserved",
  "txid": "",
  "txids": [],
  "delegation_verified": false,
  "created": 1793635200,
  "updated": 1793635200,
  "channel": "api",
  "bundle_id": null,
  "idempotency_key": "telegram-order-001",
  "error_code": null,
  "simulated": false
}

idempotency_key доступен во всех ответах заказа. error_code — null или безопасный код причины; технические данные поставщиков не раскрываются. txid — первый хеш делегации для совместимости, txids — все сохранённые хеши. У исторических заказов может быть только первый хеш.

GET /orders?offset=0&limit=50 → 200

{
  "orders": [
    {
      "id": "order_example",
      "receiver": "YOUR_TRON_ADDRESS",
      "resource": "ENERGY",
      "quantity": 65000,
      "duration": 3600,
      "currency": "TRX",
      "total": "2.000000",
      "status": "reserved",
      "txid": "",
      "txids": [],
      "delegation_verified": false,
      "created": 1793635200,
      "updated": 1793635200,
      "channel": "api",
      "bundle_id": null,
      "idempotency_key": "telegram-order-001",
      "error_code": null,
      "simulated": false
    }
  ]
}

Сортировка: новые сначала, затем id; offset ≥ 0, limit от 1 до 100 (по умолчанию 50). Фильтр idempotency_key ищет точное совпадение в вашем аккаунте; отсутствие результата — {"orders":[]}.

GET /balance → 200

[
  {
    "asset": "TRX",
    "available": "98.000000",
    "reserved": "2.000000"
  }
]

available можно потратить, reserved удерживается активными заказами. Подтверждённый заказ списывает резерв; failed возвращает всю сумму заказа в available; review ничего не возвращает до сверки. Это сервисные кредиты, не баланс блокчейн-кошелька.

Повторы, таймауты и хранение ключей

Idempotency-Key: от 1 до 100 символов, один уникальный ключ на бизнес-операцию. Область уникальности — аккаунт, включая разные API-ключи и каналы. Автоматического срока удаления ключей нет: они сохраняются с заказом; это не обещание бессрочного хранения. Сохраняйте свой ключ и id заказа.

Повтор с теми же quote_id и max_amount возвращает тот же заказ, в том числе после истечения котировки. Изменение quote_id или max_amount (включая null/отсутствие) даёт 409 idempotency_conflict. Для исторических заказов без снимка параметров проверяются quote_id и новый потолок суммы. Разные ключи могут создавать разные платные заказы даже по одной котировке.

GET /orders?idempotency_key=YOUR_ORIGINAL_KEY

После таймаута сначала выполните поиск по исходному ключу. Если заказа нет, повторяйте исходный запрос с исходным ключом и параметрами; 409 quote_expired требует новой котировки. Не создавайте замену новым ключом, пока исходный результат не выяснен.

Состояния и проверка делегации

reserved

Сумма зарезервирована, заказ ожидает обработки.

submitting

Запрос передаётся поставщику; результат ещё может быть неизвестен.

pending

Заказ принят, ожидается подтверждение делегации.

review

Нужна ручная сверка; это не отказ и не возврат.

confirmed

Финальный успех; резерв списан.

failed

Финальный отказ; полный резерв возвращён, повтор того же ключа не создаёт заказ.

refund_due

Ручной возврат для аренды без аккаунта; обычные API-заказы используют failed.

Для production сверяйте receiver, resource, quantity, duration, status, delegation_verified и txids. confirmed ставится после успешной подтверждённой сетевой делегации указанного ресурса получателю. quantity — заказанное число единиц, не поле стейка в контракте TRON: stake balance нельзя напрямую сравнивать с Energy. Несколько делегаций могут обслуживать один заказ.

Опрос раз в 5–10 секунд достаточен. При review не повторяйте покупку; передайте поддержке id заказа, исходный ключ и txids, если они есть. Средства остаются в резерве до сверки. Публичного метода принудительного подтверждения или возврата нет; предельный срок сверки не гарантируется.

Лимиты и ошибки

GET /limits

{
  "daily_limit_sun": 100000000,
  "used_sun": 2000000,
  "remaining_sun": 98000000,
  "resets_at": 1793664000,
  "rate_limit_per_minute": 300,
  "scope": "account; all API keys share usage; UTC calendar day"
}

Дневной расход — сумма розничных total всех API-заказов аккаунта за календарный день UTC, кроме failed. confirmed, активные и review учитываются; применяется лимит используемого ключа. Сброс в 00:00 UTC. 300 авторизованных запросов за фиксированную минуту на аккаунт, совместно для всех ключей и sandbox; отклонённые транзакции могут не расходовать квоту. При 429 используйте Retry-After и задержку со случайным разбросом.

{
  "detail": "Idempotency key was used for another request",
  "code": "idempotency_conflict"
}

{
  "detail": "Проверьте введённые данные / Please check your input",
  "code": "invalid_request",
  "fields": [
    "quantity"
  ]
}

401 — авторизация; 403 — доступ или дневной лимит; 404 — объект не найден в аккаунте; 409 — конфликт ключа, истёкшая цена, потолок суммы или баланс; 422 — данные; 429 — частота; 500/503 — временная ошибка. code предназначен для программы, detail — для человека и может быть двуязычным. Ошибка/таймаут создания не доказывает отсутствие заказа: сначала сверяйте исходный ключ.