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": "3636f97dde244fca17cdc0b2cf7fd1572a9b4c6d8e0f1a3b5c7d9e1f3a5b7c9d",
            "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": "3636f97dde244fca17cdc0b2cf7fd1572a9b4c6d8e0f1a3b5c7d9e1f3a5b7c9d",
            "delegateAddress": "TNp5gsJhBmZFXgCdgjMgr8pEZ8fHgXUHDq",
            "energy": 65050,
            "activationHash": "bab38070a64b237acc9110ecf5135acc4d6e8f0a2b4c6d8e0f2a4b6c8d0e2f4a"
        }
    }
}

Поля ответа

Поле	Тип	Описание
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 запросов в секунду

Заголовки Rate Limit

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": "3636f97dde244fca17cdc0b2cf7fd1572a9b4c6d8e0f1a3b5c7d9e1f3a5b7c9d",
            "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-минутный тариф)	Стандартный часовой тариф
Доступность	Может быть ограничена в пиковые часы	Высокая (резервирование несколькими провайдерами)
Лучше всего для	Частых небольших транзакций	Крупной или гарантированной доставки

Постоплатные аккаунты

Аккаунты с постоплатной системой расчетов используют тот же эндпоинт, URL, заголовки и тело запроса, что и остальные. Разница заключается в способе оплаты заказа:

С вашего депозита ничего не списывается. Каждый успешный заказ добавляется к балансу задолженности вашего аккаунта в валюте расчетов, согласованной в вашем договоре. Вы оплачиваете его по счету в соответствии с договоренностями.
У вашего аккаунта есть кредитный лимит. Пока сумма задолженности находится в пределах лимита, заказы принимаются даже при нулевом депозите.
Оплачиваются только фактически оказанные услуги. Отклоненный или невыполненный заказ ничего не стоит.
Если адрес получателя необходимо активировать, активация входит в состав того же заказа и тарифицируется отдельной статьей расходов.

Постоплатная система расчетов подключается командой Netts по запросу. Каждый ответ сообщает способ оплаты заказа: paymentMode имеет значение postpaid или prepaid.

Дополнительные поля запроса

Параметр	Тип	Обязательный	Описание
test	boolean	Нет	`true` — только рассчитать стоимость. Ничего не заказывается, не доставляется и не выставляется к оплате
freezePrice	boolean	Нет	`true` — зафиксировать цену по вашему договору на 60 секунд. Ничего не заказывается и не выставляется к оплате
quoteId	string	Нет	Оформить заказ по цене котировки, полученной через `freezePrice`
priceCurrency	string	Нет	`TRX` (по умолчанию) или валюта вашего договора, как в `settlement.asset`. Для постоплатных аккаунтов суммы в валюте договора включаются всегда

Параметр quoteId нельзя совмещать с test или freezePrice. Любые другие поля в теле запроса отклоняются.

Проверка цены (`test: true`)

json

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

json

{
    "detail": {
        "code": 10010,
        "msg": "Test calculation",
        "data": {
            "amount": 65000,
            "unitPriceSun": "19",
            "discount": null,
            "energyTRX": "1.235000",
            "activationTRX": "1.100000",
            "wouldCostTRX": "2.335000",
            "paidTRX": 0,
            "paymentMode": "postpaid",
            "activationCheck": "inactive",
            "alt": {"USDC": {"energy": "0.409088", "activation": "0.364370", "total": "0.773458"}},
            "fxAt": "2026-10-19T07:16:12.548894+00:00"
        }
    }
}

Поле	Описание
unitPriceSun	Цена за единицу энергии в SUN, включая вашу персональную скидку, если она есть
discount	Ваша персональная скидка (`type`, `value`) или `null`
energyTRX / activationTRX / wouldCostTRX	Энергия, активация (если адресу она требуется) и общая сумма, в TRX
activationCheck	`inactive` — адрес будет активирован и включен в счет; `active` — активация не требуется; `unknown` — в данный момент проверить не удалось
`alt.<currency>`	Те же суммы в валюте вашего договора
fxAt	Время курса конвертации, использованного для расчета сумм в валюте договора

Котировка с фиксированной ценой (`freezePrice: true`)

Используйте котировку, чтобы зафиксировать цену по договору перед заказом.

Отправьте заказ с "freezePrice": true. Ответ содержит код 10011 (Quote issued), те же поля, что и при проверке цены, а также quoteId и expiresAt.
В течение 60 секунд отправьте заказ с "quoteId": "<quoteId>" и теми же значениями amount и receiveAddress.
Заказ тарифицируется по цене котировки — цене по вашему договору на момент ее формирования — даже если цена изменится за это время.

Котировку можно использовать один раз и только для того же продукта: 5-минутная котировка не может оплатить 1-часовой заказ. Истекшая или уже использованная котировка отклоняется, и заказ не создается.

json

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

Успешный заказ

json

{
    "detail": {
        "code": 10000,
        "msg": "Successful, 1.24 TRX service cost, postpaid",
        "data": {
            "orderId": "5M5f557d2fba",
            "paidTRX": 1.235,
            "hash": "c1fafd8ef7fb6b7fb8a729120756b26e611f401275cb4f7a04fe2bafd75b13da",
            "delegateAddress": "TR3qZsdmkFcvP729Md3PwXzktFQkMoUzjg",
            "energy": 65000,
            "paymentMode": "postpaid",
            "energyTRX": "1.235000",
            "activationTRX": "0.000000",
            "totalTRX": "1.235000"
        }
    }
}

Поле	Описание
paidTRX	Стоимость услуги в TRX. Для постоплатных аккаунтов она не списывается с депозита
paymentMode	`postpaid`
energyTRX / activationTRX / totalTRX	Точные суммы, 6 знаков после запятой
quoteId, alt	Присутствуют, если заказ был оформлен по котировке: идентификатор котировки и зафиксированные суммы

Все остальные поля аналогичны предоплатным заказам.

Достигнут кредитный лимит (402)

json

{
    "detail": {
        "code": 1004,
        "msg": "Postpaid credit limit reached.",
        "paymentMode": "postpaid",
        "reason": "limit_reached"
    }
}

Заказ не выполняется и ничего не начисляется к оплате. Прием новых заказов возобновляется после поступления оплаты или увеличения кредитного лимита.

Коды ошибок постоплаты

Код	HTTP	Описание
`10010`	200	Результат проверки цены (`test`)
`10011`	200	Котировка выдана (`freezePrice`)
`1004`	402	Достигнут кредитный лимит постоплаты
`4100`	400	Недопустимый запрос
`4101`	400	Неподдерживаемая `priceCurrency`
`4102`	400	`quoteId` передан одновременно с `test` или `freezePrice`
`4103`	409	Котировка уже использована
`4104`	409	Срок действия котировки истек
`4105`	409	Ключ идемпотентности уже использован для другого запроса
`4106`	404	Котировка не найдена
`4107`	409	Параметры заказа отличаются от параметров в котировке
`4108`	400	Неверный формат `quoteId`
`4109`	422	Недоступно для субаккаунтов
`5032`	503	Цена временно недоступна
`5033`	503	Курс конвертации временно недоступен
`5034`	503	Биллинг временно недоступен — заказ не принят
`5036`	503	Проверка кредитного лимита временно недоступна — повторите попытку позже

Для всех приведенных выше ответов 4xx и 503 заказ не создается и начисления не производятся.

Примечания

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

POST /apiv2/order5m ​

URL эндпоинта ​

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

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

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

Сведения о провайдерах ​

Примеры запросов ​

cURL ​

Python ​

Ответ ​

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

Успешный ответ с активацией адреса (200 OK) ​

Поля ответа ​

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

Недопустимый объем энергии (400) ​

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

Недостаточно средств (403) ​

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

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

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

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

Заголовки Rate Limit ​

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

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

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

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

Отправка двух одинаковых заказов ​

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

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

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

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

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

Постоплатные аккаунты ​

Дополнительные поля запроса ​

Проверка цены (test: true) ​

Котировка с фиксированной ценой (freezePrice: true) ​

Успешный заказ ​

Достигнут кредитный лимит (402) ​

Коды ошибок постоплаты ​

Примечания ​

POST /apiv2/order5m

URL эндпоинта

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

Тело запроса

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

Сведения о провайдерах

Примеры запросов

cURL

Python

Ответ

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

Успешный ответ с активацией адреса (200 OK)

Поля ответа

Ответы с ошибкой

Недопустимый объем энергии (400)

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

Недостаточно средств (403)

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

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

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

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

Заголовки Rate Limit

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

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

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

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

Отправка двух одинаковых заказов

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

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

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

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

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

Постоплатные аккаунты

Дополнительные поля запроса

Проверка цены (`test: true`)

Котировка с фиксированной ценой (`freezePrice: true`)

Успешный заказ

Достигнут кредитный лимит (402)

Коды ошибок постоплаты

Примечания