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"}`	Непредвиденная ошибка на стороне сервера.

Ограничение частоты запросов (Rate limit)

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-ключом и вам требуется больше, свяжитесь со службой поддержки — лимит может быть повышен для конкретного ключа, либо к вашему потребителю может быть подключен отдельный плагин ограничения частоты запросов.

Заголовки для отладки

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

Заголовок	Значение
`X-Request-ID`	ID запроса на стороне приложения (генерируется калькулятором).
`X-Process-Time`	Время обработки приложением в миллисекундах (вышестоящий сервис, без учета 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, поэтому предварительный запрос OPTIONS (preflight) для кросс-доменного POST в браузерах завершится ошибкой.

Если вам необходимо вызывать калькулятор из интерфейса браузера, проксируйте запрос через собственный бэкенд (на котором хранится API-ключ), чтобы не раскрывать ключ клиенту в любом случае.

TIP

Если ваш сценарий действительно требует отправки POST из браузера с API-ключом (например, доверенная внутренняя панель управления на известном источнике), обратитесь в поддержку — плагин 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) ​

Ошибки ​

Ограничение частоты запросов (Rate limit) ​

Пример ответа 429 ​

Заголовки для отладки ​

Таймаут и повторные попытки на стороне клиента ​

Поддержка браузеров / CORS ​

Примечания ​