GET /apiv2/usdt/{sender}&

计算 TRON USDT 转账成本（公开端点，无需 API 密钥）。

返回发送方和接收方账户的详细分析、资源需求（Energy/Bandwidth）以及推荐的成本路径。

速率限制较低 — 适用于偶尔调用 / 测试用途

此端点为全局共享，速率限制为 1 次请求/秒 和 60 次请求/分钟。当您的应用程序位于 Cloudflare 或其他反向代理之后时，该限制实际上可能会在通过同一边缘节点访问 Netts 的所有客户端之间共享，因此单个用户可能会在达到 60 次请求/分钟之前遇到 429 Too Many Requests。

对于偶发调用之外的任何需求，请使用需要身份验证的 POST /apiv2/usdt/analyze 端点 — 它具有更高的单密钥限制（50 次请求/秒）。

端点 URL

GET https://netts.io/apiv2/usdt/{sender}&{receiver}

URL 参数

参数	类型	必填	描述
sender	string	是	发送方的 TRON 地址
receiver	string	是	接收方的 TRON 地址

地址在路径中传递，以**与号（&）**分隔。两者都必须是有效的 base58 TRON 地址（34 个字符，以 T 开头，有效的校验和）。

请求示例

cURL

bash

curl "https://netts.io/apiv2/usdt/TFLit1TFohBtT2f8UVCLFVPmZxawxqByYe&TTKR9aQdJWTgXLK9cmzaDitT5VXE497thL"

Python

python

import requests

sender   = "TFLit1TFohBtT2f8UVCLFVPmZxawxqByYe"
receiver = "TTKR9aQdJWTgXLK9cmzaDitT5VXE497thL"

url = f"https://netts.io/apiv2/usdt/{sender}&{receiver}"
response = requests.get(url, timeout=15)

if response.status_code == 200:
    payload = response.json()
    data = payload["data"]
    print(f"Can transfer:        {data['can_transfer']}")
    print(f"Energy needed:       {data['requirements']['energy_needed']}")
    print(f"Bandwidth needed:    {data['requirements']['bandwidth_needed']}")
    print(f"Total cost (TRX):    {data['costs']['total_cost_trx']}")
    print(f"Recommended method:  {data['costs']['recommended_method']}")
elif response.status_code == 429:
    print("Rate-limited — retry after:", response.headers.get("Retry-After"), "s")
else:
    print("Error:", response.json())

响应

成功 (200 OK)

顶级外层结构：

json

{
    "status": "success",
    "data": { /* TransferAnalysis — 见下文 */ },
    "current_utc_time": "2026-04-23 11:54:13",
    "processing_time_ms": 19.27
}

`data` (TransferAnalysis)

字段	类型	描述
`sender`	`AddressInfo`	发送方的完整账户信息（余额、质押、质押代理、激活状态）。
`receiver`	`AddressInfo`	接收方的完整账户信息。
`requirements`	`Requirements`	转账所需的 Energy / Bandwidth（原始值 + 安全缓冲值）。
`costs`	`Costs`	燃烧与租赁成本明细及推荐方式。
`can_transfer`	`boolean`	如果以当前资源/价格可以执行转账，则为 `true`。
`issues`	`string[]`	分析期间检测到的问题（例如 Bandwidth 不足）。
`recommendations`	`string[]`	针对客户端的人类可读建议。
`variation_id`	`string \| null`	匹配的内部变体目录中的场景 ID（例如 `"CUSTOM"`）。

`AddressInfo`

集成中常用的典型字段：address、is_activated、trx_balance、usdt_balance、has_usdt、energy_balance、bandwidth_balance。供高级使用的额外底层字段：trx_balance_sun、energy_total、bandwidth_total、bandwidth_free、bandwidth_staked、energy_used、bandwidth_used、create_time、latest_operation_time、staked_for_energy、staked_for_bandwidth、delegated_for_energy、delegated_for_bandwidth、delegated_out_energy、delegated_out_bandwidth、votes。

`Requirements`

字段	类型	描述
`energy_needed`	int	转账所需的原始 Energy 单位数。
`bandwidth_needed`	int	所需的原始 Bandwidth 单位数。
`energy_with_buffer`	int	向上取整至安全租赁档位的 Energy（例如 131 000）。
`bandwidth_with_buffer`	int	带有少量安全缓冲的 Bandwidth。
`receiver_has_usdt`	boolean	接收方是否已持有 USDT（会影响 Energy 消耗）。

`Costs`

字段	类型	描述
`energy_burn_trx`	decimal	如果通过直接燃烧支付 Energy 所需燃烧的 TRX。
`bandwidth_burn_trx`	decimal	如果 Bandwidth 无法免费获取，为覆盖 Bandwidth 所需燃烧的 TRX。
`total_burn_trx`	decimal	`energy_burn_trx + bandwidth_burn_trx`。
`total_burn_sun`	int	以 SUN（10⁻⁶ TRX）表示的 `total_burn_trx`。
`energy_rental_trx`	decimal	在以下周期内从 Netts 租赁所需 Energy 的费用。
`energy_rental_sun`	int	同上，但以 SUN 为单位。
`rental_time_period`	string	例如 `"1h"`、`"5m"`，当租赁不是最佳路径时为 `"not_needed"`。
`rental_price_per_unit`	int	所选周期内每单位 Energy 的租赁价格（单位：SUN）。
`savings_trx`	decimal	相比 `burn`，`rent` 可节省的金额（如果燃烧更划算，则可能为负数）。
`savings_percentage`	float	同上，以百分比表示。
`recommended_method`	string	`"burn"` 或 `"rent"` — 当前请求更便宜的选择。
`total_cost_trx`	decimal \| null	如果遵循 `recommended_method` 的实际成本。
`sender_activation_cost`	decimal \| null	如果发送方账户需要激活所产生的额外费用，否则为 `null`。

真实响应示例（节选）

json

{
    "status": "success",
    "data": {
        "sender":   { "address": "TFLit1...", "is_activated": true,  "trx_balance": 191.943, "usdt_balance": 24410.499, "energy_balance": 195297, "bandwidth_balance": 148, "has_usdt": true,  "...": "..." },
        "receiver": { "address": "TTKR9a...", "is_activated": true,  "trx_balance":  18.656, "usdt_balance":     0.0,   "energy_balance":      0, "bandwidth_balance": 263, "has_usdt": false, "...": "..." },
        "requirements": {
            "energy_needed": 130285,
            "bandwidth_needed": 345,
            "energy_with_buffer": 131000,
            "bandwidth_with_buffer": 360,
            "receiver_has_usdt": false
        },
        "costs": {
            "energy_burn_trx": 0.0,
            "bandwidth_burn_trx": 0.345,
            "total_burn_trx": 0.345,
            "total_burn_sun": 345000,
            "energy_rental_trx": 0.0,
            "energy_rental_sun": 0,
            "rental_time_period": "not_needed",
            "rental_price_per_unit": 0,
            "savings_trx": 0.0,
            "savings_percentage": 0.0,
            "recommended_method": "burn",
            "total_cost_trx": 0.345,
            "sender_activation_cost": null
        },
        "can_transfer": true,
        "issues": [
            "Insufficient bandwidth: have 148, need 345. Network will burn 0.345 TRX for full amount"
        ],
        "recommendations": [
            "Insufficient bandwidth: have 148, need 345. Full amount of 0.345 TRX will be burned",
            "💰 Total cost: 0.345 TRX (burn for all resources)"
        ],
        "variation_id": "CUSTOM"
    },
    "current_utc_time": "2026-04-23 11:54:13",
    "processing_time_ms": 19.27
}

错误

HTTP	响应体（示例）	触发条件
400	`{"code": -1, "msg": "Invalid sender address format: Txyz..."}`	地址未通过 TRON base58 / 长度 / 校验和验证。
400	`{"code": -1, "msg": "Expected at least 2 parameters: sender&receiver"}`	URL 未包含由 `&` 分隔的两个地址。
400	`{"code": -1, "msg": "Sender and receiver cannot be the same address"}`	发送方和接收方地址相同。
429	`{"message": "API rate limit exceeded"}`	超出速率限制（请参阅本页顶部的警告）。
500	`{"code": -1, "msg": "Internal server error"}`	非预期的服务器端错误。

速率限制响应头

在每个响应（包括 429）中都会返回以下标头：

标头	含义
`X-RateLimit-Limit-Second`	每秒允许的最大请求数（当前为 `1`）。
`X-RateLimit-Remaining-Second`	本秒内您仍可发送的请求数。
`X-RateLimit-Limit-Minute`	每分钟允许的最大请求数（当前为 `60`）。
`X-RateLimit-Remaining-Minute`	本分钟内您仍可发送的请求数。
`Retry-After`	在 429 错误时 — 重试前需要等待的秒数。

调试响应头

每个响应还携带在提交支持工单时非常有用的标识符 — 请完整附带这些信息，以便我们能在几秒钟内在日志中找到该请求：

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

客户端超时与重试

计算器对每个请求都会针对 TRON 节点执行实时链上查询，因此在高负载或上游节点较慢的情况下，单次调用可能会耗时数秒。过短的客户端超时设置会导致即便响应正常也会失败。

建议的设置：

超时时间 ≥ 15 秒（30 秒更安全）。许多 HTTP 客户端默认使用的 10 秒过短。
遇到 HTTP 429 时，请严格遵守 Retry-After 标头（秒）。在重试前添加微小的随机抖动（例如 0–200 毫秒），如果仍然触发限制，则使用指数退避策略。
遇到 HTTP 5xx 或网络错误时，最多使用指数退避重试 2–3 次；切勿频繁连续轰炸端点。
在客户端对每个 (sender, receiver) 地址对将结果缓存 30–60 秒 — 底层资源价格和链上状态很少会发生迅速变化而需要更频繁地重新计算。

429 响应示例

http

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

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

说明

匿名访问：无需 X-API-KEY，无需 Authorization 标头，无 IP 白名单限制。
响应始终包裹在 {status, data, current_utc_time, processing_time_ms} 中 — 集成时应从 data.costs 读取价格信息，从 data.requirements 读取资源需求。
响应是实时计算的 — 反映了来自 Netts 的当前 TRON 资源价格以及两个地址当前的链上状态，因此连续调用之间可能会有细微差异。
如果您的应用程序需要每分钟调用计算器超过数次（按每个 IP / 每个 CF 边缘节点计算），请改用附带 API 密钥的 POST /apiv2/usdt/analyze。

GET /apiv2/usdt/{sender}& ​

端点 URL ​

URL 参数 ​

请求示例 ​

cURL ​

Python ​

响应 ​

成功 (200 OK) ​

data (TransferAnalysis) ​

AddressInfo ​

Requirements ​

Costs ​

真实响应示例（节选） ​

错误 ​

速率限制响应头 ​

调试响应头 ​

客户端超时与重试 ​

429 响应示例 ​

说明 ​