Batch transfer

Process multiple transfers in a single request. Transfers are executed sequentially — use this instead of sending many parallel single-transfer requests.

Each transfer in the array supports the same parameters as the single transfer endpoint.

Best-effort (default): omit atomic or set atomic: false. Results are returned per-transfer; a failure in one item does not stop the others.

Atomic: set atomic: true when every transfer must commit, or none should. SideShift validates the whole batch (accounts, amounts, commercial evidence, and combined source balances) before moving money. If any item would fail, the API returns an error and executes nothing. If an item fails after money has started moving, remaining items are not attempted and already-settled items are reversed. A successful atomic batch returns the same per-item result envelope with failureCount: 0 and atomic: true.

Retry an aborted atomic batch with new per-item idempotencyKey values (and a new batch idempotencyKey if you sent one). Replaying the same keys returns the stored abort and does not pay again.

Why batch? Sending 50+ parallel requests to /accounts/transfer causes Firestore transaction contention on the source wallet, resulting in INTERNAL_ERROR failures. The batch endpoint eliminates this by processing transfers one at a time within a single HTTP call.

Limits: Maximum 200 transfers per batch.

Idempotency and evidence: Every transfer requires its own idempotencyKey. Live batch items also require the same commercial-evidence metadata as the single-transfer endpoint. Atomic batches also reject duplicate per-item keys.