Forced conversion
Run a custodian-initiated conversion that bypasses the holder consent path, used for mandatory convertible instruments and institution-approved exception cases.
An active conversion trigger is the entry point for this workflow. When a mandatory convertible instrument reaches its trigger event, the custodian initiates the conversion directly rather than waiting for the holder to act.
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.
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 currently open, or the asset has no conversion window.
- 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.
How the Force Convert entry appears depends on your roles for that asset:
- Enabled when you hold the asset's Custodian role. Select it to open the forced conversion sheet.
- Disabled with a tooltip when you can manage the conversion but do not hold the Custodian role. This is common when you published the trigger or set the conversion window without being the custodian. The tooltip explains that you cannot force convert because you do not have the Custodian role for this token. A Permission manager can grant you the Custodian role, after which the item becomes selectable.
- Absent when you have no conversion-management permissions for the asset.
If you see the disabled entry, get the Custodian role granted before continuing. See Change asset admin roles for how a Permission manager grants Custodian.
Specify the holder address, amount, and trigger ID
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 satisfies the asset's conversion policy. If the asset disables partial conversion, use the holder's full convertible-principal balance. If the asset sets a minimum conversion amount, 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 conversion.
After submission, record the transaction result alongside the approving operator, trigger ID, holder address, and approval evidence. Keep the record with the mandatory conversion decision so an auditor can trace the business approval to the trigger and to the on-chain transaction.
API integration
Use the API path when an operator system runs the forced conversion instead of the Console.
POST /api/v2/tokens/{tokenAddress}/conversion/forced-conversionsSend the token address in the path. Include the holder address, principal amount, trigger ID, and wallet verification payload in the request body. Express the principal amount in the token's base unit. The trigger ID is the bytes32 hexadecimal identifier of the active conversion trigger.
Troubleshooting
| Issue | Check |
|---|---|
| Force Convert is disabled | You manage the conversion but lack the Custodian role. Have a Permission manager grant Custodian, then reopen the menu. |
| Force Convert is not shown | Confirm the asset has the Conversion feature enabled and you hold the conversion roles. |
| 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 against the trigger record, holder address, and approval evidence. |
Related guides
- Conversion for the feature model, role requirements, trigger configuration, and emitted events
- Asset detail workspace for navigating asset controls and feature pages
- Per-asset RBAC for Custodian role context
- Token lifecycle API integration for conversion API operations
Forced transfer
A custodian-authorised on-chain transaction that debits one holder and credits another, bypassing normal approval and freeze controls for governed exception cases.
Authorized converters
Add or remove converter addresses for conversion-minter assets before running governed conversion workflows.