Use the Ripple Custody (Wallet) console to freeze incoming deposits by default, freeze and unfreeze individual transactions, and check a wallet's frozen balance. For how freeze controls work and the compliance scenarios they support, see Configure transaction freeze controls. To do the same tasks through the API, see Freeze and unfreeze transactions via the API.
Permissions: In the console, owners, administrators, and auditors can freeze and unfreeze transactions. Owners, administrators, and proposers can turn on freeze by default, which is a wallet setting. See User roles and permissions. Freezing and unfreezing through the API needs an API credential of type TRANSACTIONS. Changing wallet settings through the API needs a WALLETS credential.
Required role: Owner, Administrator, or Proposer.
Automatic freeze places every incoming deposit into a frozen state as soon as it arrives. Use this for compliance-sensitive wallets where you must review each deposit before making it available.
- Open the wallet, select Settings (gear icon), and go to the Transactions tab.
- Toggle Freeze transactions by default to enabled.
- Select Enable to confirm.
After you enable automatic freeze:
- Ripple Custody (Wallet) freezes all new incoming deposits immediately on arrival.
- The setting doesn't affect existing unfrozen funds.
- You must manually unfreeze each deposit after review.
To disable automatic freeze, toggle Freeze transactions by default off, and then select Disable to confirm. New deposits arrive as available funds. Previously frozen deposits remain frozen until you manually unfreeze them.
Required role: Owner, Administrator, or Auditor.
You can freeze any incoming transaction, regardless of whether the wallet uses automatic freeze.
- Open the wallet and go to the Transactions tab.
- Select the transaction you want to freeze, and then select View transaction.
- Open the actions menu (three dots) next to the status and select Freeze transaction.
- Enter a Reason for freezing (required). Ripple Custody (Wallet) records the reason in the audit trail.
- Select Freeze to confirm.
The transaction's funds move from the available balance to the frozen balance until the transaction is unfrozen. The freeze takes effect as soon as Ripple Custody (Wallet) confirms the request. Balances and the console update shortly afterwards.
Required role: Owner, Administrator, or Auditor.
- Open the wallet and go to the frozen transaction's details.
- Select Unfreeze in the Transaction frozen notice, or open the actions menu and select Unfreeze transaction.
- Enter a Reason for unfreezing (required). Ripple Custody (Wallet) records the reason in the audit trail.
- Select Unfreeze to confirm.
The funds move from the frozen balance back to the available balance. The unfreeze takes effect as soon as Ripple Custody (Wallet) confirms the request. Balances and the console update shortly afterwards.
You can unfreeze a transaction whatever caused the freeze, including the wallet's default freeze setting, a Travel Rule check, or a freeze applied by Ripple. A manual freeze or unfreeze stays in place even if an automatic process would later change it. For the full rules, see Freeze types and who can change them.
Each frozen transaction carries a freezeType that records why it was frozen:
| Freeze type | Set by |
|---|---|
FREEZE_TYPE_MANUAL | A user who froze the transaction through the console or API. All new manual freezes use this type. |
FREEZE_TYPE_AUTO_WALLET_SETTING | The wallet's Freeze transactions by default setting. See Enable automatic freeze on a wallet. |
FREEZE_TYPE_TRAVEL_RULE | A Travel Rule check. See Travel Rule transactions. |
FREEZE_TYPE_COMPLIANCE, FREEZE_TYPE_AUTO_RISK, FREEZE_TYPE_AUTO_AMOUNT | Older freeze sources. Ripple Custody (Wallet) keeps these types so that existing records stay readable, and you can still unfreeze them. |
These rules apply to every freeze type:
- You can unfreeze any frozen incoming transaction directly, whatever its freeze type and whoever froze it, including Ripple.
- Manual decisions take precedence over automatic ones. A manual freeze stays in place if an automatic process, such as a Travel Rule check or the wallet's default freeze setting, would later release the transaction. A manual unfreeze stays in place if an automatic process would later freeze it again.
- The latest manual decision wins. Your users and Ripple have equal weight. If Ripple freezes a transaction, you can unfreeze it, and the other way round.
- To keep an automatic hold in place, freeze the transaction manually. The manual freeze then stops a later automatic release.
To freeze or unfreeze a transaction, a user needs permission to update transactions for that wallet. In the console, only owners, administrators, and auditors have it. Other roles don't see the Freeze transaction and Unfreeze transaction actions.
To freeze or unfreeze a transaction through the API, see Freeze and unfreeze transactions via the API.
To check a wallet's frozen balance:
- Open the wallet and go to the Assets tab.
- Review the balance breakdown, which shows the Total, Available, Pending, and Frozen amounts for each asset.
In the transaction list, frozen transactions carry a Frozen label.
- Configure transaction freeze controls — How freeze controls work and compliance use cases
- Freeze and unfreeze transactions via the API — Freeze, unfreeze, and check freeze state programmatically
- View and track transactions — Find a transaction and open its transaction page
- Travel Rule transactions — How a Travel Rule check can freeze a deposit
- Understanding balances — Available, pending, and frozen balances