# Token management

Executive summary
**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.


Why this matters
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.

Prerequisites
Before using token management, you should understand:

- [Intents](/products/custody/governance/intents) — Token classification changes follow the standard intent workflow.
- Ripple Custody Auth & Sign mobile app — Required to sign classification intents.


## The problem: unsolicited tokens

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.

## Allowlist-Only visibility model

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.

## Token lifecycle

Tokens follow a defined lifecycle in Ripple Custody:


```mermaid
stateDiagram-v2
    [*] --> Unclassified: Auto-discovered or imported
    Unclassified --> Allowlisted: Allowlist
    Unclassified --> Denylisted: Denylist
    Allowlisted --> Denylisted: Denylist
    Denylisted --> Allowlisted: Restore
```

### How tokens enter the system

- 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.


Token and ticker terminology
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.

### State transitions

| 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` |


## Token management screen

The token management screen provides a centralized view for managing all tokens:

![Token management homepage showing tabs for allowlisted, unclassified, and denylisted tokens](/assets/token_homepage_main.bd22653a1d98fc0c03d64df217060cbe6dd18e1c3992cc148fdc970152fedda9.28bfd75c.png)

- 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.


### Accessing token management

Navigate to **Custody Admin > Token Management** to access the token management screen.

## Security model

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.

## Risk mitigation

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.

![Denylisted tokens view showing warning banner](/assets/token_denied_assets.2465e8a92e0edabb48f57cc5b2c2b7d59af0c47edd982c08ab12cbf21df56818.28bfd75c.png)

## Supported token standards

You can manage tokens that follow these standards:

- ERC-20 (fungible tokens).
- ERC-721 (NFTs).
- ERC-1155 (multi-token).


ERC-20 metadata requirement
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](/products/custody/reference/supported-ledgers#erc-20-metadata-requirement).

Native blockchain currencies (such as ETH or XRP) are always visible and cannot be denylisted.

## Related topics

- [Manage tokens in the UI](/products/custody/accounts-and-assets/tokenization/token-management/ui)
- [Manage tokens with the API](/products/custody/accounts-and-assets/tokenization/token-management/api)
- [Ledger-specific token operations](/products/custody/accounts-and-assets/tokenization/ledger-specific)
- [XRPL Multi-Purpose Tokens](/products/custody/accounts-and-assets/tokenization/xrpl-mpts)
- [Accounts](/products/custody/accounts-and-assets/accounts/overview)
- [Intents](/products/custody/governance/intents)