# 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:

- [Blockchains and ledgers](/products/custody/v1.36/accounts-and-assets/blockchains) — 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 issuer operations for creating and managing MPT issuances, and holder operations for receiving and transferring MPTs.

MPT operations are available with API workflows in this release. Before submitting MPT transactions to the ledger, use the [Perform a dry run for an intent](/products/custody/v1.36/reference/api/openapi/intents/intentdryrun) operation to validate MPT-specific requirements such as flag settings, holder authorization status, token balances, and lock status.

| Role | Operation | Description |
|  --- | --- | --- |
| Issuer | [Create issuance](/products/custody/v1.36/accounts-and-assets/tokenization/xrpl-mpts/issuer/create-issuance) | Define a new MPT asset with metadata and flags. |
| Issuer | [Mint tokens](/products/custody/v1.36/accounts-and-assets/tokenization/xrpl-mpts/issuer/mint) | Issue tokens to specific holders. |
| Issuer | [Burn tokens](/products/custody/v1.36/accounts-and-assets/tokenization/xrpl-mpts/issuer/burn) | Reduce supply when tokens are sent to the issuer. |
| Issuer | [Freeze or unfreeze](/products/custody/v1.36/accounts-and-assets/tokenization/xrpl-mpts/issuer/freeze) | Control token transfers at holder or global level. |
| Issuer | [Claw back tokens](/products/custody/v1.36/accounts-and-assets/tokenization/xrpl-mpts/issuer/clawback) | Recover tokens from holders. |
| Issuer | [Authorize holders](/products/custody/v1.36/accounts-and-assets/tokenization/xrpl-mpts/issuer/authorize-holder) | Manage holder authorization for MPTs that require issuer approval. |
| Issuer | [Escrow tokens](/products/custody/v1.36/accounts-and-assets/tokenization/xrpl-mpts/issuer/escrow) | Place tokens in escrow with time-based or conditional release. |
| Issuer | [Destroy issuance](/products/custody/v1.36/accounts-and-assets/tokenization/xrpl-mpts/issuer/destroy-issuance) | Permanently retire the MPT when supply is zero. |
| Holder | [Authorize an MPT](/products/custody/v1.36/accounts-and-assets/tokenization/xrpl-mpts/holder/authorize) | Opt in to hold a specific MPT issuance. Required before receiving any MPT for the first time. |
| Holder | [Receive MPTs](/products/custody/v1.36/accounts-and-assets/tokenization/xrpl-mpts/holder/receive) | Accept incoming MPT payments from issuers or other holders. |
| Holder | [Send MPTs](/products/custody/v1.36/accounts-and-assets/tokenization/xrpl-mpts/holder/send) | Transfer MPTs to other authorized holders, if the token allows transfers. |
| Holder | [Check balances](/products/custody/v1.36/accounts-and-assets/tokenization/xrpl-mpts/holder/balances) | View 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

- [Send assets](/products/custody/v1.36/transactions/send-and-receive/send-assets-api) — Send assets, including supported token transfers, with the API.
- [Receive assets](/products/custody/v1.36/transactions/send-and-receive/receive-assets-api) — Receive and release incoming transfers.
- [Blockchains and ledgers](/products/custody/v1.36/accounts-and-assets/blockchains) — Supported blockchain networks.
- Multi-purpose tokens (XRPL documentation) — Protocol-level reference.