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.
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
A conversion is submitted against the convertible (source) token, which carries the conversion feature. The paired conversion-minter on the target token mints the matching target amount. The 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 the 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 final conversion was withheld. |
| 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"
}Available to authorised operators after conversionWindowEnd when the operating model includes mandatory conversion. The holder is the address whose tokens are converted.
Related
- conversion-minter — required companion feature on the target asset.
- Feature constraints
external-transaction-fee API
API reference for creating and updating the external-transaction-fee token feature, which charges fixed fees in a separate ERC-20 token for asset operations.
conversion-minter
API reference for the DALP conversion-minter token feature, the companion feature on the target asset of a conversion pair.