POST /apiv2/order5m

Створення замовлення на оренду Energy на 5 хвилин через внутрішні пули energy 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	Так	Кількість Energy для оренди (мінімум: 61 000, максимум: 650 000)
receiveAddress	string	Так	TRON-адреса, яка отримає energy (формат TRC-20)

Ліміти Energy

Кінцева точка для 5-хвилинної оренди приймає обсяги energy від 61 000 до 650 000 одиниць на одне замовлення. Запити поза цим діапазоном буде відхилено з помилкою HTTP 400.

Інформація про постачальника

5-хвилинні замовлення energy виконуються виключно через внутрішні пули energy 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	Уніфікований 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"
}

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

Код	Опис	HTTP-статус
`10000`	Успіх	200
`10000`	Успіх (кешована відповідь)	208
`-`	Повторний запит ще обробляється	409
`1003`	Кількість Energy виходить за межі діапазону	400
`1004`	Недостатній баланс	403
`1005`	Адресу платника користувача не налаштовано	400
`5000`	Внутрішня помилка сервера	500
`5003`	Сервіс Energy недоступний	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 секунди)
Кількості Energy
Адреси одержувача
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-годинне замовлення
Endpoint	`/apiv2/order5m`	`/apiv2/order1h`
Тривалість	5 хвилин	1 година
Діапазон Energy	61 000 - 650 000	61 000 - 3 000 000
Постачальники	Лише внутрішні пули Netts	Внутрішні пули + зовнішні постачальники
Ціна	Нижча (5-хвилинний тариф)	Стандартний погодинний тариф
Доступність	Може бути обмежена в пікові години	Висока (резервування через кількох постачальників)
Найкраще підходить для	Частих невеликих транзакцій	Великих обсягів або гарантованої доставки

Примітки

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 ендпоінта ​

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

Тіло запиту ​

Параметри ​

Інформація про постачальника ​

Приклади запитів ​

cURL ​

Python ​

Відповідь ​

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

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

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

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

Недійсна кількість Energy (400) ​

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

Недостатньо коштів на балансі (403) ​

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

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

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

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

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

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

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

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

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

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

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

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

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

Рекомендації ​

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

Примітки ​

POST /apiv2/order5m

URL ендпоінта

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

Тіло запиту

Параметри

Інформація про постачальника

Приклади запитів

cURL

Python

Відповідь

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

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

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

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

Недійсна кількість Energy (400)

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

Недостатньо коштів на балансі (403)

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

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

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

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

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

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

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

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

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

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

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

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

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

Рекомендації

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

Примітки