POST /apiv2/usdt/analyze

Calcular o custo de transferência de USDT na TRON (endpoint privado — autenticado).

Retorna exatamente a mesma carga útil de TransferAnalysis que a variante pública GET, mas com um limite de taxa muito mais alto (50 req/seg por nó do Kong em vez de 1/seg) e com os dados da requisição enviados em um corpo JSON em vez da URL. Use este endpoint para qualquer integração em produção.

URL do endpoint

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

Autenticação

Qualquer um dos dois cabeçalhos a seguir é aceito (ambos suportados simultaneamente; X-API-KEY é o preferido porque corresponde ao restante da superfície da API /apiv2/* da Netts):

Cabeçalho	Obrigatório	Descrição
Content-Type	Sim	Deve ser application/json.
X-API-KEY	Preferido	Sua chave de API da Netts — exatamente o mesmo formato usado para /apiv2/order1h e outros endpoints autenticados da Netts.
Authorization	Aceito como alternativa	Bearer {key} ou apenas {key} (sem prefixo). Use isto se o seu cliente HTTP tiver um fluxo integrado de bearer/auth.

Se ambos os cabeçalhos forem enviados, X-API-KEY terá prioridade.

Whitelist de IP: o IP a partir do qual a requisição atinge a nossa borda deve estar na whitelist configurada para a sua chave de API (mesmo mecanismo dos outros endpoints /apiv2/*). Requisições de um IP fora da whitelist retornam 401 Unauthorized com "Invalid API key or IP not in whitelist".

Reutilizando seus cabeçalhos do order1h

Se você já chama /apiv2/order1h com X-API-KEY: {key}, você pode enviar exatamente o mesmo cabeçalho X-API-KEY para /apiv2/usdt/analyze — a calculadora agora o reconhece como o cabeçalho de autenticação principal.

Corpo da requisição

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

Campos

Campo	Tipo	Obrigatório	Restrições
sender_address	string	Sim	Endereço TRON válido — 34 caracteres, começa com T, checksum base58 válido.
receiver_address	string	Sim	Endereço TRON válido; deve ser diferente de sender_address.

TIP

Não há campo amount. A calculadora retorna o custo e os requisitos de recursos para uma única transferência de USDT entre os dois endereços; se você precisar do detalhamento para uma quantia específica de USDT, multiplique a Energy recomendada pela contagem de transferências do seu lado — uma única transferência de USDT TRC-20 consome os mesmos ~130 k de Energy, independentemente do valor.

Exemplos de requisição

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

Resposta

Sucesso (200 OK)

Envelope idêntico ao do 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
}

A descrição completa campo a campo de data está na página do endpoint público — consulte TransferAnalysis, AddressInfo, Requirements e Costs.

Erros

Ordem das validações

A autenticação é validada antes da validação do corpo. Se o cabeçalho Authorization estiver ausente/inválido ou seu IP não estiver na whitelist, você sempre verá 401 — mesmo se o corpo JSON também estiver malformado. Corrija a autenticação primeiro, depois teste novamente com uma chave válida; somente então os erros de validação de corpo do Pydantic (422) aparecerão.

HTTP	Corpo	Quando
401	{"code": -1, "msg": "API key not provided (expected X-API-KEY or Authorization header)"}	Nenhum cabeçalho X-API-KEY ou Authorization presente.
401	{"code": -1, "msg": "Invalid API key or IP not in whitelist"}	Chave desconhecida, ou IP da requisição fora da sua whitelist.
404	{"code": -1, "msg": "User not found"}	Chave válida, mas o registro do usuário não foi encontrado (raro).
422	{"detail": [{"loc": ["body","sender_address"], "msg": "Invalid TRON address length", "type": "value_error"}]}	Falha na validação do corpo pelo FastAPI/Pydantic. O status é 422 Unprocessable Entity, não 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áfego contínuo acima de 50 req/sec em um nó do Kong.
500	{"code": -1, "msg": "Internal server error"}	Falha inesperada no lado do servidor.

Limite de taxa

• 50 requisições / segundo por nó do Kong (limit_by = ip, política local).
• Limites de minute / hour não estão configurados — apenas o limite por segundo se aplica.
• Cada resposta traz os cabeçalhos padrão do Kong: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, X-RateLimit-Limit-Second, X-RateLimit-Remaining-Second, e Retry-After em um 429.

Exemplo de resposta 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

Se você estiver atingindo 50 req/seg com uma única chave de API e precisar de mais, entre em contato com o suporte — o limite pode ser aumentado por chave, ou um plugin dedicado de limite de taxa pode ser associado ao seu consumidor.

Cabeçalhos de depuração

Cada resposta também carrega identificadores úteis ao abrir um ticket de suporte — inclua-os textualmente para que possamos localizar a requisição em nossos logs em segundos:

Cabeçalho	Significado
X-Request-ID	ID da requisição no lado da aplicação (gerado pela calculadora).
X-Process-Time	Tempo de processamento da aplicação em milissegundos (upstream, excluindo o Kong).
X-Kong-Request-Id	ID da requisição no lado do Kong (presente nos logs de acesso do Kong).

Timeout e novas tentativas no lado do cliente

A calculadora realiza consultas on-chain em tempo real aos nós da TRON para cada requisição, portanto, sob carga ou nós upstream lentos, uma única chamada pode levar vários segundos. Timeouts curtos no cliente falharão mesmo em respostas saudáveis — esta é a causa raiz da maioria dos relatos de cURL error 28 (Connection timed out) vindos de integradores.

Configurações recomendadas:

• Timeout ≥ 15 segundos (30 s é mais seguro). O padrão de 10 s utilizado por muitos clientes HTTP é muito curto.
• No HTTP 429, respeite o cabeçalho Retry-After (segundos). Adicione uma pequena variação (ex.: 0–200 ms) antes de tentar novamente, depois use recuo exponencial se você ainda atingir o limite de 50 req/seg.
• No HTTP 5xx ou erros de rede, tente novamente no máximo 2–3 vezes com recuo exponencial; não sobrecarregue o endpoint.
• Armazene o resultado em cache no lado do cliente por 30–60 segundos por par (sender_address, receiver_address) — os preços dos recursos subjacentes e o estado on-chain raramente mudam rápido o suficiente para justificar um recálculo mais frequente.

Suporte a Navegador / CORS

Este endpoint foi projetado para integrações servidor a servidor e atualmente não suporta chamadas diretas a partir de um navegador: a aplicação FastAPI upstream anuncia apenas Access-Control-Allow-Methods: GET, de modo que o preflight OPTIONS para um POST de origem cruzada falhará nos navegadores.

Se você precisar chamar a calculadora a partir de um front-end de navegador, faça o proxy da requisição através do seu próprio back-end (que armazena a chave de API) em vez de expor a chave ao cliente de qualquer maneira.

TIP

Se o seu caso de uso exigir legitimamente um POST no lado do navegador com uma chave de API (por exemplo, um painel interno confiável em uma origem conhecida), entre em contato com o suporte — um plugin de CORS pode ser anexado no nível do Kong para a sua rota.

Observações

• O formato da resposta é intencionalmente idêntico ao do endpoint público, para que o código do cliente que faz o parse da resposta pública continue funcionando após você migrar para a variante autenticada — apenas a chamada em si é alterada.
• Tanto X-API-KEY: {key} (preferido, consistente com /apiv2/order1h) quanto Authorization: Bearer {key} / Authorization: {key} são aceitos; se ambos forem enviados, X-API-KEY terá prioridade.
• A interposição do Cloudflare / proxy reverso não afeta este endpoint da mesma forma que afeta o público, porque o tráfego autenticado tem limite de taxa por nó do Kong e semânticas por consumidor podem ser ativadas sob solicitação.