# conversion

Source: https://docs.settlemint.com/docs/developers/api-integration/token-features/conversion
API reference for configuring the conversion token feature during token creation and operating the conversion-window mechanics for convertible instruments.



The `conversion` token feature handles instruments that exchange holdings into a target token at a configured rate. It always pairs with [`conversion-minter`](/docs/developers/api-integration/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).

## 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]

```
POST /api/v2/token/{address}/features/conversion/convert
{
  "amount": "100.00"
}
```

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`.

## Mandatory conversion at window end [#mandatory-conversion-at-window-end]

```
POST /api/v2/token/{address}/features/conversion/force-convert
```

Available to authorised operators after `conversionWindowEnd` when the operating model includes mandatory conversion.

## Related [#related]

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