归集详情

查询一个 USDT 归集任务的原始请求金额、准备金额、链上状态、交易哈希和关联回调状态。

本页的 ID、地址、交易哈希、时间及金额均为文档示例；请使用自己账户的数据。金额以六位精度的最小单位字符串表示，例如 "100000000" 代表 100 USDT，"1000000" SUN 代表 1 TRX。

请求地址

http

GET /open/v1/sweeps/{id}

鉴权请求头

先获取 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>`

路径参数

字段	类型	必填	说明	示例值
id	string	是	归集任务 ID，以正整数解析，范围 1–9223372036854775807；请使用创建或列表接口返回的原始 ID。	`123456789012345680`

http

GET /open/v1/sweeps/123456789012345680

不接受 network 查询参数；GET 请求体必须为空。记录必须属于当前账户及当前网络，且类型为 sweep。不存在、其他账户或其他网络的记录统一返回 404。路径中的 ID 决定查询对象，query 中的 id 不会覆盖它。

成功响应

HTTP 200。

字段	类型	必填	说明	示例值
code	integer	是	业务请求成功时固定为 0。	`0`
message	string	是	成功时固定为空字符串。	`""`
data	object	是	完整归集任务对象。	见下方 JSON 示例
data.network	string	是	资产所属网络：main（主网）或 nile（测试网络）。	"nile"

`data` 的完整字段

字段	类型	必填	说明	示例值
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",
    "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
  }
}

requested_amount 是原始每钱包金额，amount 是准备时确定的金额；all 模式的 requested_amount 始终为 null。没有生成交易时 txid=""；没有关联通知事件时 webhook=null。这些空值不是字段缺失。

若任务为 unknown，继续查询或等待确认，不要据此认定交易失败并重新提交。succeeded 与 webhook.status="failed" 可以同时出现：归集已经成功，但回调未送达。

详情读取当前保存状态，不使用创建接口的幂等响应缓存，不需要 request_id；不要发送 Idempotency-Key 请求头。

典型错误

错误响应不包含 data。鉴权、租户状态、限流、超时等通用处理见通用错误说明。

HTTP 400：路径 ID 不是有效正整数

json

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

HTTP 404：当前账户和网络下没有该归集任务

json

{
  "code": 404,
  "message": "not found",
  "error_code": "RESOURCE_NOT_FOUND",
  "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支出，分开核算。

完整字段与状态

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

归集详情 ​

请求地址 ​

鉴权请求头 ​

路径参数 ​

成功响应 ​

data 的完整字段 ​

任务状态 ​

典型错误 ​

HTTP 400：路径 ID 不是有效正整数 ​

HTTP 404：当前账户和网络下没有该归集任务 ​

HTTP 401：token 缺失、无效或已过期 ​

租赁执行阶段 ​

费用来源及实际扣费 ​

完整字段与状态 ​

归集详情

请求地址

鉴权请求头

路径参数

成功响应

`data` 的完整字段

任务状态

典型错误

HTTP 400：路径 ID 不是有效正整数

HTTP 404：当前账户和网络下没有该归集任务

HTTP 401：token 缺失、无效或已过期

租赁执行阶段

费用来源及实际扣费

完整字段与状态