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 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 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 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 records the event and links back to this page.
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.
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.
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
Open the token's 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
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
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
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 explains, then confirm with Publish trigger.
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
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 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
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
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
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
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.
- 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”.
- The “Convert tokens” sheet opens with the balance card Your conversion balance, which shows “Available principal” and “Total converted”.
- 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.
- 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.
- 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.”
- 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.
- 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.
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
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.
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 “The conversion window has not opened”. Submit it again after the start. A request after the end returns DALP-9461 “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 “Conversion window not open” or DALP-4057 “Conversion window closed”.
The trigger cannot be used
The contract refused the trigger and no unit moved. DALP-4324 “Trigger expired” means the expiry has passed, and DALP-4325 “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 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 “Trigger already exists” means the identifier was used before on this token: choose a new one. DALP-4421 “Conversion trigger expiry timestamp is in the past” means the expiry passed before the transaction was mined. DALP-4064 “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 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 “Partial conversion disabled” means the terms require the whole balance: enter 0 to convert all available principal. DALP-4044 “Below min conversion amount” means the amount is under the minimum the terms set. DALP-4126 means the amount exceeds the holder's balance, and DALP-1016 “Exceeds unconverted balance” means it exceeds the units still unconverted. DALP-4370 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 “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 “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 “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 “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 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 Cannot transfer converted tokens. Only the unconverted balance moves.
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
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 describes each request and response.