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 this workflow for mandatory convertible instruments or governed exception cases that the institution has already approved outside the holder flow.
The workflow uses the asset's Conversion feature, an active conversion trigger, a holder address, a principal amount, and wallet verification by an authorized operator. DALP submits the conversion against the configured conversion pair and records the transaction result for operational review.
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.
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
Open the forced conversion workflow
Open the asset detail page, go to the Conversion feature page, then select Manage Conversion > Force Convert.
The option is shown only when the asset has conversion enabled and the current operator is allowed to force convert that asset. If the option is not visible, confirm the conversion feature, the asset permissions, and the operator's Custodian role before continuing.
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. The trigger ID must be the bytes32 hexadecimal identifier for the trigger that governs the conversion event.
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.
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.
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. Keep the record with the mandatory conversion decision so an auditor can connect the business approval, the trigger, and the on-chain transaction.
API integration
Use the API path when the forced conversion is executed from an operator system instead of the Asset Console:
POST /api/v2/tokens/{tokenAddress}/conversion/forced-conversionsSend the token address in the path and include the holder address, principal amount, trigger ID, and wallet verification payload in the request body. The principal amount is submitted as the token's base-unit amount, and the trigger ID is the bytes32 hexadecimal identifier of the active conversion trigger.
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
- Conversion for the feature model, roles, triggers, and emitted events
- Asset detail workspace for locating asset actions and feature pages
- Per-asset RBAC for Custodian role context
- Token lifecycle API integration for conversion API operations