归集记录列表
分页查询当前账户、当前网络的 USDT 归集任务，可按任务状态或地址筛选。这里只返回 sweep 任务。
本页的 ID、地址、交易哈希、时间及金额均为文档示例；请使用自己账户的数据。金额以六位精度的最小单位字符串表示，例如 "100000000" 代表 100 USDT，"1000000" SUN 代表 1 TRX。
请求地址
http
GET /open/v1/sweeps鉴权请求头
先获取 access token，再按签名规则为实际请求生成签名。四个鉴权头必须且只能提供一次，内容和签名须与实际发送的请求一致。
| 字段 | 类型 | 必填 | 说明 | 示例值 |
|---|---|---|---|---|
| X-App-Id | string | 是 | 规范正整数 appID，必须且只能提供一次。 | 1234567890 |
| X-Timestamp | string | 是 | 当前 Unix 秒级时间戳，规范十进制字符串；有效时间窗口见签名指南。 | 1788825600 |
| X-Sign | string | 是 | 本次请求的 64 位小写十六进制 HMAC-SHA256 签名，必须且只能提供一次。 | <本次请求签名> |
| Authorization | string | 是 | 必须且只能提供一次，使用当前有效 token。 | Bearer <ACCESS_TOKEN> |
查询参数
GET 请求体必须为空，不需要 JSON body。未提供或值为空的分页参数采用默认值。
| 字段 | 类型 | 必填 | 说明 | 示例值 |
|---|---|---|---|---|
| page | integer（query 字符串） | 否 | 页码，从 1 开始，默认 1。 | 1 |
| page_size | integer（query 字符串） | 否 | 每页 1–100 条，默认 20。 | 20 |
| status | string | 否 | 按任务状态精确匹配；为空时不限制。状态含义见下方；未知值不会报枚举错误，而是通常返回空列表。 | succeeded |
| address | string | 否 | 大小写不敏感的包含查询，同时匹配收款钱包地址和归集目标地址；为空时不限制。 | TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM |
http
GET /open/v1/sweeps?page=1&page_size=20&status=succeeded返回顺序固定为任务 ID 降序。sort、order 不控制排序；其他未支持的 query 字段不会扩展过滤条件。地址查询中的 % 和 _ 按 LIKE 通配符处理，不能将此参数当作严格地址等值查询。
成功响应
HTTP 200，即使没有匹配记录也返回成功分页对象。
| 字段 | 类型 | 必填 | 说明 | 示例值 |
|---|---|---|---|---|
| code | integer | 是 | 业务请求成功时固定为 0。 | 0 |
| message | string | 是 | 成功时固定为空字符串。 | "" |
| data | object | 是 | 当前筛选条件的分页结果。 | 见下方 JSON 示例 |
| data.network | string | 是 | 资产所属网络：main（主网）或 nile（测试网络）。 | "nile" |
| data.items | object[] | 是 | 当前页数据；没有匹配记录时为 []。 | [] |
| data.total | integer | 是 | 符合当前筛选条件的记录总数，不是当前页数量。 | 1 |
| data.page | integer | 是 | 当前页码，从 1 开始。 | 1 |
| data.page_size | integer | 是 | 每页数量。 | 20 |
每个 data.items[] 的完整字段
| 字段 | 类型 | 必填 | 说明 | 示例值 |
|---|---|---|---|---|
| id | string | 是 | 归集任务 ID。 | 123456789012345680 |
| wallet_id | string | 是 | 执行归集的收款钱包 ID。 | 123456789012345678 |
| address | string | 是 | 收款钱包地址，即本次 USDT 转出的来源地址。 | TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM |
| kind | string | 是 | 此接口仅返回归集任务，固定为 sweep。 | sweep |
| sweep_mode | string | 是 | 归集方式：all 为全额，fixed 为固定金额。 | fixed |
| requested_amount | string 或 null | 是 | 用户最初请求的每钱包金额；all 为 null，fixed 为正整数最小单位字符串。 | "100000000" |
| amount | string | 是 | 任务准备时确定的实际转账金额，USDT 最小单位；尚未准备时可能为 "0"。 | "100000000" |
| destination | string | 是 | 此任务保存的 USDT 归集目标地址。 | TAt8Du9Xw2CmrTHRawGETwiEKpNuKDSjE8 |
| status | string | 是 | 任务状态，完整枚举见下方说明。 | succeeded |
| reason | string | 是 | 任务失败、取消或其他状态原因；无原因时为空字符串。 | "" |
| txid | string | 是 | 已保存的交易哈希；尚未生成时为空字符串。 | 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef |
| actual_fee | string | 是 | 任务已结算的实际链上手续费，单位 SUN；未结算时通常为 "0"。 | "1000000" |
| created_at | string | 是 | 任务创建时间，带时区。 | 2026-09-08T00:00:00Z |
| updated_at | string | 是 | 任务最近更新时间，带时区。 | 2026-09-08T00:01:00Z |
| webhook | object 或 null | 是 | 关联的回调事件摘要；没有关联事件时为 null。回调状态不改变链上业务结果。 | null |
| webhook.id | string | 事件存在时 | 回调事件 ID。 | 123456789012345680 |
| webhook.event_type | string | 事件存在时 | 事件类型；归集为 sweep.succeeded / sweep.failed / sweep.cancelled，到账为 deposit.confirmed。 | sweep.succeeded |
| webhook.status | string | 事件存在时 | 回调状态：pending / delivering / delivered / failed。 | delivered |
| webhook.attempts | integer | 事件存在时 | 当前回调轮次已尝试次数。 | 1 |
| webhook.current_round | integer | 事件存在时 | 当前回调轮次，从 1 开始。 | 1 |
| webhook.next_attempt | string 或 null | 事件存在时 | 下次尝试时间，带时区；没有后续计划时为 null。 | null |
| webhook.deadline_at | string | 事件存在时 | 当前轮次截止时间，带时区。 | 2026-09-08T00:11:00Z |
| webhook.last_error | string | 事件存在时 | 最近一次回调错误；没有错误时为空字符串。 | "" |
| webhook.created_at | string | 事件存在时 | 回调事件创建时间，带时区。 | 2026-09-08T00:01:00Z |
| webhook.delivered_at | string 或 null | 事件存在时 | 回调成功送达时间，未送达时为 null。 | 2026-09-08T00:01:02Z |
任务状态
pending：任务已创建，等待准备。ready：金额和费用授权已准备，等待签名。signed：交易已签名并保存。broadcast：交易已广播，等待确认。unknown：广播或交易结果暂不确定，继续等待确认；不代表成功或可以重复转账。succeeded：归集成功。failed：归集失败。cancelled：任务已取消。
succeeded、failed、cancelled 为终态。回调的 webhook.status 是独立状态；例如归集成功后，回调仍可能处于 pending 或 failed。
json
{
"code": 0,
"message": "",
"data": {
"network": "nile",
"items": [
{
"id": "123456789012345680",
"wallet_id": "123456789012345678",
"address": "TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM",
"kind": "sweep",
"sweep_mode": "fixed",
"requested_amount": "100000000",
"amount": "100000000",
"destination": "TAt8Du9Xw2CmrTHRawGETwiEKpNuKDSjE8",
"status": "succeeded",
"reason": "",
"txid": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"actual_fee": "1000000",
"created_at": "2026-09-08T00:00:00Z",
"updated_at": "2026-09-08T00:01:00Z",
"webhook": {
"id": "123456789012345680",
"event_type": "sweep.succeeded",
"status": "delivered",
"attempts": 1,
"current_round": 1,
"next_attempt": null,
"deadline_at": "2026-09-08T00:11:00Z",
"last_error": "",
"created_at": "2026-09-08T00:01:00Z",
"delivered_at": "2026-09-08T00:01:02Z",
"network": "nile"
},
"preparation_stage": "ready",
"energy_rental": null,
"fee_source": null,
"prepared_energy": null,
"estimated_wallet_trx_fee": null,
"max_wallet_trx_fee": null,
"actual_bandwidth_fee": null,
"fee_warning": null,
"network": "nile"
}
],
"total": 1,
"page": 1,
"page_size": 20
}
}无匹配结果或请求页超出结果范围时，items=[]。total 始终表示筛选后的总数；超出页码时不一定为 0。
列表中的 requested_amount 保留原请求，amount 表示准备结果；不要把待准备任务的 "0" 当作已完成零金额转账。归集目标保存于任务中，已签名任务继续使用原目标。完整单条查询见归集详情。
这是查询接口，不需要 request_id；不要发送 Idempotency-Key 请求头。
典型错误
错误响应不包含 data。鉴权、租户状态、限流、超时等通用处理见通用错误说明。
HTTP 400：分页范围无效
json
{
"code": 400,
"message": "invalid request: invalid pagination",
"error_code": "INVALID_ARGUMENT",
"trace_id": "0123456789abcdef0123456789abcdef"
}HTTP 401：token 缺失、无效或已过期
json
{
"code": 401,
"message": "authentication required or expired",
"error_code": "TOKEN_INVALID_OR_EXPIRED",
"trace_id": "0123456789abcdef0123456789abcdef"
}租赁执行阶段
status=pending 时通过 preparation_stage 区分 queued（排队）、waiting_bandwidth（等待带宽）、renting（租赁中）、waiting_energy（等待能量到账）；ready 为资源就绪。等待期间钱包处于归集中。
energy_rental 为本任务唯一租赁订单，未租赁为null；包含 order_id、quantity、estimated_cost、paid_cost、activation_cost、state、expires_at。费用均为SUN，与链上 actual_fee 分开统计。结果未知时保留原订单号继续核验，过期或交付不足不会续租。
费用来源及实际扣费
归集使用自身能量 → 自身TRX支付完整能量缺口 → 平台CatFee租赁的顺序。免费带宽不足先等待，不燃烧TRX支付带宽、不购买带宽。
| 字段 | 类型 | 说明 |
|---|---|---|
| fee_source | string / null | resources、wallet_trx、catfee；历史或尚未准备时为null。 |
| prepared_energy | string / null | 准备时的能量额度，包含10%余量。 |
| estimated_wallet_trx_fee | string / null | 准备时预计钱包TRX消耗，SUN。 |
| max_wallet_trx_fee | string / null | 准备时允许的钱包能量缺口费用，SUN。 |
| actual_bandwidth_fee | string / null | 已确认回执的带宽费用，SUN；未记录时为null。 |
| fee_warning | string / null | 异常带宽费用说明；不会将实际成功的归集改为失败。 |
actual_fee是链上实际钱包支出；energy_rental.paid_cost和activation_cost是平台CatFee支出，分开核算。
完整字段与状态
查看全部响应字段、嵌套对象及枚举 · 业务状态与处理 · 错误码排查。