批量处理

批量处理

POST /v1/batches 支持在一次 API 调用中为多达 100 个接收地址批量下单。平台会对每个接收地址按需自动激活、补足带宽，并将大额能量分块委托上链。

批量任务执行机制

特性	行为规范
接口响应	`202 Accepted`：任务已进入排队，尚未扣款，尚未开始委托
结果追踪	调用 `GET /v1/batches/{id}` 查询，或通过 Webhooks 回调（`order.confirmed` 事件携带 `batch_id`）
扣费结算	按各个地址实际执行时的生效价格逐笔扣款；可通过每项的 `max_price_sun` 设定价格上限
故障隔离	单个地址失败绝不影响其他地址；单个地址的激活或带宽补充失败不影响该地址的能量委托
订单归属	每个接收地址生成独立的订单 ID —— 便于后续单独查询、提前赎回与对账
幂等控制	`client_batch_id`：相同 ID + 相同内容返回原始批次任务；相同 ID + 不同内容返回 `3010 idempotency_conflict`
任务取消	`POST /v1/batches/{id}/cancel` 可取消尚未开始的子项；已开始执行的子项将返回 `3002 order_not_cancellable`
请求频控	订单创建接口（`POST /v1/orders` 与 `POST /v1/batches`）共享 30 rps 预算

请求格式示例

defaults 中的配置会应用到所有子项；每个子项可单独覆盖任意字段。

{
  "client_batch_id": "acme-payout-2026-09-11-01",
  "defaults": { "resource": "energy", "tier": "1h", "amount": 65000, "activate": true, "bandwidth": true, "bandwidth_amount": 400 },
  "items": [
    { "receiver": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE" },
    { "receiver": "TXXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "amount": 131000 },
    { "receiver": "TYYyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy", "bandwidth": false }
  ]
}

方法	路径	功能说明
`POST`	`/v1/batches`	创建批量任务
`GET`	`/v1/batches`	查询批量任务列表
`GET`	`/v1/batches/{batchId}`	查询批次执行进度及各地址订单详情
`POST`	`/v1/batches/{batchId}/cancel`	取消尚未开始的待处理项

批量任务执行机制

请求格式示例

相关接口