Sweeps

When every customer has their own vault, money arrives spread across many of them. A sweep gathers it: a rule that, on one network and for one asset, regularly moves what has arrived in a set of vaults into one vault of yours, such as your treasury.

A sweep rule

A sweep rule names:

• the network and the asset, such as USDC on Base;
• the destination, one of your vaults;
• the sources: every vault opened with a reference, which includes customer vaults opened later, or a list of vaults you name. The destination is never a source;
• a minimum: a vault holding less is left alone;
• a fee ceiling: a sweep whose network fee would cost more is skipped and tried again later.

A network and asset have at most one sweep rule. Sweeps run every 15 minutes and move only free money: never what a payment has reserved or what is held for review. Their fees come from your gas pool, like any payment’s. They are not subject to your payment rules’ limits, because the money never leaves your organisation, but a paused network stops them too.

Two people agree

A sweep rule moves money, so it takes two people. Your software can propose one, a change to one, or stopping one, and someone who manages sweeps confirms it in the console. An API key can never confirm a sweep, and neither can anyone who created or gave a new secret to the key that proposed it. One proposal can wait for a network and asset at a time; a key can withdraw its own.

GET /v1/sweeps/fee prices one sweep now, to help choose a fee ceiling. GET /v1/sweeps lists the rules, their proposals and how each last ran: swept, nothing to move, skipped because the fee was above the ceiling or the gas pool could not pay, or failed. If a rule is skipped for a whole day, the people who manage sweeps are emailed.

Sweeps in your records

A sweep moves your own money, so do not treat it as a customer paying or being paid:

• the payment it makes has purpose sweep;
• the deposit it makes in the destination has sweep true.

Both appear in webhooks, balances and statements like any other movement.