Skip to content
>
Mode: standard
Dashboard

Wallet Consolidation

Permanent address utility

Move funds out of permanent addresses, three ways.

Withdrawals from permanent addresses (and every UTXO address) need a consolidation step that sweeps individual address balances into the wallet balance before they can be spent. CoinPayments offers three approaches — pick the one that fits your control and automation needs.
Configure auto-sweep (recommended)Preview consolidation fees

Three approaches

Dashboard · API · API
Approach 1Recommended · Dashboard
Auto-sweep on threshold
Configure a trigger amount per wallet from the dashboard. Once the balance crosses the threshold, CoinPayments sweeps funds to a destination address you specify. Works for any wallet type — and it's the recommended setup for most integrations because you don't have to write or maintain code.
  • WhereDashboard → Wallets → expand the target currency.
  • TriggerA balance threshold you set per wallet.
  • DestinationAn address you specify — typically a cold or treasury wallet.
  • Best forTreasury automation — sweeping accumulated funds without writing code.
Configure auto-sweep in the dashboardOpen
Approach 2Automatic · On Spend
Auto-consolidation on spend
Submit a spend request and let CoinPayments pick the right combination of permanent addresses to consolidate behind the scenes. The withdrawal and the consolidation happen as one atomic flow — you only specify the source wallet and the amount.
  • EndpointPOST /merchant/wallets/:id/spend-request
  • ControlCoinPayments picks the address combination that minimises fees and activation costs.
  • Best forYou want the funds out; you don't care which permanent addresses get touched.
Open the spend-request route referenceOpen
Approach 3Granular · Manual
Pick the addresses yourself
Call dedicated consolidation endpoints to specify exactly which addresses (and which source wallets) to sweep. More setup and more control — useful when specific permanent addresses must remain untouched.
Open the manual consolidation referenceOpen

Convert as you consolidate

Consolidation can double as a currency conversion — the swept funds can land in a different asset as part of the same atomic operation. Handy when you want incoming coin to settle directly as a stablecoin, with no separate spend request to swap afterwards.

Fees

Per address, per consolidation
Activation Fee

Charged once per permanent address, the first time it's consolidated. Initialises the address so subsequent operations are cheaper.

Transfer Fee

Charged per address on every consolidation transaction — the on-chain cost of moving the funds.

Quote fees ahead of time with the Consolidation Preview endpoint — it returns the exact fee breakdown for the set of addresses you're about to sweep.

Consolidation must target a temporary-address wallet

When you trigger a consolidation, the :to destination wallet must be one configured with temporary addresses. Consolidating into another permanent-address wallet is not supported — the sweep needs a wallet-level balance to land in.

Sequential processing

Spend requests against a permanent-address wallet must be processed one at a time. Confirm and finalize the current request before submitting a new one — the automatic consolidation step required for each send will reject concurrent attempts.

Where to next?

Pick the most useful next step.

Spend Request
Withdraw funds — auto-consolidation runs behind the scenes.
Address Types
How temporary and permanent addresses behave over time.