Skip to main content
If your users receive money on several networks, their balance ends up spread across all of them. Settlement gathers it in one place. Pick one network, and every new deposit to any of your users’ addresses is converted to USDC if needed and moved to that same user’s address on the network you picked. It’s off until you turn it on. Set it with GET/PUT /api/v1/settlement.
This isn’t the same as auto-sweep. Settlement moves a deposit to the user’s own address on your chosen network, so their balance is all in one place. Auto-sweep moves money into your master wallet. They work together: auto-sweep still runs on the settlement network once a deposit arrives there.

​
What happens to a deposit

Say you’ve picked Polygon as your settlement network, and a user deposits USDT on Ethereum. Their address on Polygon ends up holding that amount in USDC. There’s no extra step for you or for them. If a deposit already arrives as USDC on your settlement network, there’s nothing to do, and it isn’t counted as a settlement. Very small deposits are left where they arrived, because converting and moving a few cents can cost more than the deposit is worth. You’ll see this as skipped_below_minimum on the deposit’s settlement field.

​
Keeping track

Every deposit that needed moving has a settlement object when you fetch it. See get a wallet’s deposits. You can also wait for the wallet.deposit.settled webhook instead of checking. status is one of:

​
If a settlement fails

We tell you where the money is, in one of three ways:
  • On the network where the deposit arrived. Safe at your user’s own address, in the coin they sent.
  • On Base. Safe at your user’s own address, as USDC.
  • Under review. We’re still confirming where it is and looking into it. That doesn’t mean it’s unsafe, only that we won’t name a place until we’re sure.
Whichever it is, the money still belongs to your user. A failed settlement means the automatic move didn’t finish, not that money is missing.

​
Cashing out to M-Pesa or a bank

Settle to Base, and you can pay a settled balance straight out to local currency. Create an off-ramp order with funding_wallet_ref set to the user’s address, and we pay the recipient from that balance. Wait for wallet.deposit.settled before you create the order, so the USDC is on Base when we need it.

​
Changing your settlement network

Changing or clearing the network only affects new deposits. A settlement that’s already on its way keeps going to the network it started with, and is never redirected partway.