通用约定
所有业务接口使用 /open/v1 路径前缀。API 域名由平台单独提供，本文档只列接口路径。请求地址由该域名与接口路径组合；不要使用文档站域名代替 API 域名。接口必须从三方服务端调用；平台依据认证信息识别租户，请求不传 tenant_id。
请求格式
GET 参数放在 URL 查询字符串中，请求体必须为空。业务 POST 使用 Content-Type: application/json，请求体为单个 JSON 对象。获取 Token 使用空请求体，具体要求见 Token 接口。
只接受接口声明的字段，未知参数返回400。查询参数不允许重复键；JSON 对象不允许重复属性；Query 与 Body 不允许同名参数。字段的必填性、允许值及是否可以为空，以对应接口页为准。
写接口的幂等编号是 JSON Body 中的 request_id，不要使用 Idempotency-Key 请求头。
成功与失败响应
成功响应使用 HTTP 200，并包含以下结构：
json
{
"code": 0,
"message": "",
"data": {}
}| 字段 | 类型 | 说明 |
|---|---|---|
code | integer | 业务请求成功为 0 |
message | string | 成功时为空字符串 |
data | object | 接口数据，结构见对应接口页 |
失败响应的 HTTP 状态码与 JSON code 一致，不包含 data：
json
{
"code": 401,
"message": "authentication required or expired",
"error_code": "TOKEN_INVALID_OR_EXPIRED",
"trace_id": "0123456789abcdef0123456789abcdef"
}先检查 HTTP 状态码，再判断 JSON code。异步或批量任务还需要检查 data 中逐项结果；不要把 HTTP 200 当作全部钱包归集成功。详见 错误处理 和 创建归集任务。
金额与精度
USDT 与 TRX 使用最小单位整数字符串，精度为 6。调用方应使用整数运算或十进制定点类型，不要通过 JavaScript Number 或二进制浮点数计算金额。
| 人类可读金额 | API 金额字符串 |
|---|---|
| 0 | "0" |
| 0.000001 | "1" |
| 1.02 | "1020000" |
| 100 | "100000000" |
正数金额的请求字段不接受负号、正号、小数点、前导零或空白。具体最大值和是否允许 0 / null，以对应接口页为准。
归集的 sweep_mode="all" 必须同时提交 requested_amount:null；sweep_mode="fixed" 提交正整数金额字符串。固定金额是每个钱包各归集该金额，不是整批钱包的总额。
ID、时间和空值
| 数据 | 格式 | 使用说明 |
|---|---|---|
| appID、钱包 ID、任务 ID、到账 ID | string | 不转换成浮点数；appID 是规范的正整数字符串 |
| 金额、链上区块高度 | string（以接口字段表为准） | 保留服务端格式 |
| 签名时间戳 | Unix 秒级时间戳字符串 | 放在 X-Timestamp，不是毫秒 |
| 日期时间 | RFC 3339 / ISO 8601 字符串 | 包含时区，例如 2026-09-08T11:30:00+08:00 |
null | JSON null | 表示字段当前无值；不要替换为空字符串或省略必传字段 |
网络与资产
响应和回调正文中的 network 表示该笔资产所属的 TRON 网络：
| 值 | 含义 |
|---|---|
| main | TRON 主网 |
| nile | TRON 测试网络 |
按平台为你开通的资产网络核对响应。不同网络的资产不互通，不能仅凭地址判断网络；识别代币时同时核对 network 和 contract。
network 是响应字段，不是请求参数。不要在 Query 或 JSON 中添加它；未声明的请求参数返回 INVALID_ARGUMENT。文档中的 nile 示例仅用于展示数据格式，不代表你的账户网络。
余额与到账的关系
余额和到账流水可能存在同步延迟。余额不是到账流水的加总：转出、手续费和同步进度都可能让两者不同。查询时结合 balance_block、到账 status 和 revision 判断；不能把暂时未查到记录当作未发生转账。
分页与筛选
列表通常返回 items、total、page、page_size。具体分页范围、排序字段、金额筛选、时间筛选和是否存在扩展字段，以各列表接口的请求及响应表为准。
归集目标从租户统一配置读取，任务不接受临时目标。免费带宽不足时等待恢复；能量依次使用现有能量、钱包足额 TRX、CatFee 租赁，零 TRX 钱包也可使用租赁路径。
错误与追踪编号
错误响应固定包含 code、error_code、message、trace_id。程序依据 error_code 处理，message 用于查看具体原因；trace_id 可提供给平台定位日志。所有 API 响应均携带 X-Trace-Id。它由平台生成，与你传入的写操作幂等编号 request_id 无关，接入方不需要新增任何请求参数。