Issuing and Managing a Token
This guide covers the full lifecycle of a fungible token on Mintlayer, from issuance through supply management, transfers, and optional freeze or supply locking.
Prerequisites
- A running, synced
node-daemon wallet-cliconnected to the node- A small amount of TML to cover transaction fees
Concepts
Token id: A unique identifier assigned to your token when it is issued. All subsequent management commands reference this id.
Authority address: The address whose key controls all management operations, minting, unminting, freezing, changing the metadata URI, and transferring authority. Keep the corresponding key secure.
Circulating supply vs total supply: Issuing a token defines its properties and maximum supply, but tokens are not spendable until they are minted into the circulating supply. Minting moves tokens from the reserve into circulation; unminting reverses this.
The token lifecycle, and where each management command fits:
Part 1: Issuing a Token
Decide your supply model
Before issuing, decide how you want supply to work:
| Supply type | What it means |
|---|---|
fixed(<amount>) | Total supply is set at issuance and can never change. No minting or unminting is possible. |
lockable | Supply starts unlimited but can be permanently locked later with token lock-supply, fixing it at the current circulating amount. |
unlimited | Supply is always unlimited. Minting and unminting are always available. |
Issue the token
token issue <TOKEN_TICKER> <NUMBER_OF_DECIMALS> <METADATA_URI> <AUTHORITY_ADDRESS> <TOKEN_SUPPLY> <IS_FREEZABLE>
Examples:
# Fixed supply of 1,000,000 tokens with 8 decimal places, not freezable
token issue MYTKN 8 https://example.com <authority_address> fixed(1000000) not-freezable
# Lockable supply (start unlimited, lock later), freezable
token issue MYTKN 8 https://example.com <authority_address> lockable freezable
# Unlimited supply, not freezable
token issue MYTKN 8 https://example.com <authority_address> unlimited not-freezable
After the transaction is confirmed, the output will include the token id. Record it, you will need it for every subsequent operation.
Fixed-supply tokens
If you issued with fixed(<amount>), the full supply is created at issuance and sent directly to the authority address. No minting step is needed. Skip to Part 3: Transferring Tokens.
Part 2: Minting and Unminting
For lockable and unlimited supply tokens, tokens must be minted before they can be transferred.
Mint tokens into circulation
token mint <token_id> <recipient_address> <amount>
The authority key must be in the selected account. Minted tokens are sent to <recipient_address>, this can be any address, including one in the same wallet.
Unmint tokens
Unminting reduces the circulating supply and returns the tokens to the issuer's control. The wallet must hold both the tokens being unminted and the authority key.
token unmint <token_id> <amount>
Lock the supply permanently
If you issued with lockable supply and want to make the current circulating amount the permanent total supply:
token lock-supply <token_id>
This is irreversible. After locking, minting and unminting are no longer possible. Use this when you are ready to commit to a fixed supply.
Part 3: Transferring Tokens
Send tokens to any address:
token send <token_id> <destination_address> <amount>
Transaction fees are paid in TML, not in the token being sent. The wallet calculates fees automatically.
Part 4: Ongoing Management
Update the metadata URI
token change-metadata-uri <token_id> <new_uri>
Use this to update the URL pointing to your token's website, documentation, or media.
Transfer authority to another address
token change-authority <token_id> <new_authority_address>
After this transaction is confirmed, the old authority key loses all management rights. Make sure the new address is accessible before transferring.
Freeze the token
Freezing blocks all operations on the token for all users. This requires the token to have been issued with freezable.
# Freeze but allow unfreezing later
token freeze <token_id> unfreezable
# Freeze permanently: cannot be reversed
token freeze <token_id> not-unfreezable
Unfreeze the token
Only possible if the token was frozen with the unfreezable option:
token unfreeze <token_id>
Supply Model Decision Summary
| Requirement | Recommended supply type | Freezable? |
|---|---|---|
| Fixed from day one, no changes ever | fixed(<amount>) | Either |
| Start with minting flexibility, then lock | lockable | Either |
| Always mintable, no cap | unlimited | Either |
| Need emergency stop capability | Any | freezable |
| No central freeze risk | Any | not-freezable |
Quick Reference
| Task | Command |
|---|---|
| Issue a token | token issue <ticker> <decimals> <uri> <authority> <supply> <freezable> |
| Mint tokens | token mint <token_id> <address> <amount> |
| Unmint tokens | token unmint <token_id> <amount> |
| Lock supply permanently | token lock-supply <token_id> |
| Send tokens | token send <token_id> <address> <amount> |
| Update metadata URI | token change-metadata-uri <token_id> <uri> |
| Transfer authority | token change-authority <token_id> <new_authority> |
| Freeze token | token freeze <token_id> unfreezable|not-unfreezable |
| Unfreeze token | token unfreeze <token_id> |