Freeze and unfreeze MPT tokens

Control token transfers by freezing individual holders or the entire MPT issuance.

How freezing works

Issuers can freeze tokens at two levels:

Individual freeze — Freeze a specific holder's balance.
Global freeze — Freeze all holders of the MPT.

When tokens are frozen, the holder cannot send or receive tokens until unfrozen.

Freezing requires lsfMPTCanLock to be set during issuance. If this flag is not set, the issuer cannot freeze tokens.

Prerequisites

You are the issuer of the MPT
The MPT has lsfMPTCanLock enabled

Freeze a specific holder

To freeze a specific holder's tokens, use MPTokenIssuanceSet with the tfMPTLock flag:

{
  "payload": {
    "id": "{{intent_id}}",
    "accountId": "{{issuer_account_id}}",
    "parameters": {
      "type": "XRPL",
      "feeStrategy": {
        "priority": "Medium",
        "type": "Priority"
      },
      "operation": {
        "type": "MPTokenIssuanceSet",
        "tokenIdentifier": {
          "issuanceId": "000004C463C52827307480341125DA0577AFFC21D4B2D0831E",
          "type": "MPTokenIssuanceId"
        },
        "holder": {
          "address": "rHolderAddress...",
          "type": "Address"
        },
        "flags": ["tfMPTLock"]
      }
    },
    "customProperties": {},
    "type": "v0_CreateTransactionOrder"
  }
}

Unfreeze a specific holder

To unfreeze a holder, use the tfMPTUnlock flag:

{
  "payload": {
    "id": "{{intent_id}}",
    "accountId": "{{issuer_account_id}}",
    "parameters": {
      "type": "XRPL",
      "feeStrategy": {
        "priority": "Medium",
        "type": "Priority"
      },
      "operation": {
        "type": "MPTokenIssuanceSet",
        "tokenIdentifier": {
          "issuanceId": "000004C463C52827307480341125DA0577AFFC21D4B2D0831E",
          "type": "MPTokenIssuanceId"
        },
        "holder": {
          "address": "rHolderAddress...",
          "type": "Address"
        },
        "flags": ["tfMPTUnlock"]
      }
    },
    "customProperties": {},
    "type": "v0_CreateTransactionOrder"
  }
}

Global freeze

To freeze all holders, omit the holder field:

{
  "operation": {
    "type": "MPTokenIssuanceSet",
    "tokenIdentifier": {
      "issuanceId": "000004C463C52827307480341125DA0577AFFC21D4B2D0831E",
      "type": "MPTokenIssuanceId"
    },
    "flags": ["tfMPTLock"]
  }
}

Parameters

Field	Type	Required	Description
`tokenIdentifier.issuanceId`	string	Yes	The 192-bit MPT issuance ID.
`tokenIdentifier.type`	string	Yes	Must be `MPTokenIssuanceId`.
`holder`	object	No	The holder to freeze. Omit for global freeze.
`holder.type`	string	Conditional	One of: `Account` (internal account UUID), `Address` (XRPL address), or `Endpoint` (endpoint UUID). Required when `holder` is provided.
`holder.address`	string	Conditional	The holder's XRPL address. Required when `holder.type` is `Address`.
`holder.accountId`	string	Conditional	Internal account UUID. Required when `holder.type` is `Account`.
`holder.endpointId`	string	Conditional	Endpoint UUID. Required when `holder.type` is `Endpoint`.
`flags`	array	Yes	`["tfMPTLock"]` to freeze, `["tfMPTUnlock"]` to unfreeze.

Response

A successful request returns the transaction order with status Pending. After confirmation, the holder's (or all holders') transfer capabilities are updated.

Multi-purpose tokens — Overview of MPT operations.
Token flags — Flag descriptions.
Clawback — Recover tokens from frozen holders.
MPTokenIssuanceSet — XRPL transaction reference.