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
  }
}

Manage triggers and the conversion window

A conversion trigger is the priced, authorised round a holder converts against. Before holders can convert, an operator with the governance role publishes a trigger and opens the conversion window. The three endpoints below publish a trigger, disable one, and set the window. They run against the convertible (source) token, which carries the conversion feature, and each returns the updated token once the transaction settles. To read existing triggers and audit their published, disabled, and republished lifecycle, see Token conversion triggers.

Publish a trigger

Publish a priced round that holders can convert against. The trigger carries the round price, the denomination it is priced in, an optional expiry, and a metadata hash that anchors the off-chain pricing document.

POST /api/v2/tokens/{tokenAddress}/features/conversion-minter/triggers
{
  "triggerId": "0x0000000000000000000000000000000000000000000000000000000000000001",
  "denominationAsset": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
  "roundPricePerShareWad": "1000000000000000000",
  "expiresAt": "2051222400",
  "metadataHash": "0x0000000000000000000000000000000000000000000000000000000000000001"
}

DALP applies the feature's configured discountBps and capPricePerShareWad to the round price to produce the effective price a holder receives. Publishing the trigger only authorises the round; holders convert against it separately, and only while the conversion window is open and the trigger is active and unexpired.

Disable a trigger

Take an active trigger out of service. Disabling stops new conversions against the round while keeping the trigger in the trigger list for history.

POST /api/v2/tokens/{tokenAddress}/features/conversion-minter/trigger-disablements
{
  "triggerId": "0x0000000000000000000000000000000000000000000000000000000000000001"
}

Disabling a trigger is a one-way transition. If the trigger does not exist, the request is rejected with DALP-4326. If the trigger exists but is already disabled, it is rejected with DALP-4325. Disabling the same trigger a second time is rejected rather than logged again, so the original disable time stays authoritative. To introduce new terms, publish a fresh trigger with its own triggerId.

Set the conversion window

Set or update the window during which holders can convert. Conversion is window-bound: before the start, a conversion request is rejected as not yet open; after the end, it is rejected as closed.

PATCH /api/v2/tokens/{tokenAddress}/features/conversion-minter/window
{
  "start": "2050908800",
  "end": "2051222400"
}

When end is non-zero, the start must not be after the end, and the end must not be in the past. Confirm the window before you announce it to holders, because a holder cannot convert outside it.

Failure cases

See the API error reference for full status and remediation details.

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"
}

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"
}

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