POST /apiv2/usdt/analyze

计算 TRON USDT 转账成本（私有端点 — 需鉴权）。

返回与公开 GET 变体完全相同的 TransferAnalysis 数据载荷，但具有高得多的速率限制（每个 Kong 节点 50 请求/秒，而非 1 请求/秒），且请求数据通过 JSON 请求体传递而非 URL。任何生产环境集成请使用此端点。

端点 URL

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

身份验证

接受以下两个请求头中的任意一个（两者同时支持；优先推荐 X-API-KEY，因为它与 Netts 其余 /apiv2/* API 保持一致）：

请求头	是否必填	说明
Content-Type	是	必须为 application/json。
X-API-KEY	推荐	您的 Netts API 密钥 — 与用于 /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 请求头

如果您已经使用 X-API-KEY: {key} 调用 /apiv2/order1h，您可以向 /apiv2/usdt/analyze 发送完全相同的 X-API-KEY 请求头 — 计算器现已将其识别为主身份验证头。

请求体

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

字段

字段	类型	是否必填	约束
sender_address	字符串	是	有效的 TRON 地址 — 34 个字符，以 T 开头，具有有效的 base58 校验和。
receiver_address	字符串	是	有效的 TRON 地址；必须不同于 sender_address。

TIP

没有 amount 字段。计算器返回两个地址之间单笔 USDT 转账的成本和资源需求；如果您需要特定 USDT 金额的明细，请在您本地将建议的 Energy 乘以转账次数 — 无论金额大小，单笔 TRC-20 USDT 转账消耗的 Energy 均约为 130 k。

请求示例

cURL（推荐 — 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（替代方案 — 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())

响应

成功 (200 OK)

与公开端点完全相同的信封格式：

{
    "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"}	单个 Kong 节点上的持续流量超过 50 req/sec。
500	{"code": -1, "msg": "Internal server error"}	意外的服务器端故障。

速率限制

• 每个 Kong 节点 50 请求/秒（limit_by = ip，策略为 local）。
• 未设置 minute / hour 限制 — 仅适用每秒限制。
• 每个响应均携带标准 Kong 响应头： RateLimit-Limit、RateLimit-Remaining、RateLimit-Reset、 X-RateLimit-Limit-Second、X-RateLimit-Remaining-Second， 以及在返回 429 时的 Retry-After。

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

如果您使用单个 API 密钥达到了 50 请求/秒且需要更多额度，请联系客服 — 可以针对特定密钥提高限制，或为您的 Consumer 绑定专用的速率限制插件。

调试响应头

每个响应还携带在提交支持工单时非常有用的标识符 — 请原样提供它们，以便我们在几秒钟内在日志中找到该请求：

请求头	含义
X-Request-ID	应用端请求 ID（由计算器生成）。
X-Process-Time	应用处理时间，以毫秒为单位（上游耗时，不包括 Kong）。
X-Kong-Request-Id	Kong 端请求 ID（存在于 Kong 访问日志中）。

客户端超时与重试

计算器针对每个请求对 TRON 节点执行实时链上查询，因此在负载较高或上游节点较慢的情况下，单次调用可能需要几秒钟。较短的客户端超时时间即使在响应正常时也会失败 — 这是集成方报告的大多数 cURL error 28 (Connection timed out) 的根本原因。

推荐设置：

• 超时时间 ≥ 15 秒（30 秒更安全）。许多 HTTP 客户端默认使用的 10 秒过短。
• 遇到 HTTP 429 时，遵循 Retry-After 请求头（秒）。在重试前添加轻微抖动（例如 0–200 毫秒），如果仍触发 50 请求/秒限制，请使用指数退避算法。
• 遇到 HTTP 5xx 或网络错误时，使用指数退避算法重试最多 2–3 次；切勿对端点进行高频重试攻击。
• 客户端对每个 (sender_address, receiver_address) 键值对将结果缓存 30–60 秒 — 底层资源价格和链上状态很少会发生迅速变动以致需要更频繁地重新计算。

浏览器 / CORS 支持

此端点专为服务端对服务端集成而设计，目前不支持直接从浏览器调用：上游 FastAPI 应用仅声明了 Access-Control-Allow-Methods: GET，因此跨域 POST 的预检 OPTIONS 请求在浏览器中将会失败。

如果您需要从浏览器前端调用计算器，请通过您自己的后端代理该请求（后端持有 API 密钥），而不是直接将密钥暴露给客户端。

TIP

如果您的业务场景确实需要使用 API 密钥进行浏览器端 POST（例如已知源上的受信任内部控制台），请联系客服 — 可以在 Kong 层面为您的路由绑定 CORS 插件。

说明

• 响应格式特意与公开端点保持完全一致，因此在您迁移到需鉴权的变体后，解析公开响应的客户端代码仍可继续使用 — 仅调用方式本身发生变化。
• 同时接受 X-API-KEY: {key}（推荐，与 /apiv2/order1h 保持一致）和 Authorization: Bearer {key} / Authorization: {key}；如果两者均已发送，以 X-API-KEY 为准。
• Cloudflare / 反向代理介入对该端点的影响与公开端点不同，因为鉴权流量基于每个 Kong 节点进行速率限制，并可根据需求启用基于每个 Consumer 的语义。