Batches
POST /v1/batches orders for up to 100 receivers at once. For each receiver the platform activates the address if needed, tops up bandwidth if it is short, then delivers the resource, splitting large amounts into chunks.
How a batch behaves
| Property | Behaviour |
|---|---|
| Response | 202 Accepted: queued, nothing charged, nothing delivered yet |
| Result | GET /v1/batches/{id}, or the per-order webhooks (order.confirmed carries batch_id) |
| Billing | Per receiver, at the price in force when that receiver runs; cap it with max_price_sun per item |
| Isolation | One receiver failing never affects the others; a failed activation or bandwidth step does not stop that receiver’s resource order |
| Orders | Each receiver gets its own order id — what you inspect, reclaim and reconcile against |
| Idempotency | client_batch_id: same id + same body returns the original batch; same id + different body is 3010 idempotency_conflict |
| Cancel | POST /v1/batches/{id}/cancel stops the not-yet-started part; receivers already picked up return 3002 order_not_cancellable |
| Rate limit | Order creation (POST /v1/orders, POST /v1/batches) shares 30 rps |
Request
defaults apply to every item; an item overrides any field.
{
"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 }
]
}
Endpoints
| Method | Path | Purpose |
|---|---|---|
POST | /v1/batches | Create a batch |
GET | /v1/batches | List batches |
GET | /v1/batches/{batchId} | Progress and per-receiver orders |
POST | /v1/batches/{batchId}/cancel | Cancel the not-yet-started part |
Field-level schemas: Batches — API reference.