批量预览钱包
按固定钱包 ID 清单批量读取钱包快照，供归集前核对。输入去重并保序；任一 ID 不属于当前租户、网络则整体返回 404。
POST /open/v1/wallets/preview
请求头
| 字段 | 类型 | 必填 | 说明 | 示例值 |
|---|---|---|---|---|
| X-App-Id | string | 是 | 平台appID，规范正int64，只传一次。 | 123456789012345001 |
| X-Timestamp | string | 是 | 当前秒级时间戳，服务器时间前后300秒内。 | 1893456000 |
| X-Sign | string | 是 | 本次HMAC-SHA256签名，64位小写十六进制；按签名规则生成。 | 按本次请求计算 |
| Authorization | string | 是 | 当前有效accessToken，格式为 Bearer 后加令牌。 | Bearer <ACCESS_TOKEN> |
| Content-Type | string | 是 | 单个UTF-8 JSON对象。 | application/json |
认证只使用上表请求头；不要发送 Idempotency-Key。示例凭据、ID和地址是演示值，签名必须按实际参数和当前时间重新计算。
请求参数
无路径参数，不接受任何Query（包括仅有问号的URL）。以下字段全部放JSON，额外字段返回400。
| 字段 | 类型 | 必填 | 说明 | 示例值 |
|---|---|---|---|---|
| wallet_ids | string[] | 是 | 1–1000 个 ID，去重后保留请求顺序。 | [] |
json
{
"wallet_ids": [
"123456789012345678"
]
}业务规则
输入为1–1000个规范正int64钱包ID，重复ID按首次出现去重，返回顺序与去重后的输入一致。任一ID不存在或属于其他租户/网络，整个请求返回404，不返回部分列表。
返回完整钱包快照，包括collection_status、统一destination和余额同步高度。此接口不会锁定钱包，不排除归集目标或忙碌钱包；调用方可展示原因，再由创建归集接口独立校验。
本接口为只读POST，不需要request_id。与跨页选择不同，它读取你已经固定的ID清单；跨页选择则筛选可用钱包。
成功响应
HTTP 200，外层code=0、message为空字符串。
json
{
"code": 0,
"message": "",
"data": {
"network": "nile",
"items": [
{
"id": "123456789012345678",
"address": "TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM",
"custom_id": "customer-001",
"chain": "TRON",
"network": "nile",
"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.network | string | 是 | 资产所属网络：main（主网）或 nile（测试网络）。 | "nile" |
| data.items | object[] | 是 | 所选钱包，去重并按请求首次出现顺序返回；任何 ID 不属于当前租户和网络则整个请求失败。 | [] |
| data.items[].id | string | 是 | 钱包 ID。 | "123456789012345678" |
| data.items[].address | string | 是 | 平台生成的 TRON Base58Check 收款地址。 | "TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM" |
| data.items[].custom_id | string | 是 | 租户自定义 ID；同一租户内唯一，1–32 个字符，不允许首尾空白。 | "customer-001" |
| data.items[].chain | string | 是 | 所属链。 | "TRON" |
| data.items[].network | string | 是 | 资产所属网络：main（主网）或 nile（测试网络）。 | "nile" |
| data.items[].collection_status | string | 是 | idle：暂无任务；collecting：存在任一未结束的归集任务。 可选 idle, collecting。 | "idle" |
| data.items[].balance_usdt | string / null | 是 | 已同步的 USDT 余额；最小单位的整数字符串，六位精度，禁止用浮点数处理。 | "100000000" |
| data.items[].balance_trx | string / null | 是 | 已同步的 TRX 余额，单位 SUN；最小单位的整数字符串，六位精度，禁止用浮点数处理。 | "30000000" |
| data.items[].balance_block | string | 是 | 余额同步时的固化区块参考高度。0 表示尚未完成首次同步；不是实际链上余额为零的证明。 | "12345678" |
| data.items[].destination | string | 是 | 当前租户统一配置的 USDT 归集地址；未绑定时为空字符串，可为外部地址。 | "TAt8Du9Xw2CmrTHRawGETwiEKpNuKDSjE8" |
| data.items[].collected_usdt | string | 是 | 累计成功归集 USDT 金额；最小单位的整数字符串，六位精度，禁止用浮点数处理。 | "0" |
| data.items[].last_collected_at | string / null | 是 | 最近一次成功归集时间；从未归集为 null。 | null |
| data.items[].created_at | string | 是 | 钱包创建时间。 | "2030-01-01T00:00:00Z" |
失败响应
错误JSON没有data；HTTP状态与code一致。
| HTTP | 情况 |
|---|---|
| 400 | 参数缺失、类型/格式无效或存在不支持的字段 |
| 401 | accessToken、签名或签名时间窗口无效 |
| 403 | 租户停用、删除或过期 |
| 404 | 钱包不存在或不属于当前租户/网络 |
| 413 / 429 | 请求体过大 / 请求频率超限 |
| 500 / 503 / 504 | 内部依赖错误 / 资源或配置不可用 / 请求超时 |
json
{
"code": 401,
"message": "authentication required or expired",
"error_code": "TOKEN_INVALID_OR_EXPIRED",
"trace_id": "0123456789abcdef0123456789abcdef"
}通用错误说明Retry-After及重试处理；写请求不要因超时生成新的request_id。
业务错误示例
HTTP 400：钱包数量不在1至1000范围。
json
{
"code": 400,
"message": "invalid request: wallet_ids requires 1..1000 IDs",
"error_code": "INVALID_ARGUMENT",
"trace_id": "0123456789abcdef0123456789abcdef"
}HTTP 404：至少一个钱包不存在或不属于当前租户及网络。
json
{
"code": 404,
"message": "not found",
"error_code": "RESOURCE_NOT_FOUND",
"trace_id": "0123456789abcdef0123456789abcdef"
}待同步余额
balance_block为"0"时，balance_usdt、balance_trx为null，请显示“待同步”。完成同步后返回的字符串"0"才表示确认余额为零。
完整字段与状态
查看全部响应字段、嵌套对象及枚举 · 业务状态与处理 · 错误码排查。