Multi-send: batch payouts to many addresses

From a CSV to a finished run

1. Validate the list before you price it

   Every row is address, asset, network, amount. Run each one through GET /v1/validate-address — a keyless call — and reject the file rather than the payout. known:false means the network has no pattern to check against, which is "unverified", not "valid".

2. Quote every row

   One quote per recipient, by the amount they should receive (amount_to). The sum of the returned FromAmount values is what the run will cost you — approve it before anything is created.

3. Create the orders, a few at a time

   Five to ten concurrent creations is the right pace: providers throttle bursts, and each order must be created and funded inside the offer's five-minute life. Every creation carries an Idempotency-Key built from the run id and the row.

4. Fund each order

   Each one has its own DepositAddress and exact AmountFrom. This is where the network fees live: a hundred recipients is a hundred outgoing transfers from your wallet.

5. Collect the results

   Poll each order to a terminal status and write the run's report: DONE with TxID, or a reason and a row to retry.

The fan-out

import pLimit from "p-limit";
const limit = pLimit(8);                      // providers dislike bursts

const results = await Promise.all(rows.map((row, i) => limit(async () => {
  try {
    const order = await createPayout(runID, row, i);   // quote → POST /orders
    return { row: i, ok: true, id: order.ID, send: order.AmountFrom,
             to: order.DepositAddress };
  } catch (e) {
    return { row: i, ok: false, error: String(e) };    // one row, not the run
  }
})));

const payable = results.filter((r) => r.ok);
const rejected = results.filter((r) => !r.ok);         // show these before funding

The idempotency key is what makes the run restartable. Derive it from the run and the row, never from the clock:

const key = `${runID}:${row.address}:${row.amount}`;  // stable across retries
// POST /v1/partner/orders with header "Idempotency-Key: "
// A repeat returns the same order — a crashed run resumes instead of duplicating.

When a row fails

How this differs from an on-chain multisend

Not included, and worth planning around: there is no single batch endpoint, no one funding transaction, no webhooks, and no fiat leg. A run is a loop your side drives — the API makes each iteration safe.

What people fan out

• Affiliate and referral payouts — hundreds of small amounts, each to whichever asset the partner asked for.
• Creator and bounty programmes, where the payout list changes every cycle and the addresses are user-supplied.
• Airdrops and rewards that must land in the recipient's preferred network rather than yours.
• Refund and compensation runs, reconciled row by row with a TxID against each one.

Questions