创建归集任务

为当前账户指定的收款钱包批量创建 USDT 归集任务。每个钱包独立处理，接口返回任务受理结果，链上准备、签名和确认异步完成。

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

请求地址

POST /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>
Content-Type	string	是	请求体必须是单个 UTF-8 JSON 对象；可指定 charset=utf-8。	application/json

请求体

以下业务字段全部放JSON，必须显式提供，不接受额外顶层字段。request_id 只能放在 JSON body 中；Query 中传入任何字段都会被拒绝。不能在本次请求中指定临时归集目标，目标来自当前账户的归集地址设置。不要发送 Idempotency-Key 请求头。

字段	类型	必填	说明	示例值
wallet_ids	string[]	是	1–1000 个正整数钱包 ID；不能重复，必须使用字符串。每个 ID 以有符号 64 位正整数解析。	["123456789012345678"]
sweep_mode	string	是	all：归集准备时的全部已确认可用余额；fixed：每个钱包按 requested_amount 分别归集。	all
requested_amount	string 或 null	是	all 必须显式为 null；fixed 必须为规范正整数最小单位字符串，范围 1–9223372036854775807，不接受前导零、符号、小数或空白。	null 或 "100000000"
request_id	string	是	此业务操作的幂等编号，长度 16–128 个 UTF-8 字节；重试同一请求必须保持不变。	sweep-example-20260908-0001

无路径参数，不接受任何 Query（包括仅有问号的 URL）。所有业务参数必须放 JSON。

全额归集示例

{
  "wallet_ids": [
    "123456789012345678",
    "123456789012345679"
  ],
  "sweep_mode": "all",
  "requested_amount": null,
  "request_id": "sweep-example-20260908-0001"
}

每个钱包归集 100 USDT

{
  "wallet_ids": [
    "123456789012345678",
    "123456789012345679"
  ],
  "sweep_mode": "fixed",
  "requested_amount": "100000000",
  "request_id": "sweep-example-20260908-0002"
}

固定金额应用于每个钱包，不会把它分摊为批次总额。余额不足会在执行检查时明确失败，不会自动减少所请求金额。执行时先检查免费带宽，再依次选择已有能量、钱包自身 TRX、CatFee 租赁。仅当钱包 TRX 能覆盖整个能量准备缺口时才选择燃烧；否则由 CatFee 租足缺口，不混合支付。未激活钱包由 CatFee 同单激活，随后重新检查资源。

成功响应

HTTP 200 表示本批请求已处理，不代表所有钱包成功创建任务，更不代表链上归集已经成功。

字段	类型	必填	说明	示例值
code	integer	是	业务请求成功时固定为 0。	0
message	string	是	成功时固定为空字符串。	""
data	object	是	本批请求的逐钱包受理结果。	见下方 JSON 示例
data.network	string	是	资产所属网络：main（主网）或 nile（测试网络）。	"nile"

字段	类型	必填	说明	示例值
data.items	object[]	是	结果按请求钱包顺序返回。	见下方示例
data.items[].wallet_id	string	是	本项对应的钱包 ID。	123456789012345678
data.items[].id	string	pending 时必有	新建或幂等重放的归集任务 ID；failed 项不返回此字段。	123456789012345680
data.items[].status	string	是	仅有 pending / failed。pending 表示已创建任务，failed 表示该钱包未创建任务。	pending
data.items[].reason	string	failed 时必有	该钱包未创建任务的原因；pending 项不返回此字段。	wallet already has an unfinished task

{
  "code": 0,
  "message": "",
  "data": {
    "network": "nile",
    "items": [
      {
        "wallet_id": "123456789012345678",
        "id": "123456789012345680",
        "status": "pending",
        "network": "nile"
      },
      {
        "wallet_id": "123456789012345679",
        "status": "failed",
        "reason": "wallet already has an unfinished task",
        "network": "nile"
      }
    ]
  }
}

以下逐项失败仍可能出现在 HTTP 200 响应中，即使整批没有任何任务成功创建：

• wallet not found：钱包不存在，或不属于当前账户、当前网络。
• collection destination wallet cannot collect to itself：收款地址就是当前归集目标，不能向自身归集。
• tenant collection address not configured：账户尚未配置归集地址。
• wallet already has an unfinished task：该钱包存在未完成任务。

创建响应不包含完整任务、实际准备金额或实时状态；受理后请使用归集详情查询。

幂等与重试

同一账户、同一操作、同一 request_id 和相同业务参数返回已保存结果，不重复创建任务。改变钱包顺序、钱包集合、归集方式或金额会返回 HTTP 409。原请求处理结果不确定时，使用相同编号和参数重试，不要立即换编号重复创建。

进入业务处理后失败的请求也可能已经绑定该编号与参数。修正业务参数时应使用新的 request_id。幂等重放的是原受理结果，后续状态必须通过详情接口查询；已返回 failed 的逐项结果也会按原结果重放。

典型错误

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

HTTP 400：遗漏 requested_amount

{
  "code": 400,
  "message": "invalid request: requested_amount必须显式提供",
  "error_code": "INVALID_ARGUMENT",
  "trace_id": "0123456789abcdef0123456789abcdef"
}

HTTP 400：钱包 ID 重复或格式无效

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

HTTP 409：相同幂等编号用于不同参数

{
  "code": 409,
  "message": "conflict: idempotency key already used with another request",
  "error_code": "IDEMPOTENCY_CONFLICT",
  "trace_id": "0123456789abcdef0123456789abcdef"
}

查询执行结果与费用

本接口只返回逐钱包的受理结果。实际转账金额、交易哈希、链上手续费和 CatFee 租赁费用请通过归集详情查询，或接收归集结果回调。不要从创建响应中读取这些字段。

批次 data.network 和每项 data.items[].network 均表示资产所属网络，值为 main 或 nile。

完整字段与状态

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