> ## Documentation Index
> Fetch the complete documentation index at: https://docs.digitalasset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Force Transfer

> Learn how to create instruments with force transfer enabled and force transfer holdings through the Registry UI and the DA Registry API.

> [!NOTE]
>
> This feature has been introduced with version `0.15` of the Registry App.

For an overview of force transfer, see [Force Transfer](https://docs.digitalasset.com/registry/features/force-transfer.md).

## For Registrars

### Create an Instrument with Force Transfer Enabled

> [!WARNING]
>
> Decide before you create the instrument. You cannot enable or disable force transfer later.

1. In the Registry UI, click **Instrument** > **Management** in the left sidebar.
2. Click **+ New Instrument**.
3. Fill in the instrument details, and check **Enable Force Transfer**.
4. Click **Create**.

The **Enable Force Transfer** checkbox is shown once the operator's and registrar's participants have vetted `utility-registry-v0` version `0.9.0` or later. To check whether force transfer is enabled for an instrument, click its row on the **Instrument Management** page: the details show **Force Transfer** as **Enabled** or **Disabled**.

> [!NOTE]
>
> Informing holders that an instrument has force transfer enabled is the registrar's responsibility.

Archiving an existing instrument configuration and re-creating it with forced transfer enabled makes all existing holdings non-transferable.

### Perform a Force Transfer

1. On the **Instrument Management** page, click **Forced Transfer** above the instrument table.
2. In **Instrument ID**, select the instrument. The list shows your instruments with force transfer enabled.
3. In **Sender**, enter the party ID of the affected holder. **Requester** and **Receiver** show your registrar party.
4. In **Amount**, enter the amount to transfer, or click **Max**. The form shows the holder's **Available funds**: their unlocked holdings with force transfer enabled. The amount cannot exceed them.
5. In **Reference**, add a note, for example a regulatory order reference. It appears in the transaction history as `Force transfer: <reference>`.
6. Click **Send**.

Force transfer also works when a holder is blocklisted or is missing credentials.
To move the holdings to another party, for example as ordered by a regulatory order, the registrar then transfers them with a regular transfer. The usual blocklist and credential checks apply to the receiver.

### Perform a Force Transfer Programmatically

The registrar exercises the `Holding_ForceTransfer` choice of `Utility.Registry.Holding.V0.Holding:Holding` (`utility-registry-holding-v0` version `0.4.0` or later) on one of the holder's holdings:

| Argument | Description |
| :- | :- |
| `otherHoldingCids` | Additional holdings of the same holder and instrument to include. |
| `transferAmount` | Amount to transfer to the registrar. |
| `registrarLabel` | Account label of the registrar's new holding. |
| `reference` | Reference explaining the force transfer. |

The result contains the registrar's new holding (`receiverHoldingCid`) and the holder's remaining holding, if any (`remainingHoldingCid`). The remaining holding is in the account of the holding the choice is exercised on.

### Limitations

* **Locked holdings cannot be force transferred.** This includes holdings locked in pending transfer offers and allocations.
* **The participant node(s) hosting the holder must be online,** because it automatically validates and confirms the transaction. The holder does not need to approve it.
* **The participant node(s) hosting the holder must have vetted** `utility-registry-holding-v0 `**version** `0.4.0 `**or later.**

## Effect on Holdings

The table shows how each operation affects the holdings of an instrument with force transfer enabled:

| Operation | Behavior |
| :- | :- |
| **Minting** | New holdings have force transfer enabled. |
| **Transfers & Settlement** | The receiver's holdings, and the sender's change, have force transfer enabled. |
| **Burning** | The holder's remaining holdings keep force transfer enabled. |
| **Force Transfer** | The registrar receives a new holding with the transferred amount. Any remaining amount stays with the holder. |

For instruments with force transfer disabled, nothing changes.

## For Wallets

### Detect Force Transfer on Holdings

Holdings with force transfer enabled include this entry in the `meta` of their token standard holding view (v1 and v2):

```json theme={null}
{ "values": { "registry.app.digitalasset.com/force-transfer": "true" } }
```

Holdings with force transfer disabled have no such entry.

### Show Force Transfers in the Transaction History

A force transfer appears in the token standard transaction history (v1 and v2) as a transfer from the holder to the registrar (the instrument admin), with the reason `Force transfer: <reference>`. The holder does not submit this transaction, so wallets may want to label it, for example as "Force transfer by the registrar".

## For Trading Venues

### Check Whether an Instrument Has Force Transfer Enabled

Settlements of instruments with force transfer enabled require all involved participants to have vetted Registry App version `0.15` or later, see [V1 / V2 cross-version compatibility](https://docs.digitalasset.com/registry/apis/token-standard/cross-version-compatibility.md#recommended-approach-for-trading-venues). To check whether an instrument has force transfer enabled, call the instrument configuration endpoint of the Registry App with the instrument's default identifier:

```
POST /api/utilities/v0/contract/instrument-configuration
```

```json theme={null}
{
  "registrar": "<instrument admin party ID>",
  "instrumentIdentifier": {
    "source": "<instrument admin party ID>",
    "id": "<instrument ID>",
    "scheme": "RegistrarInternalScheme"
  }
}
```

The `payload.forceTransferEnabled` field of the response is `true` if the instrument has force transfer enabled.