Address Types
Choose how wallet addresses behave over time.
Temporary vs Permanent
Side by sideAccount-based addresses that recycle back into the CoinPayments system pool once their job is done — usually when an invoice completes or after an inactivity timeout.
- Auto-recycled. Residual balance at recycling time is automatically credited to your account wallet.
- No activation fee. Cheaper for short-lived attribution — e.g. one address per invoice or per checkout session.
- Pooled routing. CoinPayments can opportunistically reduce network fees via internal accounting before any on-chain move.
- Account-based chains only. UTXO chains cannot use temporary addresses — see the callout below.
Addresses that persist indefinitely and continue to receive funds at the same destination — ideal for per-customer attribution and recurring deposits. Opt in on account-based chains; always on for UTXO chains.
- Stable destination. Hand the same address to a customer or counterparty without worrying about it expiring.
- Funds accumulate at the address. It is recommended to consolidate for centralized holdings.
- One-time activation fee on the first consolidation or spend out of each permanent address. Subsequent operations are cheaper.
- UTXO economics. On UTXO chains, accumulating fund-bearing UTXOs at a single address can materially reduce network fees on bulk withdrawals.
UTXO chains are always permanent
If a currency's capabilities array contains utxo — Bitcoin, Litecoin, Dogecoin, and other UTXO networks — addresses on that chain cannot be temporary. UTXOs are inherently bound to the address that received them, so CoinPayments treats every API-created UTXO address as permanent. The usePermanentAddresses flag on create-wallet only affects account-based chains; on UTXO chains the value is ignored.
Setting the flag
POST /merchant/wallets{
"currency": "4",
"label": "Customer deposit wallet",
"usePermanentAddresses": true
}Sequential processing on permanent-address wallets
Withdrawals from a wallet with permanent addresses must be processed one at a time. Confirm and finalize the current spend request before submitting a new one — submitting multiple before the first is confirmed will fail because of the automatic consolidation step required for each send.
Migrating between modes
You can't flip usePermanentAddresses on an existing wallet. To move funds between modes (or out of a dashboard wallet entirely), use wallet consolidation to sweep balances into a new wallet created with the mode you want.
Where to next?
Pick the most useful next step.