# Token conversion

Source: https://docs.settlemint.com/docs/console/asset-management/manage/conversion
Convert a convertible note, SAFE or warrant into a share token against a published round, as an issuer, a custodian or a holder, and read what each side sees.

Token conversion turns units of a convertible instrument, such as a convertible note, a SAFE or a warrant, into newly minted units of a share token at the price of a funding round. The issuer publishes each priced round as a trigger. Holders then convert their own units against an open trigger, or a custodian converts for them. The platform settles the convertible units under the token's [debt method](#how-a-conversion-is-priced) and mints the shares in the same transaction. The terms themselves, such as the discount, the cap and the debt method, are fixed when the token is created and are listed under [Conversion](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/conversion#conversion) in the token features catalogue.

Two token features work together. The conversion feature sits on the convertible token and holds the terms: the target token, the denomination asset that prices every round, the discount, the price cap and the conversion window. The [conversion minter](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/conversion#conversion-minter) sits on the target token, the share token that holders receive. It mints only for the conversion features on its list of authorised converters, so the target token's governance role, together with its Supply management or admin role, decides which convertibles may mint into it. A conversion can also be recorded as a corporate action, with **Record conversion** in [Corporate actions](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-actions) records the event and links back to this page.

![Conversion page of a convertible note with the Configuration panel and Publish trigger](https://docs.settlemint.com/docs/screenshots/console-conversion-page.light.en.webp)

[Screenshot] The page heading "Conversion" with the "Convert" button beside it.

The **Configuration** panel lists the target token, the denomination asset, the discount, partial conversions, the conversion minter, active triggers and the conversion window with its badge and an "Edit" button. "Publish trigger" sits under the facts. Further down the page, "Force convert" sits in the danger area, followed by the "Triggers" and "Conversion history" tables.

A token gets the conversion feature only when it is created. Issue asset sets the conversion feature from the instrument template, and the Console has no control to attach it later. An asset without it shows "Conversion is not enabled for this asset" on its Conversion page.

## Before you start [#before-you-start]

- The target token carries the conversion minter. The target is a token already registered in your organisation, and it cannot be the convertible token itself. The conversion minter comes from the target's template, or an account that can set the target's feature list (Governance with Supply management and Custodian, or with admin) attaches it later through the Platform API. The Console offers no attach control for it.
- The minter lists the conversion feature as an authorised converter. The template can name converters at issuance. Otherwise an account with the governance role and the Supply management or admin role on the target token adds the conversion feature's address with **Add converter**. A conversion against a minter that does not list the feature fails.
- The conversion window is open, or opens when you need it. The Warrant template requires a window start and a window end, so a warrant cannot be created without a window. The window applies to forced conversions too, so after it closes nobody can convert.
- Interest is bound, if interest converts. The **Include accrued interest** switch on the conversion step of Issue asset converts a holder's accrued interest with the principal. When the token carries exactly one interest yield or fixed treasury yield feature, creation binds the conversion feature as the only feature allowed to use that interest. The Console states: "This is permanent. Creating the token binds the conversion feature as the only feature allowed to use the interest, and this cannot be undone." If the bind fails, creation stops at the step "Binding the conversion feature to the yield feature", and "Finish setup" on the asset list runs it again.

## Roles and controls [#roles-and-controls]

Each issuer action needs a role on the token it changes, and every write asks for wallet verification. None of them waits for a second person: one account with the governance role sets the round price, and one account with the custodian role can force a holder to convert at it.

| Action | Role | Token | Where in the Console |
| --- | --- | --- | --- |
| **Add converter**, **Remove converter** | Governance. **Add converter** also needs Supply management or admin | Target token | **Authorized converters** table on the Conversion page |
| **Publish trigger**, **Disable trigger** | Governance | Convertible token | Configuration panel and triggers table on the Conversion page |
| Change the conversion window | Governance | Convertible token | **Edit** on the **Conversion window** row |
| **Force convert** | Custodian | Convertible token | Danger area at the foot of the Configuration panel |
| **Convert** | None. The holder converts the holder's own units | Convertible token | Holding page, or the Conversion page title row |

The controls follow the account's roles:

- "Convert", "Add converter", "Disable trigger" and "Remove converter" show only to an account that holds their role.
- "Publish trigger", "Edit" and "Force convert" stay visible to everyone else but are greyed out.

When another wallet of the same user holds the role, the control is greyed out with "The role for this action sits on wallet `{wallet}`. Switch to that wallet to use it." A user who lacks one of the three controls in the Configuration panel sees the note "Governance holders publish triggers and set the conversion window. Custodians force a conversion."

## Steps [#steps]

### Open the token's conversion page [#open-the-tokens-conversion-page]

Open "All assets", select the convertible token, and open its Features tab. The conversion section shows the target token, the denomination asset, the discount and whether partial conversions are allowed. Select **View conversion details** to open the Conversion page. The same page opens on the target token, where it shows the minter side.

On the convertible token, the **Configuration** panel lists "Target token", "Denomination asset", "Discount", "Partial conversions", "Conversion minter", "Active triggers" and "Conversion window". Three rows change with the terms:

- **Partial conversions** reads "Allowed" or "Not allowed".
- **Conversion minter** reads "Found on the target token" when no minter was named at creation. The conversion feature then looks up the minter on the target token.
- The **Conversion window** row shows its dates, the time left before it closes while it is open and has an end, and a "Window open" or "Window closed" badge. With no start and no end the row reads "Unrestricted", and with one side set it reads "From" or "Until".

Below the panel sit the "Triggers" and "Conversion history" tables. Both tables shorten each trigger ID and conversion ID to its first and last characters. Open a row to see the full identifier with a "Copy" button. Prices carry the symbol of the denomination asset, "Principal" carries the convertible token's symbol, and "Target received" carries the target token's symbol. On the target token, the **Minter administration** panel shows "Total issuances", "Total minted" and the number of authorised converters, and the "Authorized converters" table lists each converter.

### Authorise the converter on the target token [#authorise-the-converter-on-the-target-token]

Skip this step when the target token's "Authorized converters" table already lists the conversion feature. Otherwise open the Conversion page of the target token and select "Add converter" in the table toolbar or its empty state. Enter the address of the conversion feature on the convertible token in "Converter address", and confirm with **Add converter**.

Only a contract that reports the conversion feature interface can be authorised. The minter does not check who deployed it, so authorise only the conversion feature address of a convertible your organisation issued. Because an authorised converter mints, adding one needs the Supply management or admin role on the target token besides Governance. Removing one needs Governance only. For a wallet or any other contract, the sheet shows "Enter the loan token's conversion feature contract address. A wallet or other contract can't be authorized as a converter." To stop a convertible from minting, select **Remove converter** in the converter's row menu.

### Set the conversion window [#set-the-conversion-window]

Read the "Conversion window" row on the convertible token. To change it, select **Edit** on that row. The "Set conversion window" sheet takes a "Window start" and a "Window end". The sheet fills in the current time as the start and an end 24 hours ahead. Both fields are required, so saving also sets a start. The end must lie in the future and after the start. The governance role can set a new window at any time, with an end earlier or later than before, so bringing the end forward or moving the start later closes the window on holders. A start in the future counts as closed until it arrives. The review step shows both moments with their time in UTC. Confirm with "Set window".

### Publish the round as a trigger [#publish-the-round-as-a-trigger]

Select **Publish trigger** in the Configuration panel, or in the empty triggers table. The "Publish conversion trigger" sheet asks for:

- **"Trigger ID":** a new identifier, 0x followed by 64 hexadecimal characters. An identifier already used on this token is refused. The Console does not generate one. Any unused 32-byte value works, for example a hash of the round name.
- **"Denomination asset":** the asset that prices the round. It must be the denomination asset of the conversion terms, and it must be a deployed token with ERC-20 metadata.
- **"Round price per share":** the price per share that the funding round set, in the denomination asset, as a decimal such as 2.5.
- **"Expiration date":** when the round closes for conversions. It must lie in the future and on or before the conversion maturity date, and starts 24 hours ahead.
- **"Metadata hash":** the hash of the round's off-chain details, such as the signed term sheet, 0x followed by 64 hexadecimal characters. The platform stores the value as entered and does not compare it with any document. Record which file you hashed and with which algorithm, so a reviewer can recompute it.

As you type the price, the sheet shows the "Discount", the "Price cap" or "No cap", the **Effective price per share**, and "Cap applies" when the cap lowers the price.

When the target token holds fewer decimals than the convertible token, the sheet warns "The target token holds fewer decimals", because every conversion then loses the rounded-off part. Check the effective price against the approved round terms, as [How a conversion is priced](#how-a-conversion-is-priced) explains, then confirm with **Publish trigger**.

![Publish conversion trigger sheet with the decimals warning and the trigger fields](https://docs.settlemint.com/docs/screenshots/console-conversion-publish-trigger.light.en.webp)

[Screenshot] The "Publish conversion trigger" sheet opens with the warning "The target token holds fewer decimals".

The fields "Trigger ID", "Denomination asset", "Round price per share", "Expiration date" and "Metadata hash" follow the warning. Under the price, a line asks you to enter the round price to see the price holders convert at.

### Let holders convert [#let-holders-convert]

Holders convert their own units while the trigger is active, unexpired and the window is open. No role is needed. A holder converts from the holding page in the Console or the Investor portal, as [What the holder sees](#what-the-holder-sees) describes. A holder can also select **Convert** beside the heading of the Conversion page. While the window is closed, that button is greyed out with "The conversion window is closed."

### Force a conversion when the terms make it mandatory [#force-a-conversion-when-the-terms-make-it-mandatory]

When the instrument terms require conversion without the holder's action, an account with the custodian role selects "Force convert" in the danger area of the Configuration panel. The "Force convert tokens" sheet takes the "Holder address", the "Principal amount" and the "Trigger ID". It shows the holder's "Current principal" and warns: "This force conversion overrides the holder's normal consent path and cannot be undone through the holder flow." The review step shows the estimated output in the target token's decimals and any part lost to rounding. Confirm with **Force convert**. A principal amount of 0 converts the holder's whole unconverted balance. A mandatory round needs one forced conversion per holder.

A forced conversion follows the same trigger and window rules as a holder's conversion. A forced full conversion closes the holder's interest accrual, so interest still unsettled stays claimable as cash yield and can no longer be converted into shares.

### Close a round before its expiry [#close-a-round-before-its-expiry]

To stop conversions against a round before its expiry, open the row menu of the active trigger in the "Triggers" table and select **Disable trigger**. The sheet states "Disable an active conversion trigger. This cannot be undone." A trigger stopped this way cannot be turned back on. To reopen the round, publish a new trigger with a new identifier.

## How a conversion is priced [#how-a-conversion-is-priced]

A trigger carries a round price per share in the denomination asset. The contract subtracts the discount from the round price, then lowers the result to the price cap when one is set. That is the effective price. The holder receives the converted value divided by the effective price, rounded down to the decimals of the target token. The converted value is the principal, with each convertible unit counted as one unit of the denomination asset, plus the accrued interest when the terms include interest. So one convertible unit must carry a face value of one unit of the denomination asset: a note with a face value of 1,000 USD, priced in a USD stablecoin, is issued as 1,000 units.

For example, a note carries a discount of 20%, set as 2,000 basis points, and a price cap of 1.80. The issuer publishes a round at 2.50 per share. The discount brings the price to 2.00, and the cap lowers it to 1.80. A holder who converts 900 notes receives 900 divided by 1.80, which is 500 shares.

The platform records the fraction lost to rounding with the conversion, and the conversion history shows it under the shares received. At the same 1.80, 250 notes converted into a share token with no decimals show "138" with "0.888888888888888888 lost to rounding". Nothing pays the fraction out. A conversion that would give zero shares is refused, and no units move.

The debt method, set at creation, decides what happens to the converted units. Burn destroys them. Lock moves them to the escrow address named when the token was created. The platform places no hold on that address, so whoever controls it controls the locked units. Mark as converted leaves them in the holder's wallet, but they can no longer be transferred or burned, and a forced transfer keeps that restriction.

## What the holder sees [#what-the-holder-sees]

The holder sees the conversion on the page of the holding. In the Console and the Investor portal, open "Wealth", then **Portfolio**, and select the holding's name in the holdings table.

1. The **Convert** control appears only when the token has a configured conversion feature and the holder has an available balance. It is the main button when nothing waits to be claimed or redeemed. Otherwise it sits in the "Actions" menu. Until the holder's claims and the token's features load, the item is greyed out with "Available once your claims and this asset's features have loaded".
2. The "Convert tokens" sheet opens with the balance card **Your conversion balance**, which shows "Available principal" and "Total converted".
3. The **Conversion round** list shows every open round, each as "Price" with the round price and "Open until" with the expiry date and time in UTC, or "No expiry". The sheet selects the only open round on its own. With no open round, it reads "No conversion round is open right now. Once the issuer publishes one, you can convert here." and the submit button stays greyed out. The sheet reads the newest 200 published triggers, so an older round cannot be picked there.
4. When the token's interest yield feature is bound to this conversion, the holder chooses what to convert: "Principal" or **Interest only**. "Interest only" converts the interest the holder is owed and leaves the principal as it is.
5. The **Principal amount** field takes the amount to convert, and 0 converts all available principal. When the terms do not allow partial conversions, the sheet reads "This token converts your whole principal at once."
6. The review step **Conversion preview** shows the round, the amount or "All available principal", and the "Effective price" per share. In the Console it also shows the "Estimated output" in the target token's decimals and how much is lost to rounding. The Investor portal preview shows the round, the amount and the effective price.
7. After **Confirm conversion** and wallet verification, the message reads "Tokens converted successfully" with the token name and symbol. The shares arrive in the holder's wallet as a holding of the target token. The convertible units leave the wallet, move to escrow, or stay in it marked as converted, per the debt method, and "Total converted" rises.

![Convert tokens sheet on a holding page with the conversion balance, three open rounds and the principal amount](https://docs.settlemint.com/docs/screenshots/console-conversion-convert-sheet.light.en.webp)

[Screenshot] The "Convert tokens" sheet with the conversion balance, the open rounds and the principal amount.

The sheet shows "Your conversion balance" with "Available principal" and "Total converted", then the "Conversion round" list with each open round's price and closing date, then "Principal amount". This token allows no partial conversions, so the amount is the whole principal, with "This token converts your whole principal at once."

The sheet names each round by the date it was published, in UTC, such as "Round published 1 Jan 2026". The price and the closing date sit on the line below the name. The review step repeats all three.

## What the platform checks [#what-the-platform-checks]

Every conversion, by a holder or a custodian, passes these checks before any unit moves:

- **The trigger.** It exists, is active, has not expired, and uses the same denomination asset as the conversion terms.
- **The window.** The current block time lies inside the conversion window. The Platform API checks the window before it queues the request, and the contract checks it again.
- **The amount.** The holder holds the amount. An amount of zero converts the whole unconverted balance. A part of that balance is refused unless partial conversion is allowed. An amount below the minimum conversion amount is refused.
- **The price and the output.** The effective price is greater than zero, and the output in target units is at least one base unit.
- **The interest.** When a holder's full conversion closes interest accrual, every convertible period must be settled first. Before the conversion, the Platform API converts the holder's unsettled interest into the target token, in up to 10 rounds, each its own transaction. A forced conversion skips this check.
- **The mint.** The target token has a conversion minter, the minter lists the conversion feature, and the conversion identifier is new. A failed mint reverts that conversion transaction, so the convertible units stay where they were. Interest settled in earlier rounds stays converted.

When a trigger is published, the platform checks that the identifier is new, that the denomination asset matches the terms and has ERC-20 metadata, and that a set expiry lies in the future.

## You should see [#you-should-see]

- On the Conversion page of the convertible token, the **Conversion history** table shows one row per conversion, with "Conversion ID", "Principal", "Target received" and "Status". "Holder", "Effective price", "Initiated" and "Forced" open from the "View" menu.
- A completed conversion shows the status **Minted**, and a forced one shows "Yes" under "Forced".
- In the **Triggers** table, the "Conversions" count of the trigger rises.
- On the target token, "Total issuances" and "Total minted" in the **Minter administration** panel rise by the same conversion.

## Troubleshooting [#troubleshooting]

**The conversion is refused because the window is not open or has closed**

The Platform API compared the chain time with the conversion window and stopped before it sent anything. A request
before the start returns [DALP-9460](https://docs.settlemint.com/docs/api-reference/errors) "The conversion window has not opened". Submit it
again after the start. A request after the end returns [DALP-9461](https://docs.settlemint.com/docs/api-reference/errors) "The conversion window
has closed", and retrying cannot reopen it. An account with the governance role can set a new window with a future
end. The platform does not check this against the instrument terms, so confirm the terms allow it first. If the
contract finds the window shut instead, the refusal is [DALP-4058](https://docs.settlemint.com/docs/api-reference/errors) "Conversion window not
open" or [DALP-4057](https://docs.settlemint.com/docs/api-reference/errors) "Conversion window closed".

**The trigger cannot be used**

The contract refused the trigger and no unit moved. [DALP-4324](https://docs.settlemint.com/docs/api-reference/errors) "Trigger expired" means
the expiry has passed, and [DALP-4325](https://docs.settlemint.com/docs/api-reference/errors) "Trigger not active" means an account with the
governance role turned the trigger off. Neither can be reversed, so the issuer publishes a new trigger and the holder
converts against it. [DALP-4326](https://docs.settlemint.com/docs/api-reference/errors) means no trigger with that identifier exists on this
token: check the Trigger ID against the **Triggers** table.

**Publishing a trigger is refused**

[DALP-4323](https://docs.settlemint.com/docs/api-reference/errors) "Trigger already exists" means the identifier was used before on this token:
choose a new one. [DALP-4421](https://docs.settlemint.com/docs/api-reference/errors) "Conversion trigger expiry timestamp is in the past" means
the expiry passed before the transaction was mined. [DALP-4064](https://docs.settlemint.com/docs/api-reference/errors) "Denomination mismatch"
means the trigger names another asset than the conversion terms. When the denomination address has no ERC-20 metadata,
the Platform API refuses the request with [DALP-9073](https://docs.settlemint.com/docs/api-reference/errors) before it sends anything, and the
sheet shows "No contract exists at this address on" with the network name when no contract exists there. In the price
preview, "No price to convert at" means the discount brings the price to zero, and "Price too large" means the
contract cannot hold the price. Enter another price.

**The amount is refused**

[DALP-4256](https://docs.settlemint.com/docs/api-reference/errors) "Partial conversion disabled" means the terms require the whole balance: enter
0 to convert all available principal. [DALP-4044](https://docs.settlemint.com/docs/api-reference/errors) "Below min conversion amount" means the
amount is under the minimum the terms set. [DALP-4126](https://docs.settlemint.com/docs/api-reference/errors) means the amount exceeds the
holder's balance, and [DALP-1016](https://docs.settlemint.com/docs/api-reference/errors) "Exceeds unconverted balance" means it exceeds the units
still unconverted. [DALP-4370](https://docs.settlemint.com/docs/api-reference/errors) means the output rounds down to zero target units: convert
a larger amount.

**The holder's interest is still settling**

A holder's full conversion that closes interest accrual waits until every convertible period is settled. The Platform
API first converts the holder's unsettled interest into the target token, in up to 10 rounds, each its own
transaction. When interest is still settling after those rounds, it refuses with
[DALP-9080](https://docs.settlemint.com/docs/api-reference/errors) "Convert is settling this holder's accrued-interest backlog to target tokens"
and HTTP status 409. The interest rounds already done stay converted. This refusal is retryable: the holder submits
the conversion again after the settlement lands. The contract's own refusal for the same case is
[DALP-9081](https://docs.settlemint.com/docs/api-reference/errors) "Convert needs the accrued-interest backlog settled first."

**An interest-only conversion is refused**

When the holder chooses **Interest only** and has no unsettled convertible interest, or the conversion feature has no
interest provider or more than one, the Platform API refuses with [DALP-9487](https://docs.settlemint.com/docs/api-reference/errors) "The holder
has no convertible interest to convert" and HTTP status 409. No interest is converted. Retrying at once returns the
same error. Convert principal instead. With one interest provider, convert interest only after it accrues.

**The mint fails on the target token**

[DALP-4056](https://docs.settlemint.com/docs/api-reference/errors) "Conversion minter missing" means the target token has no conversion minter.
An account that can set the target token's feature list attaches it through the Platform API, then the holder retries.
[DALP-4334](https://docs.settlemint.com/docs/api-reference/errors) means the minter does not list this conversion feature: add it with **Add
converter** on the target token. In both cases the conversion reverts as a whole, and the holder keeps the convertible
units.

**A holder cannot move converted units**

Under the mark-as-converted debt method, converted units stay in the wallet but cannot be transferred or burned. A
transfer of them returns [DALP-1007](https://docs.settlemint.com/docs/api-reference/errors) **Cannot transfer converted tokens**. Only the
unconverted balance moves.

## Frequently asked questions [#frequently-asked-questions]

### Can a holder convert after the window closes?

No. The window applies to every conversion, forced ones included, so a warrant lapses at the end of its window. An account with the governance role can set a new window with an earlier or later end. The platform does not check that change against the instrument terms, so confirm the terms allow it first.

### Does the issuer have to convert every holder?

No. Each holder converts at a time of the holder's choosing while a round is open. The custodian role exists for terms that make conversion mandatory, and it converts one holder per request.

## API routes [#api-routes]

The Platform API offers the same operations. The convert, trigger and converter routes sit under the feature name `conversion-minter`, and `assetId` is the convertible token, except for the converter routes, where it is the target token. The [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2) describes each request and response.

| Method | Route | Use |
| --- | --- | --- |
| `POST` | `/api/v2/tokens/{assetId}/features/conversion-minter/conversions` | Convert the caller's units. `scope` set to `interest` converts interest only. |
| `POST` | `/api/v2/tokens/{assetId}/features/conversion-minter/forced-conversions` | Force a conversion for a holder. Custodian role. |
| `POST` | `/api/v2/tokens/{assetId}/features/conversion-minter/triggers` | Publish a trigger. The price is a whole number scaled to 18 decimals, and the expiry is optional. Governance role. |
| `POST` | `/api/v2/tokens/{assetId}/features/conversion-minter/trigger-disablements` | Turn a trigger off. Governance role. |
| `PATCH` | `/api/v2/tokens/{assetId}/features/conversion-minter` | Change the conversion window. Governance role. |
| `POST` | `/api/v2/tokens/{assetId}/features/conversion-minter/authorized-converters` | Add a converter on the target token. Governance role, plus Supply management or admin. |
| `DELETE` | `/api/v2/tokens/{assetId}/features/conversion-minter/authorized-converters` | Remove a converter from the target token. Governance role. |
| `GET` | `/api/v2/tokens/{assetId}/conversion/triggers` | List the triggers with their effective price, expiry and status. |
| `GET` | `/api/v2/tokens/{assetId}/conversion/records` | List the conversions. |
| `GET` | `/api/v2/tokens/{assetId}/conversion/events` | List the trigger events. |
| `GET` | `/api/v2/tokens/{assetId}/conversion/holder-state` | Read one holder's available principal, total converted and whether interest-only conversion is available. |
| `GET` | `/api/v2/tokens/{assetId}/conversion/converts-to` | List the tokens this token converts into. |
| `GET` | `/api/v2/tokens/{assetId}/conversion/converted-from` | List the tokens that convert into this token. |