# Forced conversion

Source: https://docs.settlemint.com/docs/user-guides/asset-servicing/forced-conversion
Convert a holder's convertible-principal balance through a custodian-controlled exception workflow.



Forced conversion lets a custodian convert a holder's convertible-principal balance without waiting for the holder to start the conversion.

Use forced conversion only for mandatory convertible instruments or governed exception cases that the institution has approved outside the holder flow.

The action uses an active conversion trigger, a holder address, and a principal amount. The confirmation step shows a custodian override warning and the holder's current principal before submission.

<Callout type="warn" title="Custodian-only exception workflow">
  Forced conversion bypasses the holder's normal consent path and cannot be undone through the holder flow. Run it only
  from an operator with the asset's Custodian role, verify the trigger and amount before submission, and keep the
  approval evidence with the transaction record.
</Callout>

## Prerequisites [#prerequisites]

* The asset has the Conversion feature configured.
* The target conversion trigger is active and matches the mandatory conversion event you are executing.
* The conversion window is open, or no conversion window is set for the asset.
* The operator has the asset's Custodian role.
* The holder address has enough convertible principal for the requested amount.
* The requested amount respects the asset's partial-conversion and minimum-conversion settings.
* Your operating record contains the business reason, approval evidence, trigger identifier, holder address, amount, and expected result.

## Steps [#steps]

<Steps>
  <Step>
    ### Open the forced conversion workflow [#open-the-forced-conversion-workflow]

    Open the asset detail page, go to the Conversion feature page, then select **Manage Conversion** > **Force Convert**.

    If the option is not visible, confirm that the asset has conversion enabled and that your user has the Custodian role for that asset.
  </Step>

  <Step>
    ### Enter the holder, amount, and trigger [#enter-the-holder-amount-and-trigger]

    Provide the holder address, the principal amount to convert, and the trigger ID for the active conversion trigger.

    Use the exact trigger ID from the conversion trigger record. Forced conversion uses that trigger to calculate and execute the conversion against the configured conversion pair.

    Before continuing, confirm the amount is allowed by the asset's conversion policy. If partial conversion is disabled, use the holder's full convertible-principal balance. If a minimum conversion amount is configured, enter at least that amount.
  </Step>

  <Step>
    ### Review the custodian override [#review-the-custodian-override]

    Review the confirmation card before submitting. It shows:

    * the holder address;
    * the holder's current principal, when available;
    * the principal amount to force convert;
    * the trigger ID;
    * the custodian override warning.

    If the current principal is unavailable, verify the holder balance through your operating view or API integration before submitting.
  </Step>

  <Step>
    ### Submit and record the result [#submit-and-record-the-result]

    Authenticate with the required wallet verification method and submit the action.

    After submission, record the transaction result with the approving operator, trigger ID, holder address, amount, and approval evidence.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

| Issue                     | Check                                                                                                  |
| ------------------------- | ------------------------------------------------------------------------------------------------------ |
| Option not visible        | Confirm the asset has conversion enabled and the operator has the Custodian role.                      |
| Trigger is rejected       | Confirm the trigger ID is active, correctly formatted, and valid for the conversion window.            |
| Window is closed          | Confirm the current time is inside the conversion window, unless the asset has no window configured.   |
| Amount is rejected        | Confirm the holder has enough principal and the amount satisfies partial-conversion and minimum rules. |
| Principal is unavailable  | Verify the holder address and check the holder balance from the operating view or API.                 |
| Transaction is rejected   | Confirm the asset is not paused, the trigger is valid, and wallet verification passed.                 |
| Result needs audit review | Compare the transaction result with the trigger record, holder address, amount, and approval evidence. |

## Related guides [#related-guides]

* [Conversion](/docs/architecture/components/token-features/conversion) for the feature model, roles, triggers, and emitted events
* [Asset detail workspace](/docs/user-guides/asset-servicing/asset-detail-workspace) for locating asset actions and feature pages
* [Per-asset RBAC](/docs/architecture/components/asset-contracts/rbac) for Custodian role context