钱包详情

按钱包 ID 查询当前租户和当前网络的一个钱包。返回余额同步快照及当前归集配置，不返回私钥。

GET /open/v1/wallets/{id}

需要当前租户的 Bearer accessToken，并对每次请求签名。先获取 accessToken，再按签名规则调用。只返回当前账户的数据，请求不传 network 或 tenant_id。

请求头

字段	类型	必填	说明	示例值
X-App-Id	string	是	平台分配的 appID，规范正 int64 十进制字符串，只能传一次。	123456789012345001
X-Timestamp	string	是	当前 Unix 秒级时间戳，服务器时间前后 300 秒内，只能传一次。	1893456000
X-Sign	string	是	按请求签名生成的 64 位小写 HMAC-SHA256；包含本次 accessToken、规范查询串和原始请求体。	按本次请求计算
Authorization	string	是	Bearer 后跟当前有效的 accessToken；只能传一次。	Bearer AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA

不接受 Idempotency-Key。示例中的凭据、时间戳、地址、ID 均为虚构示例，不能直接调用；实际请求必须重新生成时间戳及签名。

路径参数

字段	类型	必填	说明	示例值
id	string	是	正 int64 钱包 ID；推荐原样使用创建/列表返回值。最大 9223372036854775807。	123456789012345678

不接受 network 查询参数，无请求体。路径 id 决定查询对象；不存在、不属于本租户或不属于当前网络都返回 404。没有分页，没有写入或幂等要求。

destination 是租户统一的归集配置，不是每个钱包独立设置的目标。collection_status=collecting表示该网络存在未结束的归集任务。

成功响应

HTTP 200，Content-Type: application/json。

json

{
  "code": 0,
  "message": "",
  "data": {
    "network": "nile",
    "id": "123456789012345678",
    "address": "TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM",
    "custom_id": "customer-001",
    "chain": "TRON",
    "collection_status": "idle",
    "balance_usdt": "100000000",
    "balance_trx": "30000000",
    "balance_block": "12345678",
    "destination": "TAt8Du9Xw2CmrTHRawGETwiEKpNuKDSjE8",
    "collected_usdt": "0",
    "last_collected_at": null,
    "created_at": "2030-01-01T00:00:00Z"
  }
}

字段	类型	必填	说明	示例值
code	integer	是	业务成功。	0
message	string	是	成功时为空字符串。	""
data	object	是	本次请求的业务结果；完整字段如下。	见 JSON 示例
data.id	string	是	钱包 ID。	"123456789012345678"
data.address	string	是	平台生成的 TRON Base58Check 收款地址。	"TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM"
data.custom_id	string	是	租户自定义 ID；同一租户内唯一，1–32 个字符，不允许首尾空白。	"customer-001"
data.chain	string	是	所属链。	"TRON"
data.network	string	是	资产所属网络：main（主网）或 nile（测试网络）。	"nile"
data.collection_status	string	是	idle：暂无任务；collecting：存在任一未结束的归集任务。可选：`idle`, `collecting`。	"idle"
data.balance_usdt	string / null	是	已同步的 USDT 余额；最小单位的整数字符串，六位精度，禁止用浮点数处理。	"100000000"
data.balance_trx	string / null	是	已同步的 TRX 余额，单位 SUN；最小单位的整数字符串，六位精度，禁止用浮点数处理。	"30000000"
data.balance_block	string	是	余额同步时的固化区块参考高度。0 表示尚未完成首次同步；不是实际链上余额为零的证明。	"12345678"
data.destination	string	是	当前租户统一配置的 USDT 归集地址；未绑定时为空字符串，可为外部地址。	"TAt8Du9Xw2CmrTHRawGETwiEKpNuKDSjE8"
data.collected_usdt	string	是	累计成功归集 USDT 金额；最小单位的整数字符串，六位精度，禁止用浮点数处理。	"0"
data.last_collected_at	string / null	是	最近一次成功归集时间；从未归集为 null。	null
data.created_at	string	是	钱包创建时间。	"2030-01-01T00:00:00Z"

失败响应

错误时 HTTP 状态码与 code 一致，JSON 只含 code、message，不含 data。

HTTP	情况	message 示例
400	参数或请求格式错误	`invalid request`
401	签名、时间窗口或令牌无效	`authentication required or expired`
403	租户停用、删除或过期	`tenant disabled or expired`
404	对象不存在，或不属于当前租户和网络	`not found`
413	请求体超过大小限制	`request body exceeds configured limit`
429	请求频率超限；读取 Retry-After 秒数	`too many requests`
500	内部依赖或业务执行失败	`internal operation failed`
503	HTTP 并发槽已满；Retry-After 为 1 秒	`too many in-flight requests`
504	操作超过请求截止时间	`request timed out`

非法或非正整数 id 返回 HTTP 400，invalid request: id required。

json

{
  "code": 400,
  "message": "invalid request",
  "error_code": "INVALID_ARGUMENT",
  "trace_id": "0123456789abcdef0123456789abcdef"
}

完整字段格式、路由错误与重试约定见通用约定。

待同步余额

balance_block为"0"时，balance_usdt、balance_trx为null，请显示“待同步”。完成同步后返回的字符串"0"才表示确认余额为零。

完整字段与状态

查看全部响应字段、嵌套对象及枚举 · 业务状态与处理 · 错误码排查。

钱包详情 ​

请求头 ​

路径参数 ​

成功响应 ​

失败响应 ​

待同步余额 ​