POST /apiv2/usdt/analyze

Розрахунок вартості переказу TRON USDT (приватний ендпоінт — автентифікований).

Повертає точно такий самий корисний вантаж TransferAnalysis, як і публічний варіант GET, але з набагато вищим лімітом запитів (50 зап/сек на вузол Kong замість 1/сек) і з даними запиту, що передаються в тілі JSON замість URL. Використовуйте цей ендпоінт для будь-якої інтеграції в проперійному середовищі.

URL ендпоінта

POST https://netts.io/apiv2/usdt/analyze

Автентифікація

Приймається будь-який із наступних двох заголовків (обидва підтримуються одночасно; X-API-KEY є бажаним, оскільки він узгоджується з рештою API-поверхні Netts /apiv2/*):

Заголовок	Обов'язковий	Опис
`Content-Type`	Так	Має бути `application/json`.
`X-API-KEY`	Бажаний	Ваш API-ключ Netts — точно такого самого формату, як для `/apiv2/order1h` та інших автентифікованих ендпоінтів Netts.
`Authorization`	Приймається як альтернатива	`Bearer {key}` або просто `{key}` (без префікса). Використовуйте це, якщо ваш HTTP-клієнт має вбудовану схему bearer/auth.

Якщо надіслано обидва заголовки, перевага надається X-API-KEY.

Білий список IP: IP-адреса, з якої запит надходить до нашого периферійного вузла, має бути в білому списку, налаштованому для вашого API-ключа (той самий механізм, що й для інших ендпоінтів /apiv2/*). Запити з IP, якого немає в білому списку, повертають 401 Unauthorized із "Invalid API key or IP not in whitelist".

Повторне використання заголовків order1h

Якщо ви вже викликаєте /apiv2/order1h із X-API-KEY: {key}, ви можете надіслати точно такий самий заголовок X-API-KEY до /apiv2/usdt/analyze — калькулятор тепер розпізнає його як основний заголовок автентифікації.

Тіло запиту

json

{
    "sender_address":   "TFLit1TFohBtT2f8UVCLFVPmZxawxqByYe",
    "receiver_address": "TTKR9aQdJWTgXLK9cmzaDitT5VXE497thL"
}

Поля

Поле	Тип	Обов'язкове	Обмеження
`sender_address`	string	Так	Дійсна адреса TRON — 34 символи, починається з `T`, дійсна контрольна сума base58.
`receiver_address`	string	Так	Дійсна адреса TRON; має відрізнятися від `sender_address`.

TIP

Поле amount відсутнє. Калькулятор повертає вартість та вимоги до ресурсів для одного переказу USDT між двома адресами; якщо вам потрібна деталізація для певної суми USDT, помножте рекомендовану Energy на кількість переказів на вашому боці — окремий переказ TRC-20 USDT споживає однакові ~130 k Energy незалежно від суми.

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

cURL (бажаний — `X-API-KEY`)

bash

curl -X POST "https://netts.io/apiv2/usdt/analyze" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
        "sender_address":   "TFLit1TFohBtT2f8UVCLFVPmZxawxqByYe",
        "receiver_address": "TTKR9aQdJWTgXLK9cmzaDitT5VXE497thL"
      }'

cURL (альтернативний — `Authorization`)

bash

curl -X POST "https://netts.io/apiv2/usdt/analyze" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
        "sender_address":   "TFLit1TFohBtT2f8UVCLFVPmZxawxqByYe",
        "receiver_address": "TTKR9aQdJWTgXLK9cmzaDitT5VXE497thL"
      }'

Python

python

import requests

API_KEY = "YOUR_API_KEY"

payload = {
    "sender_address":   "TFLit1TFohBtT2f8UVCLFVPmZxawxqByYe",
    "receiver_address": "TTKR9aQdJWTgXLK9cmzaDitT5VXE497thL",
}

r = requests.post(
    "https://netts.io/apiv2/usdt/analyze",
    headers={
        "Content-Type": "application/json",
        "X-API-KEY":    API_KEY,           # preferred; same header as /apiv2/order1h
        # or, equivalently:
        # "Authorization": f"Bearer {API_KEY}",
    },
    json=payload,
    timeout=15,
)

if r.status_code == 200:
    data = r.json()["data"]
    print("Energy needed:", data["requirements"]["energy_with_buffer"])
    print("Total cost:   ", data["costs"]["total_cost_trx"], "TRX")
    print("Method:       ", data["costs"]["recommended_method"])
elif r.status_code == 401:
    print("Auth failed:", r.json())
elif r.status_code == 429:
    print("Rate-limited — Retry-After:", r.headers.get("Retry-After"))
else:
    print("Error:", r.status_code, r.json())

Відповідь

Успіх (200 OK)

Ідентична оболонка з публічним ендпоінтом:

json

{
    "status": "success",
    "data": { /* TransferAnalysis — see the public-endpoint page */ },
    "current_utc_time": "2026-04-23 11:54:13",
    "processing_time_ms": 20.14
}

Повний покроковий опис полів data наведено на сторінці публічного ендпоінта — див. TransferAnalysis, AddressInfo, Requirements і Costs.

Помилки

Порядок перевірок

Автентифікація перевіряється до валідації тіла запиту. Якщо заголовок Authorization відсутній/недійсний або ваш IP не внесено до білого списку, ви завжди отримуватимете 401 — навіть якщо тіло JSON також сформовано некоректно. Спочатку виправте налаштування автентифікації, потім повторіть тест із дійсним ключем; лише після цього з'являться помилки валідації тіла Pydantic (422).

HTTP	Тіло	Коли
401	`{"code": -1, "msg": "API key not provided (expected X-API-KEY or Authorization header)"}`	Відсутній як заголовок `X-API-KEY`, так і `Authorization`.
401	`{"code": -1, "msg": "Invalid API key or IP not in whitelist"}`	Невідомий ключ або IP запиту не у вашому білому списку.
404	`{"code": -1, "msg": "User not found"}`	Ключ дійсний, але запис користувача не знайдено (рідко).
422	`{"detail": [{"loc": ["body","sender_address"], "msg": "Invalid TRON address length", "type": "value_error"}]}`	Збій валідації тіла FastAPI/Pydantic. Статус — `422 Unprocessable Entity`, а не `400`.
422	`{"detail": [{..., "msg": "Sender and receiver cannot be the same address", "type": "value_error"}]}`	`sender_address == receiver_address`.
429	`{"message": "API rate limit exceeded"}`	Тривалий трафік понад `50 req/sec` на вузлі Kong.
500	`{"code": -1, "msg": "Internal server error"}`	Неочікувана помилка на стороні сервера.

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

50 запитів / секунду на вузол Kong (limit_by = ip, політика local).
Ліміти на minute / hour не встановлені — застосовується лише ліміт на секунду.
Кожна відповідь містить стандартні заголовки Kong: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, X-RateLimit-Limit-Second, X-RateLimit-Remaining-Second, а також Retry-After у разі 429.

Приклад відповіді 429

http

HTTP/1.1 429 Too Many Requests
Content-Type: application/json; charset=utf-8
RateLimit-Limit: 50
RateLimit-Remaining: 0
RateLimit-Reset: 1
Retry-After: 1
X-RateLimit-Limit-Second: 50
X-RateLimit-Remaining-Second: 0

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

TIP

Якщо ви досягаєте 50 зап/сек з одним API-ключем і потребуєте більшого, зверніться до служби підтримки — ліміт можна підвищити для окремого ключа або підключити виділений плагін обмеження частоти запитів до вашого споживача (consumer).

Заголовки налагодження

Кожна відповідь також містить ідентифікатори, корисні під час відкриття тікета в службу підтримки — будь ласка, додавайте їх без змін, щоб ми могли знайти запит у наших журналах за лічені секунди:

Заголовок	Значення
`X-Request-ID`	ID запиту на стороні програми (згенерований калькулятором).
`X-Process-Time`	Час обробки програмою в мілісекундах (upstream, за винятком Kong).
`X-Kong-Request-Id`	ID запиту на стороні Kong (присутній у журналах доступу Kong).

Тайм-аут і повторні спроби на стороні клієнта

Калькулятор виконує живі ончейн-запити до вузлів TRON для кожного запиту, тому за високого навантаження або повільних апстрім-вузлів один виклик може тривати кілька секунд. Короткі клієнтські тайм-аути призводитимуть до збоїв навіть у разі успішних відповідей — це основна причина більшості повідомлень про помилку cURL error 28 (Connection timed out) від інтеграторів.

Рекомендовані налаштування:

Тайм-аут ≥ 15 секунд (30 с безпечніше). Стандартні 10 с, які використовуються багатьма HTTP-клієнтами, є занадто короткими.
У разі HTTP 429 зважайте на заголовок Retry-After (у секундах). Додавайте невеликий джитер (наприклад, 0–200 мс) перед повторною спробою, потім використовуйте експоненційну затримку, якщо ви все ще впираєтеся в ліміт 50 зап/сек.
У разі HTTP 5xx або мережевих помилок повторюйте спробу щонайбільше 2–3 рази з експоненційною затримкою; не перевантажуйте ендпоінт надмірними запитами.
Кешуйте результат на стороні клієнта на 30–60 секунд для кожної пари (sender_address, receiver_address) — базові ціни на ресурси та стан блокчейну рідко змінюються настільки швидко, щоб виправдати частіший перерахунок.

Підтримка браузерів / CORS

Цей ендпоінт розроблений для інтеграцій server-to-server і наразі не підтримує прямі виклики з браузера: апстрім-застосунок FastAPI повертає лише Access-Control-Allow-Methods: GET, тому попередній запит (preflight) OPTIONS для міждоменного POST у браузерах зазнає помилки.

Якщо вам потрібно викликати калькулятор із фронтенду браузера, проксуйте запит через власний бекенд (який містить API-ключ), замість того щоб у будь-якому випадку розкривати ключ клієнту.

TIP

Якщо ваш сценарій використання обґрунтовано вимагає надсилання POST із боку браузера з API-ключем (наприклад, довірена внутрішня панель приладів на відомому джерелі (origin)), зверніться до підтримки — плагін CORS можна підключити на рівні Kong для вашого маршруту.

Примітки

Формат відповіді навмисно ідентичний публічному ендпоінту, тому клієнтський код, який аналізує відповідь публічного ендпоінта, продовжує працювати після міграції на автентифікований варіант — змінюється лише сам виклик.
Приймаються як X-API-KEY: {key} (бажаний, узгоджується з /apiv2/order1h), так і Authorization: Bearer {key} / Authorization: {key}; якщо надіслано обидва, перевага надається X-API-KEY.
Втручання Cloudflare / зворотного проксі не впливає на цей ендпоінт так само, як на публічний, оскільки для автентифікованого трафіку діє обмеження частоти на вузол Kong, а семантику для конкретного споживача (consumer) можна увімкнути за запитом.

POST /apiv2/usdt/analyze ​

URL ендпоінта ​

Автентифікація ​

Тіло запиту ​

Поля ​

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

cURL (бажаний — X-API-KEY) ​

cURL (альтернативний — Authorization) ​

Python ​

Відповідь ​

Успіх (200 OK) ​

Помилки ​

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

Приклад відповіді 429 ​

Заголовки налагодження ​

Тайм-аут і повторні спроби на стороні клієнта ​

Підтримка браузерів / CORS ​

Примітки ​