POST /apiv2/order5m

Створення замовлення на оренду Energy на 5 хвилин через внутрішні пули Energy Netts.

URL кінцевої точки

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

Заголовки запиту

Header	Required	Description
Content-Type	Так	application/json
X-API-KEY	Так	Ваш API-ключ із панелі керування Netts
X-Real-IP	Так	IP-адреса з вашого білого списку

Тіло запиту

json

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

Параметри

Parameter	Type	Required	Description
amount	integer	Так	Кількість Energy для оренди (мінімум: 61,000, максимум: 650,000)
receiveAddress	string	Так	TRON-адреса, яка отримає Energy (формат TRC-20)

Ліміти Energy

Ендпоінт на 5 хвилин приймає кількість Energy від 61,000 до 650,000 одиниць на одне замовлення. Запити поза цим діапазоном відхилятимуться з помилкою HTTP 400.

Інформація про провайдера

Замовлення Energy на 5 хвилин виконуються виключно через внутрішні пули Energy Netts. На відміну від 1-годинного ендпоінта, зовнішні провайдери не використовуються.

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

Оскільки делегування надходить лише з внутрішніх пулів, у періоди високого попиту можлива тимчасова недоступність. Якщо ви отримуєте помилку 503, повторіть запит після невеликої затримки або скористайтеся 1-годинним ендпоінтом, який має доступ до кількох зовнішніх провайдерів.

Examples запитів

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"
        }
    }
}

Поля відповіді

Field	Type	Description
detail.code	integer	Завжди `10000` для успішних замовлень
detail.msg	string	Повідомлення про успіх зі списаною сумою
detail.data.orderId	string	Уніфікований ID замовлення (формат: `5M{id}`)
detail.data.paidTRX	number	Загальна вартість у TRX (включає комісію за активацію, якщо застосовно)
detail.data.hash	string	Хеш транзакції делегування
detail.data.delegateAddress	string	Адреса пулу, з якої було делеговано Energy
detail.data.energy	integer	Кількість Energy + буфер (зазвичай +50)
detail.data.activationHash	string	Присутнє лише у разі виконання активації адреси

Відповіді з помилками

Неприпустима кількість Energy (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"
}

Довідник кодів помилок

Code	Description	HTTP Status
`10000`	Успіх	200
`10000`	Успіх (кешована відповідь)	208
`-`	Дублікат запиту ще обробляється	409
`1003`	Кількість Energy поза межами діапазону	400
`1004`	Недостатній баланс	403
`1005`	Адреса платника користувача не налаштована	400
`5000`	Внутрішня помилка сервера	500
`5003`	Сервіс Energy недоступний	503

Ліміти запитів

До цього ендпоінта застосовуються такі обмеження частоти запитів (на одну IP-адресу):

Period	Limit	Description
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-секундне вікно)
Кількість Energy
Адреса одержувача
API-ключ

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

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

Ви можете взяти контроль над ідемпотентністю у свої руки, передавши заголовок X-Idempotency-Key. Коли він присутній, саме це значення одноосібно визначає, чи є запит повторним, а автоматична комбінація вище не використовується. Коли він відсутній, нічого не змінюється — сервер генерує ключ для вас автоматично.

Правила такі самі, як і для /apiv2/order1h:


Header	`X-Idempotency-Key`
Format	Рівно 64 шістнадцяткових символи в нижньому регістрі — дайджест SHA-256
Lifetime	24 години з моменту першого запиту з цим ключем
Scope	Ваш акаунт. Те саме значення, надіслане іншим акаунтом, ніколи не поверне ваш результат

Ключ будь-якого іншого формату — 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 для повторних запитів

Status Code	Name	Description
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
}

Практичні рекомендації

Не надсилайте паралельні запити з однаковими параметрами — дочекайтеся відповіді на кожен
Обробляйте відповіді 409 очікуванням, а не негайним повторенням запиту
Перевіряйте поле idempotency.cached, щоб виявити кешовані відповіді

Порівняння: 5-хвилинні та 1-годинні замовлення

Feature	5-Minute Order	1-Hour Order
Endpoint	`/apiv2/order5m`	`/apiv2/order1h`
Тривалість	5 хвилин	1 година
Діапазон Energy	61,000 - 650,000	61,000 - 3,000,000
Провайдери	Лише внутрішні пули Netts	Внутрішні пули + зовнішні провайдери
Ціна	Нижча (5-хвилинний тариф)	Стандартний погодинний тариф
Доступність	Може бути обмежена в пікові години	Висока (резервування через кількох провайдерів)
Найкраще для	Частих невеликих транзакцій	Великих обсягів або гарантованої доставки

Постоплатні акаунти

Акаунти з постоплатним розрахунком використовують той самий ендпоінт, URL, заголовки та тіло запиту, що й усі інші. Різниця полягає в способі оплати замовлення:

З вашого депозиту нічого не списується. Кожне успішне замовлення додається до суми до сплати вашого акаунта у валюті розрахунку, зазначеній у вашому договорі. Ви оплачуєте її за рахунком відповідно до умов угоди.
Ваш акаунт має кредитний ліміт. Поки сума заборгованості залишається в межах ліміту, замовлення приймаються навіть із нульовим депозитом.
Оплачуються лише фактично надані послуги. Замовлення, яке було відхилено або не виконано, нічого не коштує.
Якщо адресу одержувача необхідно активувати, активація є частиною того самого замовлення та тарифікується як окрема плата.

Постоплатний розрахунок підключається компанією Netts для акаунта за запитом. Кожна відповідь містить інформацію про спосіб оплати замовлення: поле paymentMode має значення postpaid або prepaid.

Додаткові поля запиту

Parameter	Type	Required	Description
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"
        }
    }
}

Field	Description
unitPriceSun	Ціна за одиницю Energy в SUN з урахуванням вашої персональної знижки, якщо вона є
discount	Ваша персональна знижка (`type`, `value`) або `null`
energyTRX / activationTRX / wouldCostTRX	Energy, активація (якщо адреса її потребує) та загальна сума в 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"
        }
    }
}

Field	Description
paidTRX	Вартість послуги в TRX. Для постоплатних акаунтів вона не списується з депозиту
paymentMode	`postpaid`
energyTRX / activationTRX / totalTRX	Точні суми, 6 знаків після коми
quoteId, alt	Присутні, якщо замовлення було розміщено за квотою: ID квоти та зафіксовані суми

Усі інші поля такі ж самі, як і для передоплатних замовлень.

Кредитний ліміт вичерпано (402)

json

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

Замовлення не виконується, і нарахування не здійснюються. Нові замовлення знову прийматимуться, щойно ваш платіж буде зареєстровано або ваш ліміт буде збільшено.

Коди помилок постоплати

Code	HTTP	Description
`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 вище нічого не замовляється і кошти не списуються.

Примітки

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

POST /apiv2/order5m ​

URL кінцевої точки ​

Заголовки запиту ​

Тіло запиту ​

Параметри ​

Інформація про провайдера ​

Examples запитів ​

cURL ​

Python ​

Відповідь ​

Успішна відповідь (200 OK) ​

Успіх з активацією адреси (200 OK) ​

Поля відповіді ​

Відповіді з помилками ​

Неприпустима кількість Energy (400) ​

Помилка автентифікації (401) ​

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

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

Внутрішня помилка сервера (500) ​

Довідник кодів помилок ​

Ліміти запитів ​

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

Перевищення ліміту частоти запитів (429) ​

Ідемпотентність ​

Як працює ідемпотентність ​

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

Розміщення двох однакових замовлень ​

Коди стану HTTP для повторних запитів ​

Повторний запит — вже оброблено (208) ​

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

Практичні рекомендації ​

Порівняння: 5-хвилинні та 1-годинні замовлення ​

Постоплатні акаунти ​

Додаткові поля запиту ​

Перевірка ціни (test: true) ​

Квота з фіксованою ціною (freezePrice: true) ​

Успішне замовлення ​

Кредитний ліміт вичерпано (402) ​

Коди помилок постоплати ​

Примітки ​

POST /apiv2/order5m

URL кінцевої точки

Заголовки запиту

Тіло запиту

Параметри

Інформація про провайдера

Examples запитів

cURL

Python

Відповідь

Успішна відповідь (200 OK)

Успіх з активацією адреси (200 OK)

Поля відповіді

Відповіді з помилками

Неприпустима кількість Energy (400)

Помилка автентифікації (401)

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

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

Внутрішня помилка сервера (500)

Довідник кодів помилок

Ліміти запитів

Заголовки Rate Limit

Перевищення ліміту частоти запитів (429)

Ідемпотентність

Як працює ідемпотентність

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

Розміщення двох однакових замовлень

Коди стану HTTP для повторних запитів

Повторний запит — вже оброблено (208)

Повторний запит — ще обробляється (409)

Практичні рекомендації

Порівняння: 5-хвилинні та 1-годинні замовлення

Постоплатні акаунти

Додаткові поля запиту

Перевірка ціни (`test: true`)

Квота з фіксованою ціною (`freezePrice: true`)

Успішне замовлення

Кредитний ліміт вичерпано (402)

Коди помилок постоплати

Примітки