跨页选择钱包

按筛选条件一次读取可归集的钱包 ID，供三方随后发起批量归集。此操作不创建任务，也不预留钱包。

POST /open/v1/wallets/selection

需要当前租户的 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
Content-Type	string	是	JSON 对象，UTF-8；允许 application/json; charset=UTF-8。	application/json

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

JSON 请求体

无路径参数，不需要 Query。必须提供 filters 对象，可为空对象。只允许 filters 这个顶层字段；不要传 request_id。

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

json

{
  "filters": {
    "hide_zero": true,
    "usdt_min": "100000000"
  }
}

金额和时间边界与钱包列表一致。JSON 中零余额开关可用布尔值，也接受字符串 "true" / "false"。金额、地址、时间和排序字段必须使用字符串，类型错误返回400；最小金额不能超过最大金额。

不分页，始终按钱包 ID 升序；sort、order 若传入仍会校验允许值，但不会改变结果顺序。filters.page、filters.page_size 和其他未知字段返回400。可选择记录超过 1000 个时返回 400，不静默截断；请缩小筛选范围。

忙碌钱包（归集任务未结束）及归集目标地址对应的钱包会被排除。列表与 total 来源一致，total 就是返回数组长度。这只是查询快照；调用创建归集时仍逐钱包检查状态，因此选中不保证随后全部创建成功。本接口没有持久化幂等键，重复调用会重新查询当前状态。

成功响应

HTTP 200，Content-Type: application/json。

json

{
  "code": 0,
  "message": "",
  "data": {
    "network": "nile",
    "wallet_ids": [
      "123456789012345678"
    ],
    "total": 1
  }
}

字段	类型	必填	说明	示例值
code	integer	是	业务成功。	0
message	string	是	成功时为空字符串。	""
data	object	是	当前筛选条件下可用于归集的钱包ID清单及数量。	{}
data.network	string	是	资产所属网络：main（主网）或 nile（测试网络）。	"nile"
data.wallet_ids	string[]	是	符合条件且可选择的钱包 ID，升序，最多 1000 个。	[]
data.total	integer	是	wallet_ids 的实际长度。	1

失败响应

错误时 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`

超过 1000 个可选择钱包时返回 HTTP 400，invalid request: selection exceeds 1000 wallets。filters 缺失或不是对象返回 HTTP 400，invalid request。

json

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

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

完整字段与状态

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

跨页选择钱包 ​

请求头 ​

JSON 请求体 ​

成功响应 ​

失败响应 ​

完整字段与状态 ​

跨页选择钱包

请求头

JSON 请求体

成功响应

失败响应

完整字段与状态