# Conversion

Source: https://docs.settlemint.com/docs/operators/token-features/conversion
How operators configure the conversion token feature for convertible instruments that exchange holdings into a target equity or settlement token.



The conversion token feature handles instruments that exchange their holdings into a target token at a configured rate, discount, or window. Use it for convertible notes that convert into equity, carbon credits that retire into a retirement token, or any composable instrument where the lifecycle ends in conversion rather than redemption.

Conversion always pairs with [conversion-minter](/docs/operators/token-features/conversion-minter). The minter feature handles the target-side minting that mirrors the source-side burn during conversion.

For the architecture reference, see [Conversion](/docs/architects/components/token-features/conversion).

## When it attaches [#when-it-attaches]

Convertible-note (`system-convertible-note`) and carbon-credit (`system-carbon-credit`) templates attach conversion + conversion-minter.

## What you configure [#what-you-configure]

In the Asset Designer details step, the wizard surfaces:

| Parameter                     | Description                                                                                                                               |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `targetToken`                 | The token holders convert into. Must be an equity-class token for convertible notes, or a retirement token for carbon credits.            |
| `conversionMinter`            | Address of the conversion-minter on the target token. The Designer wires this automatically if both features attach during the same flow. |
| `denominationAsset`           | ERC-20 used for any interest or partial-payment leg.                                                                                      |
| `discountBps`                 | Conversion discount in basis points (e.g. 2000 for 20% discount).                                                                         |
| `capPricePerShareWad`         | Optional cap on the conversion price.                                                                                                     |
| `conversionWindowStart`       | When conversion becomes available.                                                                                                        |
| `conversionWindowEnd`         | When conversion stops being available. After this, mandatory conversion may force-convert remaining holdings.                             |
| `minConversionAmount`         | Minimum amount per conversion request.                                                                                                    |
| `partialAllowed`              | Whether partial conversion is allowed.                                                                                                    |
| `includeInterestInConversion` | Whether accrued interest converts with the principal.                                                                                     |
| `closeInterestOnConversion`   | Whether interest accrual closes after conversion.                                                                                         |

The target-token prerequisite is checked during template selection: if no compatible equity-class (or retirement) target exists, the template card is disabled.

## What you operate [#what-you-operate]

After deployment:

* **Communicate the conversion window** to holders. Conversion is window-bound; outside the window, holders cannot voluntarily convert.
* **Holders submit conversion** through the platform's conversion flow during the window. The feature burns the source holding and the conversion-minter mints the target.
* **Optional mandatory conversion** at the window end. If the operating model includes force-convert at maturity, an authorised operator triggers the mandatory-conversion action.

## Operating considerations [#operating-considerations]

* Conversion always pairs with conversion-minter. The Asset Designer enforces this composition rule.
* Target-token authority must include the conversion-minter as a permitted minter on the target. The Designer wires this when both assets are managed by the same operating team; cross-organisation conversions require manual minter approval on the target.
* Conversion-window dates are restricted-mutable. Plan changes around the window boundaries.
* Discount and cap interact: a 20% discount with no cap can produce a different conversion ratio than 20% discount with a cap, depending on the target token's price at conversion time.

## Troubleshooting [#troubleshooting]

| What you see                             | What to check                                                                                                                                              |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Conversion rejected as outside window    | Confirm the conversion window is open and the holder's request reaches the platform during the window.                                                     |
| Conversion fails with minter error       | Confirm the conversion-minter on the target token authorises this conversion contract.                                                                     |
| Holder receives unexpected target amount | Confirm the discount, cap, and target-token price feed are configured correctly. Conversion math runs against the prices recorded at the conversion block. |

## Read next [#read-next]

* [Conversion architecture](/docs/architects/components/token-features/conversion)
* [Conversion minter](/docs/operators/token-features/conversion-minter) — required companion feature.
* [System templates catalog](/docs/operators/asset-creation/system-templates#fixed-income-asset-class-fixed-income)