Token management in Ripple Custody controls which tokens are visible and usable in the platform.
- The Allowlist-Only visibility model ensures operators only see explicitly approved tokens.
- Classify tokens as allowlisted, unclassified, or denylisted.
- Bulk operations enable efficient token classification at scale.
- Intent-based security protects all classification changes.
Custody operators face a growing challenge: anyone can send tokens to a blockchain address without permission. This creates security and operational risks that token management directly addresses.
Without token management: Operators waste time reviewing unsolicited tokens, scam tokens can mislead staff, and cluttered interfaces increase operational errors.
With token management: Only approved tokens appear in balances and transactions, new tokens are quarantined until reviewed, and denylisted tokens are permanently hidden.
Before using token management, you should understand:
- Intents — Token classification changes follow the standard intent workflow.
- Ripple Custody Auth & Sign mobile app — Required to sign classification intents.
Blockchain addresses can receive tokens from anyone without approval. This creates operational challenges:
- Spam tokens clutter the interface and waste operator time.
- Scam tokens can mislead operators into risky transactions.
- Auto-discovered tokens from incoming transactions may be unknown or unwanted.
Token management solves these problems by hiding unverified tokens from standard views until an operator explicitly approves them.
With Allowlist-Only mode:
- Only allowlisted token balances appear in account views.
- Transfers involving unclassified or denylisted tokens are filtered at the transfer level.
- You can only create transfer orders for allowlisted tokens.
This filtering happens at the individual transfer level, not the transaction level. A transaction containing both allowlisted and non-allowlisted tokens shows only the allowlisted portions.
Tokens follow a defined lifecycle in Ripple Custody:
- When an incoming transaction contains a new token, Ripple Custody registers it automatically as unclassified.
- Operators can add tokens manually, which land in the allowlisted state.
The documentation uses token for the user-facing asset, currency, or contract asset that operators manage. API payloads and some intent types use ticker for the internal token record, such as tickerId, v0_ValidateTickers, v0_LockTicker, and v0_UnlockTicker. When an intent asks for a ticker, use the token's ticker ID from the token/ticker API response.
| From | To | Action | API intent |
|---|---|---|---|
| Unclassified | Allowlisted | Allowlist | v0_ValidateTickers |
| Unclassified | Denylisted | Denylist | v0_ValidateTickers with lock: Locked |
| Allowlisted | Denylisted | Denylist | v0_LockTicker |
| Denylisted | Allowlisted | Restore | v0_UnlockTicker |
The token management screen provides a centralized view for managing all tokens:
- Separate tabs for allowlisted, unclassified, and denylisted tokens.
- Each tab shows the number of tokens in that state.
- Allowlist or denylist multiple tokens at once.
- Find tokens by name, symbol, or ledger.
Navigate to Custody Admin > Token Management to access the token management screen.
Token management uses the standard Ripple Custody intent-based security model:
- Every classification change creates an intent that must be signed.
- Operators sign intents using the Ripple Custody Auth & Sign mobile app.
- Before signing, operators can review the full JSON payload including asset IDs, contract addresses, and the specific action.
- Organizations can require multiple approvals before changes take effect.
- All classification changes are logged with intent IDs and timestamps.
When you submit a token classification change, a "Check your device" prompt appears. Use the Ripple Custody Auth & Sign mobile app to review and sign the intent.
The Allowlist-Only model helps protect against:
- Unsolicited tokens from marketing campaigns are hidden by default.
- Tokens designed to impersonate legitimate assets are not visible.
- Tokens with harmful smart contract logic remain hidden until reviewed.
The denylisted tab includes a warning banner identifying tokens as potentially malicious, phishing attempts, or security risks.
You can manage tokens that follow these standards:
- ERC-20 (fungible tokens).
- ERC-721 (NFTs).
- ERC-1155 (multi-token).
ERC-20 tokens must implement the IERC20Metadata interface — the contract must expose name(), symbol(), and decimals(). Contracts that omit any of these methods are not supported and will be silently ignored by the system. For details, see ERC-20 metadata requirement.
Native blockchain currencies (such as ETH or XRP) are always visible and cannot be denylisted.