POST /apiv2/usdt/analyze

Calcular el costo de transferencia de USDT en TRON (endpoint privado — autenticado).

Devuelve exactamente la misma carga útil TransferAnalysis que la variante pública GET, pero con un límite de tasa mucho más alto (50 req/seg por nodo de Kong en lugar de 1/seg) y con los datos de la solicitud enviados en un cuerpo JSON en lugar de la URL. Utilice este endpoint para cualquier integración en producción.

URL del endpoint

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

Autenticación

Se acepta cualquiera de los dos encabezados siguientes (ambos compatibles simultáneamente; se prefiere X-API-KEY porque coincide con el resto de la superficie de la API /apiv2/* de Netts):

Encabezado	Requerido	Descripción
Content-Type	Sí	Debe ser application/json.
X-API-KEY	Preferido	Su clave de API de Netts — exactamente el mismo formato utilizado para /apiv2/order1h y otros endpoints autenticados de Netts.
Authorization	Aceptado como alternativa	Bearer {key} o simplemente {key} (sin prefijo). Utilice esto si su cliente HTTP tiene un flujo de autenticación/bearer integrado.

Si se envían ambos encabezados, prevalece X-API-KEY.

Lista blanca de IP: la IP desde la cual la solicitud llega a nuestro edge debe estar en la lista blanca configurada para su clave de API (el mismo mecanismo que los otros endpoints /apiv2/*). Las solicitudes desde una IP que no esté en la lista blanca devuelven 401 Unauthorized con "Invalid API key or IP not in whitelist".

Reutilizar sus encabezados de order1h

Si ya llama a /apiv2/order1h con X-API-KEY: {key}, puede enviar exactamente el mismo encabezado X-API-KEY a /apiv2/usdt/analyze — la calculadora ahora lo reconoce como el encabezado de autenticación principal.

Cuerpo de la solicitud

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

Campos

Campo	Tipo	Requerido	Restricciones
sender_address	string	Sí	Dirección de TRON válida — 34 caracteres, comienza con T, suma de verificación base58 válida.
receiver_address	string	Sí	Dirección de TRON válida; debe ser diferente de sender_address.

TIP

No hay campo amount. La calculadora devuelve el costo y los requisitos de recursos para una única transferencia de USDT entre las dos direcciones; si necesita el desglose para una cantidad específica de USDT, multiplique la energía recomendada por el recuento de transferencias de su lado — una sola transferencia de USDT TRC-20 consume los mismos ~130 k de energía independientemente del monto.

Ejemplos de solicitud

cURL (preferido — X-API-KEY)

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 (alternativa — Authorization)

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

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())

Respuesta

Éxito (200 OK)

Envoltorio idéntico al endpoint público:

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

La descripción completa campo por campo de data se encuentra en la página del endpoint público — consulte TransferAnalysis, AddressInfo, Requirements y Costs.

Errores

Orden de las comprobaciones

La autenticación se valida antes de la validación del cuerpo. Si el encabezado Authorization falta o no es válido, o su IP no está en la lista blanca, siempre verá un 401 — incluso si el cuerpo JSON también está mal formado. Corrija la autenticación primero, luego vuelva a probar con una clave válida; solo entonces aparecerán los errores de validación del cuerpo de Pydantic (422).

HTTP	Cuerpo	Cuándo
401	{"code": -1, "msg": "API key not provided (expected X-API-KEY or Authorization header)"}	No está presente ni el encabezado X-API-KEY ni Authorization.
401	{"code": -1, "msg": "Invalid API key or IP not in whitelist"}	Clave desconocida, o la IP de la solicitud no está en su lista blanca.
404	{"code": -1, "msg": "User not found"}	Clave válida pero no se encontró el registro de usuario (raro).
422	{"detail": [{"loc": ["body","sender_address"], "msg": "Invalid TRON address length", "type": "value_error"}]}	Error en la validación del cuerpo de FastAPI/Pydantic. El estado es 422 Unprocessable Entity, no 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"}	Tráfico sostenido que supera los 50 req/sec en un nodo de Kong.
500	{"code": -1, "msg": "Internal server error"}	Falla inesperada del lado del servidor.

Límite de tasa

• 50 solicitudes / segundo por nodo de Kong (limit_by = ip, política local).
• No se establecen límites de minute / hour — solo se aplica el límite por segundo.
• Cada respuesta incluye los encabezados estándar de Kong: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, X-RateLimit-Limit-Second, X-RateLimit-Remaining-Second, y Retry-After en un 429.

Ejemplo de respuesta 429

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

Si está alcanzando 50 req/seg con una sola clave de API y necesita más, contacte al soporte — el límite se puede aumentar por clave, o se puede vincular un plugin de límite de tasa dedicado a su consumidor.

Encabezados de depuración

Cada respuesta también incluye identificadores útiles al abrir un ticket de soporte — por favor inclúyalos textualmente para que podamos encontrar la solicitud en nuestros registros en cuestión de segundos:

Encabezado	Significado
X-Request-ID	ID de solicitud del lado de la aplicación (generado por la calculadora).
X-Process-Time	Tiempo de procesamiento de la aplicación en milisegundos (upstream, excluyendo Kong).
X-Kong-Request-Id	ID de solicitud del lado de Kong (presente en los registros de acceso de Kong).

Tiempo de espera y reintentos del lado del cliente

La calculadora realiza consultas en vivo en la cadena a nodos de TRON para cada solicitud, por lo que bajo carga o con nodos upstream lentos una sola llamada puede tomar varios segundos. Los tiempos de espera cortos en el cliente fallarán incluso con respuestas correctas — esta es la causa raíz de la mayoría de los reportes de cURL error 28 (Connection timed out) por parte de los integradores.

Ajustes recomendados:

• Tiempo de espera ≥ 15 segundos (30 s es más seguro). El valor predeterminado de 10 s utilizado por muchos clientes HTTP es demasiado corto.
• En HTTP 429, respete el encabezado Retry-After (segundos). Agregue una pequeña variación aleatoria (jitter, ej. 0–200 ms) antes de reintentar, luego use retroceso exponencial si continúa alcanzando el límite de 50 req/seg.
• En HTTP 5xx o errores de red, reintente como máximo 2–3 veces con retroceso exponencial; no sobrecargue el endpoint.
• Almacene en caché el resultado del lado del cliente durante 30–60 segundos por cada par (sender_address, receiver_address) — los precios de recursos subyacentes y el estado en la cadena rara vez cambian tan rápido como para justificar un recálculo más frecuente.

Soporte para navegadores / CORS

Este endpoint está diseñado para integraciones servidor a servidor y actualmente no admite llamadas directas desde un navegador: la aplicación FastAPI upstream solo anuncia Access-Control-Allow-Methods: GET, por lo que la comprobación previa OPTIONS para un POST de origen cruzado fallará en los navegadores.

Si necesita llamar a la calculadora desde la interfaz de un navegador, canalice la solicitud a través de su propio back-end (que contiene la clave de API) en lugar de exponer la clave al cliente.

TIP

Si su caso de uso requiere legítimamente un POST del lado del navegador con una clave de API (por ejemplo, un panel interno de confianza en un origen conocido), contacte al soporte — se puede vincular un plugin de CORS a nivel de Kong para su ruta.

Notas

• El formato de respuesta es intencionalmente idéntico al del endpoint público, por lo que el código del cliente que analiza la respuesta pública continúa funcionando después de que migre a la variante autenticada — solo cambia la llamada en sí.
• Se aceptan tanto X-API-KEY: {key} (preferido, consistente con /apiv2/order1h) como Authorization: Bearer {key} / Authorization: {key}; si se envían ambos, prevalece X-API-KEY.
• La interposición de Cloudflare / proxy inverso no afecta a este endpoint de la misma manera que afecta al público, porque el tráfico autenticado está limitado por tasa por nodo de Kong y se puede habilitar la semántica por consumidor bajo solicitud.