POST /apiv2/order5m

Создать заказ на 5-минутную аренду энергии через внутренние пулы энергии Netts.

URL эндпоинта

POST https://netts.io/apiv2/order5m

Заголовки запроса

Заголовок	Обязательный	Описание
Content-Type	Да	application/json
X-API-KEY	Да	Ваш API-ключ из панели управления Netts
X-Real-IP	Да	IP-адрес из вашего белого списка

Тело запроса

json

{
    "amount": 65000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
}

Параметры запроса

Параметр	Тип	Обязательный	Описание
amount	integer	Да	Количество энергии для аренды (минимум: 61 000, максимум: 650 000)
receiveAddress	string	Да	Адрес TRON, который получит энергию (формат TRC-20)

Ограничения по энергии

Эндпоинт на 5 минут принимает объемы энергии от 61 000 до 650 000 единиц на заказ. Запросы вне этого диапазона будут отклонены с ошибкой HTTP 400.

Информация о провайдерах

Заказы энергии на 5 минут выполняются исключительно через внутренние пулы энергии Netts. В отличие от эндпоинта на 1 час, внешние провайдеры не используются.

Доступность и стратегия повторных попыток

Поскольку делегирование происходит только из внутренних пулов, в периоды высокого спроса возможна временная недоступность. Если вы получаете ошибку 503, повторите запрос после небольшой задержки или переключитесь на эндпоинт на 1 час, который имеет доступ к нескольким внешним провайдерам.

Примеры

cURL

bash

curl -X POST https://netts.io/apiv2/order5m \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key" \
  -H "X-Real-IP: your_whitelisted_ip" \
  -d '{
    "amount": 65000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
  }'

Python

python

import requests

url = "https://netts.io/apiv2/order5m"
headers = {
    "Content-Type": "application/json",
    "X-API-KEY": "your_api_key",
    "X-Real-IP": "your_whitelisted_ip"
}

payload = {
    "amount": 65000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()

if response.status_code == 200:
    detail = data.get('detail', {})
    order_data = detail.get('data', {})
    print(f"Order ID: {order_data.get('orderId')}")
    print(f"Transaction Hash: {order_data.get('hash')}")
    print(f"Energy Delivered: {order_data.get('energy')}")
    print(f"Cost: {order_data.get('paidTRX')} TRX")
    print(f"Delegate Address: {order_data.get('delegateAddress')}")
elif response.status_code == 503:
    # Pool temporarily unavailable - retry or fallback to 1h
    print("Pool busy, retrying in 2 seconds...")
else:
    error_detail = data.get('detail', data)
    print(f"Error Code: {error_detail.get('code', 'N/A')}")
    print(f"Error Message: {error_detail.get('msg', error_detail)}")

Ответ

Успешный ответ (200 OK)

json

{
    "detail": {
        "code": 10000,
        "msg": "Successful, 1.430 TRX deducted",
        "data": {
            "orderId": "5Mb4ee11ef86",
            "paidTRX": 1.43,
            "hash": "3636f97dde244fca17cdc0b2cf7fd157...",
            "delegateAddress": "TNp5gsJhBmZFXgCdgjMgr8pEZ8fHgXUHDq",
            "energy": 65050
        }
    }
}

Успех с активацией адреса (200 OK)

Если адрес получателя не был активирован в сети TRON, Netts активирует его автоматически. Стоимость активации добавляется к общей сумме:

json

{
    "detail": {
        "code": 10000,
        "msg": "Successful, 1.430 TRX for energy + 1.100 TRX for address activation",
        "data": {
            "orderId": "5Mb4ee11ef86",
            "paidTRX": 2.53,
            "hash": "3636f97dde244fca17cdc0b2cf7fd157...",
            "delegateAddress": "TNp5gsJhBmZFXgCdgjMgr8pEZ8fHgXUHDq",
            "energy": 65050,
            "activationHash": "bab38070a64b237acc9110ecf5135acc..."
        }
    }
}

Поля ответа

Поле	Тип	Описание
detail.code	integer	Всегда `10000` для успешных заказов
detail.msg	string	Сообщение об успешном выполнении со списанной суммой
detail.data.orderId	string	Унифицированный идентификатор заказа (формат: `5M{id}`)
detail.data.paidTRX	number	Общая стоимость в TRX (включает комиссию за активацию, если применимо)
detail.data.hash	string	Хеш транзакции делегирования
detail.data.delegateAddress	string	Адрес пула, который делегировал энергию
detail.data.energy	integer	Количество энергии + буфер (обычно +50)
detail.data.activationHash	string	Присутствует только в том случае, если была выполнена активация адреса

Ответы с ошибками

Недопустимое количество энергии (400)

json

{
    "code": 1003,
    "msg": "Energy amount must be between 61000 and 650000. Requested: 50000"
}

Ошибка аутентификации (401)

json

{
    "detail": "Invalid API key or IP not in whitelist"
}

Недостаточный баланс (403)

json

{
    "code": 1004,
    "msg": "Insufficient funds. Required: 1.43 TRX, Available: 0.50 TRX"
}

Сервис недоступен (503)

json

{
    "code": 5003,
    "msg": "Service temporarily unavailable. Energy delegation failed after retries."
}

Обработка ошибок 503

Ответ 503 означает, что внутренние пулы временно перегружены. Рекомендуемая стратегия:

Подождите 2–3 секунды и повторите попытку заказа на 5 минут
Если он по-прежнему недоступен, переключитесь на эндпоинт на 1 час, использующий несколько провайдеров

Внутренняя ошибка сервера (500)

json

{
    "code": 5000,
    "msg": "Internal server error occurred"
}

Справочник кодов ошибок

Код	Описание	HTTP-статус
`10000`	Успешно	200
`10000`	Успешно (кэшированный ответ)	208
`-`	Повторный запрос все еще обрабатывается	409
`1003`	Количество энергии вне диапазона	400
`1004`	Недостаточный баланс	403
`1005`	Адрес плательщика пользователя не настроен	400
`5000`	Внутренняя ошибка сервера	500
`5003`	Сервис энергии недоступен	503

Ограничения частоты запросов

Для этого эндпоинта действуют следующие ограничения частоты запросов (на один IP-адрес):

Период	Лимит	Описание
1 секунда	50 запросов	Максимум 50 запросов в секунду

Заголовки ограничения частоты запросов

http

RateLimit-Limit: 50
RateLimit-Remaining: 49
RateLimit-Reset: 1
X-RateLimit-Limit-Second: 50
X-RateLimit-Remaining-Second: 49

Превышение лимита запросов (429)

json

{
    "message": "API rate limit exceeded"
}

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

API поддерживает идемпотентность для предотвращения повторной обработки заказов. При отправке нескольких одинаковых запросов система гарантирует, что заказ будет обработан только один раз.

Как работает идемпотентность

Уникальность запроса определяется комбинацией следующих параметров:

Временная метка запроса (2-секундное окно)
Количество энергии
Адрес получателя
API-ключ

Каждому запросу выделяется 2-секундное окно уникальности. Запросы с идентичными параметрами внутри этого окна считаются дубликатами.

Передача собственного ключа

Вы можете взять управление идемпотентностью в свои руки, передав заголовок X-Idempotency-Key. Если он присутствует, решение о том, является ли запрос повторным, принимается исключительно на основе этого значения, а автоматическая комбинация выше не используется. Если он отсутствует, ничего не меняется — сервер формирует ключ за вас.

Правила такие же, как и для /apiv2/order1h:


Заголовок	`X-Idempotency-Key`
Формат	Ровно 64 шестнадцатеричных символа в нижнем регистре — дайджест SHA-256
Срок жизни	24 часа с момента первого запроса с этим ключом
Область действия	Ваш аккаунт. То же значение, отправленное другим аккаунтом, никогда не вернет ваш результат

Ключ любого другого формата — UUID с дефисами, base64, шестнадцатеричный в верхнем регистре — отклоняется с ошибкой 400 до размещения заказа и до списания средств:

json

{
    "detail": "Invalid idempotency key format. Must be 64-character hexadecimal string."
}

Сформируйте ключ на основе вашего API-ключа, чтобы он был уникальным для вашего аккаунта и воспроизводимым при повторной попытке — практический пример приведен на странице заказа на 1 час. Включите период аренды в хэшируемое сообщение: аренда на один и тот же адрес на 5 минут и на 1 час — это разные заказы, и повторное использование одного ключа для обоих вернет ответ первого заказа для второго запроса.

Размещение двух одинаковых заказов

Та же ловушка, что и на почасовом эндпоинте, но с более широким окном. Два одинаковых заказа — на одну и ту же сумму на один и тот же адрес — неотличимы от повторной попытки, и разделяет их только момент поступления.

Без собственного ключа:

Интервал между двумя запросами	Что происходит
В пределах одного 2-секундного окна	Второй запрос принимается за повтор. Он не выполняется: вы получаете `208` и ответ первого заказа. Списания средств за него не происходит
С интервалом более двух секунд	Два разных ключа — оба заказа размещаются и оба оплачиваются

Поэтому делайте паузу более двух секунд между двумя одинаковыми заказами и проверяйте статус-код: 208 означает, что отправленный вами заказ размещен не был.

Пауза — это обходное решение, а не исправление: она также разделяет запросы, которые вы вовсе не собирались повторять (например, повторную попытку после таймаута или повторную доставку сообщения из вашей очереди), и каждый из них становится отдельным заказом с отдельной оплатой. Отправка собственного ключа — вот что действительно решает проблему: новый nonce для нового заказа, nonce первой попытки — для повтора. Полное обоснование приведено на странице заказа на 1 час.

HTTP-статусы для повторных запросов

Код статуса	Название	Описание
200	OK	Заказ успешно обработан (первый запрос)
208	Already Reported	Заказ уже был обработан, возвращается кэшированный ответ
409	Conflict	Запрос в данный момент обрабатывается, не повторяйте попытку

Повторный запрос — уже обработан (208)

json

{
    "detail": {
        "code": 10000,
        "msg": "Successful, 1.430 TRX deducted",
        "data": {
            "hash": "3636f97dde244fca17cdc0b2cf7fd157...",
            "energy": 65050,
            "orderId": "5Mb4ee11ef86",
            "paidTRX": 1.43,
            "delegateAddress": "TNp5gsJhBmZFXgCdgjMgr8pEZ8fHgXUHDq"
        }
    },
    "idempotency": {
        "status": "completed",
        "cached": true,
        "original_created_at": "2026-03-21T08:53:52.498000"
    }
}

Повторный запрос — все еще обрабатывается (409)

json

{
    "success": false,
    "error": "duplicate_request_processing",
    "message": "This request is currently being processed. Please wait and do not retry.",
    "retry_after_seconds": 3
}

Сравнение: заказы на 5 минут и на 1 час

Функция	Заказ на 5 минут	Заказ на 1 час
Эндпоинт	`/apiv2/order5m`	`/apiv2/order1h`
Длительность	5 минут	1 час
Диапазон энергии	61 000 - 650 000	61 000 - 3 000 000
Провайдеры	Только внутренние пулы Netts	Внутренние пулы + внешние провайдеры
Цена	Ниже (5-минутный тариф)	Стандартный почасовой тариф
Доступность	Может быть ограничена в пиковые часы	Высокая (резервирование через нескольких провайдеров)
Оптимально для	Частых мелких транзакций	Крупной или гарантированной доставки

Примечания

Энергия доставляется мгновенно после успешного оформления заказа (обычно в течение 0.5–2 секунд)
Таймаут ответа API: Максимум 10 секунд (включает внутренние попытки повтора)
Активация адреса: Если адрес получателя не активирован, Netts активирует его по себестоимости. Стоимость активации взимается только один раз за адрес
Длительность: Фиксированная 5 минут (300 секунд)
Минимальное количество энергии: 61 000 единиц
Максимальное количество энергии: 650 000 единиц на заказ
Буфер энергии: +50 единиц добавляется автоматически (бесплатно)
Формат ID заказа: 5M{id} для унифицированного отслеживания
Ценообразование: Динамическое в зависимости от времени суток через Pricing API
Ограничение частоты запросов: 50 запросов в секунду на один IP-адрес
Только внутренние пулы: Если пулы заполнены, повторите попытку через некоторое время или используйте эндпоинт на 1 час в качестве запасного варианта

POST /apiv2/order5m ​

URL эндпоинта ​

Заголовки запроса ​

Тело запроса ​

Параметры запроса ​

Информация о провайдерах ​

Примеры ​

cURL ​

Python ​

Ответ ​

Успешный ответ (200 OK) ​

Успех с активацией адреса (200 OK) ​

Поля ответа ​

Ответы с ошибками ​

Недопустимое количество энергии (400) ​

Ошибка аутентификации (401) ​

Недостаточный баланс (403) ​

Сервис недоступен (503) ​

Внутренняя ошибка сервера (500) ​

Справочник кодов ошибок ​

Ограничения частоты запросов ​

Заголовки ограничения частоты запросов ​

Превышение лимита запросов (429) ​

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

Как работает идемпотентность ​

Передача собственного ключа ​

Размещение двух одинаковых заказов ​

HTTP-статусы для повторных запросов ​

Повторный запрос — уже обработан (208) ​

Повторный запрос — все еще обрабатывается (409) ​

Рекомендации ​

Сравнение: заказы на 5 минут и на 1 час ​

Примечания ​

POST /apiv2/order5m

URL эндпоинта

Заголовки запроса

Тело запроса

Параметры запроса

Информация о провайдерах

Примеры

cURL

Python

Ответ

Успешный ответ (200 OK)

Успех с активацией адреса (200 OK)

Поля ответа

Ответы с ошибками

Недопустимое количество энергии (400)

Ошибка аутентификации (401)

Недостаточный баланс (403)

Сервис недоступен (503)

Внутренняя ошибка сервера (500)

Справочник кодов ошибок

Ограничения частоты запросов

Заголовки ограничения частоты запросов

Превышение лимита запросов (429)

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

Как работает идемпотентность

Передача собственного ключа

Размещение двух одинаковых заказов

HTTP-статусы для повторных запросов

Повторный запрос — уже обработан (208)

Повторный запрос — все еще обрабатывается (409)

Рекомендации

Сравнение: заказы на 5 минут и на 1 час

Примечания