Token lifecycle

This guide visualizes the token lifecycle through flowcharts for each major operation. Use these diagrams to understand the sequence of API calls, required roles, and decision points when building automated workflows.

Create token operation

Creating a token deploys a new smart contract and configures its initial parameters.

Prerequisites:

• API key for authentication
• tokenManager system role
• Registered identity for your wallet

Required inputs:

• Common: type, name, symbol, decimals, countryCode, initialModulePairs, walletVerification
• Bond-specific: faceValue, maturityDate, denominationAsset
• Stablecoin-specific: priceCurrency, basePrice
• Fund-specific: priceCurrency, basePrice

Auto-granted roles:

When you create a token, you automatically receive:

• admin – Allows granting other roles on this token
• governance – Allows configuring compliance modules and token parameters

Next steps:

1. Grant supplyManagement role (for minting)
2. Grant emergency role (for unpausing)
3. Unpause the token
4. Add collateral (stablecoins only)
5. Mint initial supply

Example guides:

• Bonds
• Deposits
• Equities
• Funds
• Stablecoins

Mint tokens operation

Minting increases the token supply and sends tokens to specified recipients.

Prerequisites:

• API key for authentication
• supplyManagement token role
• Token must be unpaused (requires emergency role)
• Recipients must have registered identities
• For stablecoins: sufficient collateral must be added (requires trusted issuer status)

Required inputs:

• tokenAddress – Contract address from token creation
• recipients – Array of wallet addresses
• amounts – Array of amounts in smallest unit (BigInt)
• walletVerification – PINCODE verification

Validation checks:

1. Token is unpaused
2. Caller has supplyManagement role
3. Minting does not exceed cap (if set)
4. Recipients have registered identities
5. Stablecoins: sufficient collateral exists

Amount calculation:

All tokens use 18 decimals. To mint 100 tokens:

import { from } from "dnum";

const amount = from("100", 18); // 100 tokens

Example:

import { from } from "dnum";

await client.token.mint({
  tokenAddress: "0xABCD...",
  recipients: ["0x1234...", "0x5678..."],
  amounts: [from("100", 18), from("200", 18)],
  walletVerification: {
    verificationType: "PINCODE",
    secretVerificationCode: "123456",
  },
});

Burn tokens operation

Burning permanently reduces the token supply by destroying tokens from the caller's balance.

Prerequisites:

• API key for authentication
• supplyManagement token role
• Sufficient token balance to burn

Required inputs:

• tokenAddress – Contract address
• amount – Amount to burn in smallest unit (BigInt)
• walletVerification – PINCODE verification

Validation checks:

1. Caller has supplyManagement role
2. Caller has sufficient balance to burn
3. Amount is greater than zero

Example:

import { from } from "dnum";

await client.token.burn({
  tokenAddress: "0xABCD...",
  amount: from("50", 18),
  walletVerification: {
    verificationType: "PINCODE",
    secretVerificationCode: "123456",
  },
});

Use cases:

• Reduce supply after redemptions
• Adjust stablecoin supply to match collateral
• Retire tokens from circulation

Transfer tokens operation

Transfers send tokens from the caller's balance to a recipient. All transfers undergo compliance checks unless bypassed with a forced transfer.

Prerequisites:

• API key for authentication
• Token holder with sufficient balance
• Recipient must have registered identity
• Token must not be paused
• Sender and recipient addresses must not be frozen

Required inputs:

• tokenAddress – Contract address
• to – Recipient wallet address
• amount – Amount to transfer in smallest unit (BigInt)
• walletVerification – PINCODE verification

Compliance checks (automatic):

1. Sender has registered identity
2. Recipient has registered identity
3. Transfer satisfies all active compliance modules (e.g., allowlist, country restrictions, lock-up periods)
4. Token is not paused
5. Sender and recipient addresses are not frozen

Example:

import { from } from "dnum";

await client.token.transfer({
  tokenAddress: "0xABCD...",
  to: "0x1234...",
  amount: from("25", 18),
  walletVerification: {
    verificationType: "PINCODE",
    secretVerificationCode: "123456",
  },
});

Use cases:

• Send tokens to another investor
• Distribute tokens to multiple recipients
• Transfer tokens to a custody wallet

Forced transfer operation

Forced transfers bypass compliance checks and move tokens between addresses. This is a custodian operation used for regulatory interventions, court orders, or operational recovery.

Prerequisites:

• API key for authentication
• custodian token role
• Source wallet must have sufficient balance
• Destination wallet must not be frozen (source can be frozen)

Required inputs:

• tokenAddress – Contract address
• from – Source wallet address
• to – Recipient wallet address
• amount – Amount to transfer in smallest unit (BigInt)
• walletVerification – PINCODE verification

Compliance bypass:

Forced transfers skip all compliance checks including:

• Identity verification
• Allowlist restrictions
• Country/jurisdiction rules
• Lock-up periods
• Frozen sender addresses (but not frozen recipient addresses)

Example:

import { from } from "dnum";

await client.token.forcedTransfer({
  tokenAddress: "0xABCD...",
  from: "0x1234...", // Source wallet (can be frozen)
  to: "0x5678...", // Destination (must not be frozen)
  amount: from("100", 18),
  walletVerification: {
    verificationType: "PINCODE",
    secretVerificationCode: "123456",
  },
});

Use cases:

• Regulatory seizure or forfeiture
• Court-ordered asset recovery
• Operational recovery from compromised wallets
• Resolving stuck transfers due to compliance failures

Audit trail:

Every forced transfer emits a ForcedTransfer event on-chain with:

• from – Source address
• to – Destination address
• amount – Transferred amount
• executor – Custodian who executed the transfer
• timestamp – Block timestamp

Review forced transfers in the platform's audit log or via token.events.

Next steps

• Asset-specific guides – Follow step-by-step tutorials for each asset type:
  • Bonds
  • Deposits
  • Equities
  • Funds
  • Stablecoins
• API reference – Explore the OpenAPI spec and generate clients