批量处理 — API 参考

单个请求，批量交付多个接收地址。

基于 openapi.yaml 在构建时生成。基准 URL 为 https://api.tenergy.me/v1，Nile 测试网环境为 https://api-nile.tenergy.me/v1（详见环境说明）。下述每个请求均遵循身份鉴权规范进行签名，除非鉴权行另有说明。

列出批次任务

GET /v1/batches · listBatches

鉴权： API 密钥 (HMAC)。

请求参数

响应

响应字段

单次调用为多个接收方批量下单

POST /v1/batches · createBatch

鉴权： API 密钥 (HMAC)。

单个请求支持最多 100 个接收地址。对于每个地址，平台会自动串联完整交付流程 —— 若地址未激活则自动激活，若带宽不足则补充带宽，随后执行资源交付（大额自动分笔切片）。

接口返回 202 Accepted：批次已入队排队，此时尚未扣款且未完成质押交付。可通过 GET /v1/batches/{id} 或各订单的 Webhook 回调获取执行结果。

单个接收方失败不会影响其他接收方，激活或带宽补充步骤失败也不会阻断能量订单的主交付。

每个接收方按其实际执行时刻的实时价格进行计费结算。可通过设置每项的 max_price_sun 控制单价上限。

每个接收方会生成对应的独立订单 ID。client_batch_id 作为整批任务的幂等键：相同 ID 和请求体将返回原始批次；相同 ID 但不同请求体将拒绝并返回 3010 idempotency_conflict。

请求参数

请求体

JSON (BatchRequest)，必填。

来自规范的请求体示例（示意数值）：

{
  "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}
  ]
}

响应

响应字段 (Batch)

查询批次执行进度

GET /v1/batches/{batchId} · getBatch

鉴权： API 密钥 (HMAC)。

请求参数

响应

响应字段 (Batch)

字段结构与 POST /v1/batches 响应中的字段相同。

取消批次中尚未开始的项

POST /v1/batches/{batchId}/cancel · cancelBatch

鉴权： API 密钥 (HMAC)。

从排队队列中移除所有尚未开始处理的接收项。不会中断已经在处理中的项。

请求参数

响应

响应字段