conversion
API reference for the conversion token feature: configuration parameters, the holder conversion request, and how to handle staged interest settlement on a full conversion.
The conversion token feature handles instruments that exchange holdings into a target token at a configured rate. It always pairs with conversion-minter on the target asset.
For the operator how-to, see Conversion how-to. For the architecture model, see Conversion architecture. Use this page as the endpoint reference.
Configuration during token creation
{
"conversion": {
"targetToken": "0x...",
"conversionMinter": "0x...",
"denominationAsset": "0x...",
"discountBps": 2000,
"capPricePerShareWad": "...",
"conversionWindowStart": "2026-06-01",
"conversionWindowEnd": "2027-12-31",
"minConversionAmount": "1.00",
"partialAllowed": true,
"includeInterestInConversion": true,
"closeInterestOnConversion": true
}
}| Parameter | Type | Required | Description |
|---|---|---|---|
targetToken | Ethereum address | Yes | Token the holder converts into. Must be equity-class or retirement. |
conversionMinter | Ethereum address | Yes | Address of the conversion-minter on the target token. |
denominationAsset | Ethereum address | Yes | ERC-20 for any cash-leg payments. |
discountBps | Integer | Yes | Conversion discount in basis points. |
capPricePerShareWad | Decimal string (WAD) | Optional | Optional cap on conversion price. |
conversionWindowStart | ISO 8601 date | Yes | When conversion becomes available. |
conversionWindowEnd | ISO 8601 date | Yes | When conversion closes. |
minConversionAmount | Decimal string | Yes | Minimum per-request conversion amount. |
partialAllowed | Boolean | Yes | Whether partial conversions are allowed. |
includeInterestInConversion | Boolean | Yes | Whether accrued interest converts. |
closeInterestOnConversion | Boolean | Yes | Whether interest accrual stops after conversion. |
Holder conversion request
Submit the conversion against the convertible (source) token, which carries the conversion feature. The paired conversion-minter on the target token mints the matching target amount. Your request identifies the trigger that prices and authorises the conversion.
POST /api/v2/tokens/{tokenAddress}/features/conversion-minter/conversions
{
"principalAmount": "1000000000000000000",
"triggerId": "0x0000000000000000000000000000000000000000000000000000000000000001"
}| Field | Type | Required | Description |
|---|---|---|---|
tokenAddress | Ethereum address | Yes | The convertible (source) token's address, where the conversion feature lives. |
principalAmount | Decimal string (wei) | Yes | Principal to convert, in the token's smallest unit. |
triggerId | bytes32 hex | Yes | The active trigger that prices and authorises the conversion. |
The platform burns the source position and the paired conversion-minter mints the matching target amount. Conversion is window-bound and validates against minConversionAmount and partialAllowed.
Settling accrued interest on a full conversion
When includeInterestInConversion and closeInterestOnConversion are both enabled, a full conversion also converts the holder's accrued interest into target tokens before interest accrual closes. The platform settles that interest in bounded batches, so a holder with a large accrued-interest backlog may need more than one request to finish.
If the backlog cannot be fully settled in a single request, the endpoint returns HTTP 409 with error id DALP-9080. This response is transient and retryable, not a rejection. Each completed request settles a further batch of interest, and progress is durable on-chain, so re-submitting repeats no work.
To complete the conversion, re-submit your same request until it succeeds:
POST /api/v2/tokens/{tokenAddress}/features/conversion-minter/conversions
{
"principalAmount": "1000000000000000000",
"triggerId": "0x0000000000000000000000000000000000000000000000000000000000000001"
}| Field | Value | Meaning |
|---|---|---|
| HTTP status | 409 | The conversion is still in progress; the platform withheld the final conversion. |
| Error id | DALP-9080 | The accrued-interest backlog needs another request to finish settling. |
| Retryable | Yes | Re-submit the same request. The conversion completes once the backlog is fully settled. |
Partial conversions are not affected. They settle only the prorated interest and never return this response. See the API error reference for full status and remediation details.
Mandatory conversion at window end
POST /api/v2/tokens/{tokenAddress}/features/conversion-minter/forced-conversions
{
"holder": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
"principalAmount": "1000000000000000000",
"triggerId": "0x0000000000000000000000000000000000000000000000000000000000000001"
}This endpoint is available to authorised operators after conversionWindowEnd when your operating model includes mandatory conversion. The holder is the address whose tokens the platform converts.
Related
- conversion-minter: required companion feature on the target asset.
- Feature constraints
External transaction fee API
Endpoint reference for the external-transaction-fee feature, covering creation-time parameters and the mutation routes for updating fee amounts, recipient, fee token, and freeze state.
conversion-minter feature API reference
How to grant mint authority and configure the conversion-minter feature on the target asset so it mints to holders when the paired source asset burns their position.