Manage Tokens

Learn how to manage your tokens on Spark after creation. This guide covers minting new tokens, freezing/unfreezing addresses, burning tokens, and monitoring token activity.

Token Management Overview

Once you’ve created your token, you can perform various management operations to control its supply, distribution, and behavior on the Spark network.

Mint Tokens

Create new tokens to increase supply

Freeze/Unfreeze

Control token transfers for specific addresses

Burn Tokens

Permanently remove tokens from circulation

Mint Tokens

Minting on Spark is available immediately after your token is created. The mintTokens function lets you create new tokens, either to set the initial supply or to mint more over time as needed. mintTokens(tokenAmount) Mints new tokens directly to the issuer’s Spark address.

const transactionId = await wallet.mintTokens(BigInt(1000000));
console.log("Spark Transaction ID:", transactionId);

Show Parameters

tokenAmount

bigint

required

The amount to mint in base units (e.g., 1000000n for 1.000000 tokens with 6 decimals)

Show Returns

transactionId

string

required

Spark transaction ID of the minting operation

What You Need to Know

Only Creator Can Mint

Only the creator wallet can mint tokens

Minted to Creator

Tokens are minted directly to the creator’s Spark address

Base Units Required

Amount must be specified in base units

Instant Transaction

Minting is a single, instant transaction

Minting Examples

Initial Supply Minting

// Mint initial supply of 1,000,000 tokens (6 decimals)
const initialSupply = BigInt(1000000000000); // 1,000,000.000000 tokens
const mintTx = await wallet.mintTokens(initialSupply);
console.log("Initial supply minted:", mintTx);

Ongoing Minting

// Mint additional tokens as needed
const additionalTokens = BigInt(100000000); // 100,000.000000 tokens
const mintTx = await wallet.mintTokens(additionalTokens);
console.log("Additional tokens minted:", mintTx);

Where Are Tokens Minted?

When you mint tokens on Spark, they’re credited directly to your issuer’s Spark address derived from:

sp + <token_public_key>

This address is bech32m-encoded and generated automatically when you create your wallet. All minted supply is sent here by default. You can’t specify a different destination when minting. Transfers must happen in a separate step.

Freeze & Unfreeze Tokens

The freeze functionality allows token issuers to freeze and unfreeze tokens at specific Spark Addresses, only available for tokens created with isFreezable: true.

Freeze Tokens

freezeTokens(sparkAddress) Freezes tokens for a specific Spark address, preventing them from sending or receiving your token.

const freezeResult = await wallet.freezeTokens("spark1...");
console.log("Freeze result:", freezeResult);

Show Parameters

sparkAddress

string

required

The Spark Address to freeze

Show Returns

freezeResult

object

required

Object containing impacted output IDs and token amount

impactedOutputIds

string[]

required

Array of output IDs that were frozen

impactedTokenAmount

bigint

required

Total amount of tokens that were frozen

Unfreeze Tokens

unfreezeTokens(sparkAddress) Unfreezes tokens for a specific Spark address, restoring their ability to send and receive your token.

const unfreezeResult = await wallet.unfreezeTokens("spark1...");
console.log("Unfreeze result:", unfreezeResult);

Show Parameters

sparkAddress

string

required

The Spark Address to unfreeze

Show Returns

unfreezeResult

object

required

Object containing impacted output IDs and token amount

impactedOutputIds

string[]

required

Array of output IDs that were unfrozen

impactedTokenAmount

bigint

required

Total amount of tokens that were unfrozen

Freeze Requirements

Token Must Be Freezable

Token must be created with isFreezable: true

Only Issuer Can Freeze

Only the issuer can freeze or unfreeze addresses

Issuer Cannot Be Frozen

Issuer’s own address cannot be frozen

Instant Effect

Freeze takes effect instantly across the network

Freeze Examples

// Freeze tokens for a specific address
const targetAddress = "spark1s2h8nvdh4h7h43tcwjdcysf7v0fprz5uh6vshs4n0tvhgzz2xgcqpg8yqv7";
const freezeResult = await wallet.freezeTokens(targetAddress);

console.log("Frozen outputs:", freezeResult.impactedOutputIds);
console.log("Frozen amount:", freezeResult.impactedTokenAmount);

// Later, unfreeze the same address
const unfreezeResult = await wallet.unfreezeTokens(targetAddress);
console.log("Unfrozen successfully:", unfreezeResult);

Burn Tokens

The burnTokens function permanently removes tokens from circulation, reducing total supply. Burned tokens are sent to an inaccessible dead address, making them unrecoverable. burnTokens(tokenAmount) Burns existing tokens, permanently removing them from circulation.

const transactionId = await wallet.burnTokens(BigInt(100000));
console.log("Spark Transaction ID:", transactionId);

Show Parameters

tokenAmount

bigint

required

The amount to burn in base units (e.g., 100000n for 0.100000 tokens with 6 decimals)

Show Returns

transactionId

string

required

Spark transaction ID of the burn operation

What You Need to Know

Irreversible Action

Burning is irreversible. Tokens cannot be recovered

Only Own Tokens

You can only burn tokens from your own wallet

Base Units Required

Amount must be specified in base units

Reduces Supply

Burned tokens permanently reduce total supply

Burning Examples

Burn Excess Supply

// Burn excess tokens to reduce supply
const excessAmount = BigInt(500000000); // 500,000.000000 tokens
const burnTx = await wallet.burnTokens(excessAmount);
console.log("Excess tokens burned:", burnTx);

Deflationary Token

// Implement deflationary mechanics
const burnAmount = BigInt(1000000); // 1,000,000.000000 tokens
const burnTx = await wallet.burnTokens(burnAmount);
console.log("Deflationary burn completed:", burnTx);

Transfer Tokens

Transfer tokens to other Spark addresses for distribution or trading. transferTokens(params) Transfers tokens to another Spark Address.

const transferTx = await wallet.transferTokens({
  tokenIdentifier: "btkn1...",
  tokenAmount: BigInt(1000000),
  receiverSparkAddress: "spark1..."
});
console.log("Transfer transaction ID:", transferTx);

Show Parameters

tokenIdentifier

string

required

Bech32m token identifier (e.g., btkn1…) of the token to transfer

tokenAmount

bigint

required

Amount of tokens to transfer

receiverSparkAddress

string

required

Recipient’s Spark Address

selectedOutputs

OutputWithPreviousTransactionData[]

(Optional) Specific outputs to use for transfer

Show Returns

transferTx

string

required

Transaction ID of the token transfer

Batch Transfer Tokens

batchTransferTokens(params) Transfers tokens to multiple recipients in a single transaction.

const batchTx = await wallet.batchTransferTokens({
  tokenIdentifier: "btkn1...",
  transfers: [
    { tokenAmount: BigInt(1000000), receiverSparkAddress: "spark1..." },
    { tokenAmount: BigInt(2000000), receiverSparkAddress: "spark1..." }
  ]
});
console.log("Batch transfer transaction ID:", batchTx);

Show Parameters

tokenIdentifier

string

required

Bech32m token identifier of the token to transfer

transfers

object[]

required

Array of transfer objects containing recipient addresses and amounts

selectedOutputs

OutputWithPreviousTransactionData[]

(Optional) Specific outputs to use for transfer

Show Returns

batchTx

string

required

Transaction ID of the batch transfer

Monitor Token Activity

Get Token Balance

getIssuerTokenBalance(sparkAddress?) Gets the token balance of a specific wallet or the issuer wallet.

// Get issuer's token balance
const issuerBalance = await wallet.getIssuerTokenBalance();
console.log("Issuer balance:", issuerBalance.balance);

// Get balance for specific address
const userBalance = await wallet.getIssuerTokenBalance("spark1...");
console.log("User balance:", userBalance.balance);

Show Parameters

sparkAddress

string

(Optional) Spark Address to check balance for. If not provided, returns issuer’s balance

Show Returns

balance

object

required

Object containing balance and Bech32m token identifier

balance

bigint

required

Current token balance in base units

bech32mTokenIdentifier

string

required

Bech32m token identifier for the token

Query Token Transactions

queryTokenTransactions(params) Retrieves token transactions from the network with flexible filtering options.

const transactions = await wallet.queryTokenTransactions({
  ownerPublicKeys: ["spark1..."],
  tokenIdentifiers: ["btkn1..."],
  issuerPublicKeys: ["spark1..."]
});
console.log("Token transactions:", transactions);

Show Parameters

ownerPublicKeys

string[]

(Optional) Array of owner public keys to filter by

issuerPublicKeys

string[]

(Optional) Array of issuer public keys to filter by

tokenTransactionHashes

string[]

(Optional) Array of token transaction hashes to filter by

tokenIdentifiers

string[]

(Optional) Array of Bech32m token identifiers to filter by

outputIds

string[]

(Optional) Array of output IDs to filter by

Show Returns

transactions

TokenTransactionWithStatus[]

required

Array of token transactions with status information

Token Management Best Practices

Supply Management

Plan Your Supply: Decide on initial supply and future minting strategy before creating your token
Monitor Max Supply: Keep track of your token’s max supply to avoid minting beyond limits
Consider Deflation: Implement burning mechanisms to create deflationary pressure if desired

Freeze Management

Use Sparingly: Only freeze addresses when absolutely necessary for compliance or security
Document Reasons: Keep records of why addresses were frozen
Regular Review: Periodically review frozen addresses and unfreeze when appropriate

Transfer Management

Verify Addresses: Always double-check recipient addresses before transferring
Use Batch Transfers: For multiple recipients, use batch transfers to save on fees
Monitor Transactions: Track all transfers for accounting and compliance purposes

Security Considerations

Protect Private Keys: Keep your issuer wallet’s private keys secure
Test on Regtest: Always test token management operations on regtest first
Backup Metadata: Keep records of your token’s metadata and configuration

Complete Example

import { IssuerSparkWallet } from "@buildonspark/issuer-sdk";

async function manageMyToken() {
  try {
    // 1. Initialize issuer wallet
    const { wallet } = await IssuerSparkWallet.initialize({
      options: { network: "REGTEST" }
    });

    console.log("Issuer wallet initialized for token management");

    // 2. Get token metadata
    const metadata = await wallet.getIssuerTokenMetadata();
    console.log("Token:", metadata.tokenName, "(", metadata.tokenSymbol, ")");

    // 3. Mint initial supply
    const initialSupply = BigInt(1000000000000); // 1,000,000.000000 tokens
    const mintTx = await wallet.mintTokens(initialSupply);
    console.log("Initial supply minted:", mintTx);

    // 4. Check balance
    const balance = await wallet.getIssuerTokenBalance();
    console.log("Current balance:", balance.balance, "base units");

    // 5. Transfer tokens to users
    const transferTx = await wallet.transferTokens({
      tokenIdentifier: metadata.bech32mTokenIdentifier,
      tokenAmount: BigInt(100000000), // 100.000000 tokens
      receiverSparkAddress: "spark1..." // Replace with actual address
    });
    console.log("Tokens transferred:", transferTx);

    // 6. Freeze an address (if token is freezable)
    if (metadata.isFreezable) {
      const freezeResult = await wallet.freezeTokens("spark1...");
      console.log("Address frozen:", freezeResult);
    }

    // 7. Burn some tokens
    const burnAmount = BigInt(10000000); // 10.000000 tokens
    const burnTx = await wallet.burnTokens(burnAmount);
    console.log("Tokens burned:", burnTx);

    // 8. Query recent transactions
    const transactions = await wallet.queryTokenTransactions({
      issuerPublicKeys: [metadata.tokenPublicKey]
    });
    console.log("Recent transactions:", transactions.length);

  } catch (error) {
    console.error("Token management error:", error);
  }
}

manageMyToken().catch(console.error);

Introduction

Installation

Issuer

Token Data

Tools

​Token Management Overview

Mint Tokens

Freeze/Unfreeze

Burn Tokens

​Mint Tokens

​What You Need to Know

Only Creator Can Mint

Minted to Creator

Base Units Required

Instant Transaction

​Minting Examples

​Initial Supply Minting

​Ongoing Minting

​Where Are Tokens Minted?

​Freeze & Unfreeze Tokens

​Freeze Tokens

​Unfreeze Tokens

​Freeze Requirements

Token Must Be Freezable

Only Issuer Can Freeze

Issuer Cannot Be Frozen

Instant Effect

​Freeze Examples

​Burn Tokens

​What You Need to Know

Irreversible Action

Only Own Tokens

Base Units Required

Reduces Supply

​Burning Examples

​Burn Excess Supply

​Deflationary Token

​Transfer Tokens

​Batch Transfer Tokens

​Monitor Token Activity

​Get Token Balance

​Query Token Transactions

​Token Management Best Practices

​Supply Management

​Freeze Management

​Transfer Management

​Security Considerations

​Complete Example

Token Management Overview

Mint Tokens

What You Need to Know

Minting Examples

Initial Supply Minting

Ongoing Minting

Where Are Tokens Minted?

Freeze & Unfreeze Tokens

Freeze Tokens

Unfreeze Tokens

Freeze Requirements

Freeze Examples

Burn Tokens

What You Need to Know

Burning Examples

Burn Excess Supply

Deflationary Token

Transfer Tokens

Batch Transfer Tokens

Monitor Token Activity

Get Token Balance

Query Token Transactions

Token Management Best Practices

Supply Management

Freeze Management

Transfer Management

Security Considerations

Complete Example