Batches of up to 5,000

SET Direct Deposit API · Live since 2026-11-10

The problem

POST /api/partner/payees/batch resolves up to 20 emails in one call. A contest with 3,000 winners, or a monthly payout run, needs one multisend list for all of them, not 150 separate batches.

The answer: add pages to one batch

Create the batch with its first 20 emails: POST /api/partner/payees/batch {chain, items}.
Add the rest, 20 a call: POST /api/partner/payees/batch/{id}/items {items}. New items are numbered after the batch's own and use the batch's chain.
A batch holds up to 5,000 items.
Each answer is the whole batch. payTo lists every payable item so far that has an amount: direct and claimable items, never those below_minimum, invited or setup_required.

Exporting for signing

Call	Gives
`GET /api/partner/payees/batch/{id}?format=csv`	The multisend list as CSV: `address`, `amount_usdc`, `reference`, `destination`
`GET /api/partner/payees/batch/{id}?format=safe`	A Safe Transaction Builder file with one USDC `transfer` per payable item. Import it in the Safe app and sign once

CSV cells that start with =, +, - or @ are written as text.

Edge cases

Answer	Means	Do
`409 batch_busy`	Another page was being added to this batch at the same moment. Nothing from your call was added	Send the same page again
`409 batch_full`	The batch already holds 5,000 items, or this page would take it over	Start a new batch
`400 reference_repeated`	A reference is already used in this batch	Make each reference unique within the batch
`400 batch_too_large`	More than 20 items in one call	Split the page

Add pages one after another, not in parallel. Parallel pages are safe, since none is lost or numbered twice, but all but one will be batch_busy.

Why 20 a call

Each email is resolved while you wait, and SET stores no email (Payable Email's privacy rule), so it cannot keep a list to resolve later. Twenty a call is what one request can resolve within SET's hosting limits.