# conversion

Source: https://docs.settlemint.com/docs/api-reference/token-features/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`](/docs/api-reference/token-features/conversion-minter) on the target asset.

For the operator how-to, see [Conversion how-to](/docs/operators/token-features/conversion). For the architecture model, see [Conversion architecture](/docs/architects/components/token-features/conversion). Use this page as the endpoint reference.

## Configuration during token creation [#configuration-during-token-creation]

```json
{
  "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 [#holder-conversion-request]

Submit the conversion against the convertible (source) token, which carries the `conversion` feature. The paired [`conversion-minter`](/docs/api-reference/token-features/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 [#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](/docs/api-reference/errors/platform-api-error-reference) for full status and remediation details.

## Mandatory conversion at window end [#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 [#related]

* [conversion-minter](/docs/api-reference/token-features/conversion-minter): required companion feature on the target asset.
* [Feature constraints](/docs/architects/components/token-features/feature-constraints#dependency-rules)