钱包列表

分页读取收款钱包及余额快照，同时返回跨页不可归集选择的钱包清单。

GET /open/v1/wallets

需要当前租户的 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 均为虚构示例，不能直接调用；实际请求必须重新生成时间戳及签名。

Query 参数

字段	类型	必填	说明	示例值
page	integer（Query 文本）	否	页码 ≥1；不传或空字符串为 1。	1
page_size	integer（Query 文本）	否	每页 1–100 条；不传或空字符串为 20。	20
address	string	否	收款地址模糊匹配，不区分大小写；最长 100 个 UTF-8 字节。空字符串忽略，% 匹配任意长度内容，_ 匹配单个字符。	TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM
usdt_min	string	否	USDT 余额下限，包含边界；六位精度最小单位，0 至 2^256−1，不传或空字符串不限制。	100000000
usdt_max	string	否	USDT 余额上限，包含边界；六位精度最小单位，0 至 2^256−1，不传或空字符串不限制。	100000000
trx_min	string	否	TRX 余额下限，SUN，包含边界；0 至 2^256−1，不传或空字符串不限制。	100000000
trx_max	string	否	TRX 余额上限，SUN，包含边界；0 至 2^256−1，不传或空字符串不限制。	100000000
hide_zero	string（true/false）	否	true 只保留 USDT 余额大于 0 的钱包；不传为 false。	true
hide_zero_trx	string（true/false）	否	true 只保留 TRX 余额大于 0 的钱包；不传为 false。	true
last_collected_from	string	否	最近成功归集时间下限，包含边界；带时区 RFC3339，可含小数秒；不传或空字符串不限制。	2030-01-01T00:00:00Z
last_collected_to	string	否	最近成功归集时间上限，包含边界；不能早于 from；不传或空字符串不限制。	2030-01-02T00:00:00Z
sort	string	否	列表排序字段：created_at、balance_usdt、balance_trx、last_collected_at、collected_usdt；默认 created_at。selection 即使传入也始终按 ID 升序返回。	created_at
order	string	否	排序方向仅 asc / desc，默认 desc；selection 返回顺序不受此字段影响。	desc

无路径参数、无请求体。金额筛选使用最小单位，上下界均包含边界；最小金额超过最大金额时返回空结果，不自动调换。时间筛选会排除从未归集（last_collected_at=null）的钱包。时间起点晚于终点返回 400。

hide_zero=true 过滤 USDT 零余额；hide_zero_trx=true 过滤 TRX 零余额，两者同时传入时同时满足。默认按 created_at desc；同值按钱包 ID 降序，空归集时间始终排最后。sort、order 传空字符串采用默认值。

unavailable_wallet_ids仅包含当前页及selected_wallet_ids指定钱包中的不可选ID，与本页钱包状态一致。

成功响应

HTTP 200，Content-Type: application/json。

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"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20,
    "unavailable_wallet_ids": []
  }
}

字段	类型	必填	说明	示例值
code	integer	是	业务成功。	0
message	string	是	成功时为空字符串。	""
data	object	是	本次请求的业务结果；完整字段如下。	见 JSON 示例
data.network	string	是	资产所属网络：main（主网）或 nile（测试网络）。	"nile"
data.items	object[]	是	本页钱包，无结果为 []。	[]
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"
data.total	integer	是	满足筛选条件的总记录数。	1
data.page	integer	是	当前页码。	1
data.page_size	integer	是	每页条数。	20
data.unavailable_wallet_ids	string[]	是	当前页及已选钱包中的不可选ID，ID升序。	[]

失败响应

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

HTTP	情况	message 示例
400	参数或请求格式错误	`invalid request`
401	签名、时间窗口或令牌无效	`authentication required or expired`
403	租户停用、删除或过期	`tenant disabled or expired`
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`

例如非法排序字段或金额会返回 400；起止时间反向时 message 为 invalid request: last_collected_from exceeds last_collected_to。

json

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

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

待同步余额

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

跨页选择

可选Query参数selected_wallet_ids为逗号分隔的钱包ID字符串，最多1000个。分页时传入已选ID，服务端返回其中及当前页正在被任务占用或用作归集地址的钱包，客户端据此移除不可选项。

完整字段与状态

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

钱包列表 ​

请求头 ​

Query 参数 ​

成功响应 ​

失败响应 ​

待同步余额 ​

跨页选择 ​

完整字段与状态 ​