# Multi-purpose tokens

Executive summary
**Multi-purpose tokens (MPTs) represent the next generation of fungible tokens on the XRP Ledger, designed for institutional use cases.**

- Authorize, receive, send, and track MPT balances in Ripple Custody.
- Automatic ticker creation when MPT payments are received.
- On-chain metadata with standardized schema for token properties.


Why this matters
Traditional tokenization on the XRP Ledger uses trust lines, which were designed for a different era. MPTs address these limitations with a cleaner architecture built for institutional adoption.

**Benefits:** Unidirectional transfers eliminate rippling complexity. Token properties are stored on-chain, not in external systems. Holders must opt in before receiving any MPT, preventing spam.

**Use cases:** Tokenized securities and RWAs, stablecoins, loyalty programs, and gaming currencies.

Prerequisites
Before working with MPTs, you should understand:

- [Blockchain](/products/custody/v1.34/concepts/blockchain) — XRP Ledger accounts, transactions, and ledger concepts.
- Ripple Custody Auth & Sign mobile app — Required to sign MPT transaction intents.


## Tokenization on the XRP Ledger

Tokenization is the process of representing real-world or digital assets as blockchain tokens. On the XRP Ledger, tokenization enables:

- Divide high-value assets into smaller, tradeable units.
- Transfer ownership instantly, without intermediaries.
- Enforce transfer restrictions and regulatory requirements at the protocol level.
- Enable cross-border transactions with reduced friction.


The XRP Ledger supports two types of fungible tokens: trust line tokens and multi-purpose tokens. While trust line tokens have served the ecosystem well, MPTs address their limitations with a cleaner architecture designed for institutional adoption.

## How MPTs differ from trust line tokens

MPTs were designed based on lessons learned from trust line tokens. The following table summarizes the key differences:

| Feature | Trust line tokens | Multi-purpose tokens |
|  --- | --- | --- |
| Identifier | Currency code (3-char or 40-char hex) | 192-bit Issuance ID |
| Direction | Bidirectional (supports rippling) | Unidirectional only |
| Metadata | None (off-chain only) | Up to 1024 bytes on-chain |
| Settings scope | Per-account (affects all tokens) | Per-issuance (granular control) |
| Supply cap | Not enforceable | Configurable maximum quantity |
| Transfer fees | Percentage-based | Percentage-based |
| Compliance | Freeze and clawback available | Freeze, clawback, and authorization |


MPTs intentionally omit features like rippling that introduce edge cases, resulting in a simpler conceptual model that is easier to reason about and integrate.

## Core properties

The following properties are inherent to all MPTs on the XRP Ledger:

- **Anyone can be an issuer.** Every account can issue tokens, and you can create many different issuances from a single account. Each issuance can have different settings.
- **Issuers cannot hold their own tokens.** Tokens sent to the issuer are automatically burned. Use separate operational accounts if you need to hold your own tokens.
- **Holders must opt in.** Recipients must authorize an MPT before they can receive it, preventing unwanted token spam.


## Issuer and holder roles

MPT operations are divided between two distinct roles:

| Role | Description | Available operations |
|  --- | --- | --- |
| **Issuer** | Creates and controls the MPT issuance | Create, mint, burn, freeze, clawback, authorize holders, destroy |
| **Holder** | Receives and transfers MPTs | Authorize (opt-in), receive, send, check balances |


An account can act as both an issuer (for MPTs it creates) and a holder (for MPTs created by others).

## Supported operations

Ripple Custody supports the following MPT holder operations:

| Operation | Description |
|  --- | --- |
| Authorize | Opt-in to hold a specific MPT issuance. Required before receiving any MPT for the first time. |
| Receive | Accept incoming MPT payments from issuers or other holders. |
| Send | Transfer MPTs to other authorized holders (if the token allows transfers). |
| Check balances | View your MPT holdings with correct decimal precision based on AssetScale. |


## Token lifecycle

MPTs follow a defined lifecycle from creation to destruction:


```mermaid
stateDiagram-v2
    [*] --> Created: MPTokenIssuanceCreate
    Created --> Active: Holders authorize
    Active --> Active: Mint/Transfer/Burn
    Active --> Frozen: Issuer freezes
    Frozen --> Active: Issuer unfreezes
    Active --> Destroyed: MPTokenIssuanceDestroy
    Destroyed --> [*]
```

1. **Create** — The issuer creates the MPT issuance with `MPTokenIssuanceCreate`, defining metadata and flags.
2. **Authorize** — Holders opt in to receive the MPT with `MPTokenAuthorize`.
3. **Mint** — The issuer sends tokens to holders using `Payment` transactions.
4. **Transfer** — Holders transfer tokens among themselves (if `lsfMPTCanTransfer` is enabled).
5. **Burn** — Tokens returned to the issuer are automatically burned.
6. **Destroy** — The issuer can destroy the issuance with `MPTokenIssuanceDestroy` when supply reaches zero.


## MPT Issuance ID

Each MPT issuance is uniquely identified by a 192-bit identifier (displayed as 48+ hexadecimal characters):


```
00070C4495F14B0E44F78A264E41713C64B5F89242540EE255534400000000000000
```

The Issuance ID is generated by the XRP Ledger when the issuer creates the MPT. Unlike currency codes, Issuance IDs are not intended for display to end users—use the token's metadata for human-readable identifiers.

## On-chain metadata

Every MPT issuance includes on-chain metadata stored in the `MPTokenIssuance` ledger entry. This metadata contains both functional and non-functional data:

**Functional data:**

- Transfer fee percentage.
- Maximum supply cap.
- Transferability settings.


**Non-functional data:**

- Asset scale (decimal precision).
- Up to 1024 bytes of arbitrary metadata (typically JSON).


### Metadata schema

MPT metadata follows the XLS-89 standard. To fit within the 1024-byte limit, the schema uses compressed JSON keys:

| Field | Key | Required | Description |
|  --- | --- | --- | --- |
| ticker | `t` | Yes | Token symbol (uppercase letters and digits, max 6 characters recommended) |
| name | `n` | Yes | Display name of the token |
| desc | `d` | No | Short description |
| icon | `i` | Yes | URI to the token icon |
| asset_class | `ac` | Yes | Primary category: `rwa`, `memes`, `wrapped`, `gaming`, `defi`, or `other` |
| asset_subclass | `as` | Conditional | Required when `asset_class` is `rwa` |
| issuer_name | `in` | Yes | Name of the issuing entity |
| uris | `us` | No | Array of related URIs (website, docs, social) |
| additional_info | `ai` | No | Freeform field for additional details |


### Asset classes

The `asset_class` field categorizes tokens by their primary purpose:

| Class | Description |
|  --- | --- |
| `rwa` | Real-world assets with legally enforceable claims on physical or financial assets |
| `memes` | Community-driven tokens without intrinsic backing |
| `wrapped` | Tokens representing assets from other blockchains |
| `gaming` | In-game currencies, assets, or rewards |
| `defi` | Governance tokens, DEX tokens, and lending assets |
| `other` | Experimental or unique use cases |


When `asset_class` is `rwa`, specify an `asset_subclass`: `stablecoin`, `commodity`, `real_estate`, `private_credit`, `equity`, `treasury`, or `other`.

### Example metadata


```json
{
  "t": "TBILL",
  "n": "T-Bill Yield Token",
  "d": "A yield-bearing stablecoin backed by short-term U.S. Treasuries.",
  "i": "example.org/tbill-icon.png",
  "ac": "rwa",
  "as": "treasury",
  "in": "Example Yield Co.",
  "us": [
    {"u": "exampleyield.co/tbill", "c": "website", "t": "Product Page"},
    {"u": "exampleyield.co/docs", "c": "docs", "t": "Documentation"}
  ],
  "ai": {
    "interest_rate": "5.00%",
    "maturity_date": "2045-06-30",
    "cusip": "912796RX0"
  }
}
```

## Asset scale (decimals)

MPT balances are stored as raw integers. The `AssetScale` field (0–19) defines how to interpret the decimal position:

| AssetScale | Raw value | Display value |
|  --- | --- | --- |
| 0 | 1000 | 1000 |
| 2 | 150000 | 1500.00 |
| 6 | 1500000 | 1.500000 |


Ripple Custody automatically applies the MPT's `AssetScale` to display balances with correct decimal precision.

## Transferability controls

MPTs support three levels of transferability:

| Level | Configuration | Behavior |
|  --- | --- | --- |
| **Freely transferable** | `lsfMPTCanTransfer` enabled, `lsfMPTRequireAuth` disabled | Any holder can transfer to any other account |
| **Authorized holders only** | `lsfMPTCanTransfer` enabled, `lsfMPTRequireAuth` enabled | Only issuer-approved accounts can hold or receive |
| **Non-transferable** | `lsfMPTCanTransfer` disabled | Tokens can only move between holders and the issuer |


## Compliance controls

MPTs include built-in compliance capabilities:

### Freeze

When `lsfMPTCanLock` is enabled during issuance, the issuer can freeze tokens:

- **Individual freeze** — Block a specific holder from sending or receiving.
- **Global freeze** — Block all transfers of the token (except to/from the issuer).


### Clawback

When `lsfMPTCanClawback` is enabled, the issuer can reclaim tokens from any holder without consent. This is useful for:

- Recovering tokens sent to incorrect addresses.
- Enforcing legal or regulatory requirements.
- Responding to security incidents.


Before accepting an MPT as collateral or for custody, verify the token's flags. Tokens with `lsfMPTCanClawback` enabled may be reclaimed by the issuer at any time.



## Token flags reference

MPT behavior is controlled by flags set during issuance. Most flags are **immutable** after creation.

### Immutable flags

| Flag | Description |
|  --- | --- |
| `lsfMPTCanLock` | Issuer can freeze individual holders or the entire token. |
| `lsfMPTRequireAuth` | Holders must be authorized by the issuer before receiving. |
| `lsfMPTCanTransfer` | Holders can transfer tokens to each other. |
| `lsfMPTCanClawback` | Issuer can reclaim tokens without holder consent. |
| `lsfMPTCanEscrow` | Tokens can be placed in escrow. |
| `lsfMPTCanTrade` | Tokens can be traded on the DEX. |


### Mutable flags

| Flag | Description |
|  --- | --- |
| `lsfMPTLocked` | When set, all transfers are blocked (global freeze). |


## Related topics

- [Multi-purpose tokens (API)](/products/custody/v1.34/api/accounting/multi-purpose-tokens) — Procedures for working with MPTs in Ripple Custody.
- [Blockchain](/products/custody/v1.34/concepts/blockchain) — Supported blockchain networks.
- Multi-purpose tokens (XRPL documentation) — Protocol-level reference.