Skip to main content
Learn how to retrieve token metadata on Spark. This guide covers getting token information and identifiers.
Token Metadata

​
Metadata Overview

Token metadata provides essential information about your token including its name, symbol, decimals, supply limits, and unique identifiers.

Token Information

Get complete token metadata including name, symbol, and configuration

Token Identifier

Retrieve the Bech32m token identifier for transfers and queries

​
Get Token Metadata

Retrieve comprehensive information about your token using the getIssuerTokenMetadata() method. getIssuerTokenMetadata() Gets the metadata about the token associated with this issuer wallet. 
const metadata = await wallet.getIssuerTokenMetadata();
console.log("Token Name:", metadata.tokenName);
console.log("Token Symbol:", metadata.tokenSymbol);
console.log("Token Decimals:", metadata.tokenDecimals);
console.log("Max Supply:", metadata.maxSupply);
console.log("Is Freezable:", metadata.isFreezable);
console.log("Token Public Key:", metadata.tokenPublicKey);
console.log("Token Identifier:", metadata.bech32mTokenIdentifier);

​
Metadata Examples

​
Basic Token Information

const metadata = await wallet.getIssuerTokenMetadata();

console.log("=== Token Information ===");
console.log("Name:", metadata.tokenName);
console.log("Symbol:", metadata.tokenSymbol);
console.log("Decimals:", metadata.tokenDecimals);
console.log("Max Supply:", metadata.maxSupply.toString());
console.log("Freezable:", metadata.isFreezable ? "Yes" : "No");
console.log("Token ID:", metadata.bech32mTokenIdentifier);

​
Token Configuration Check

const metadata = await wallet.getIssuerTokenMetadata();

// Check if token has unlimited supply
if (metadata.maxSupply === BigInt(0)) {
  console.log("Token has unlimited supply");
} else {
  console.log("Token max supply:", metadata.maxSupply.toString());
}

// Check if token supports freezing
if (metadata.isFreezable) {
  console.log("Token supports freezing/unfreezing");
} else {
  console.log("Token does not support freezing");
}

// Display token precision
console.log(`Token precision: ${metadata.tokenDecimals} decimal places`);
console.log(`1 token = ${10 ** metadata.tokenDecimals} base units`);

​
Get Token Identifier

Retrieve the Bech32m token identifier for use in transfers and queries. getIssuerTokenIdentifier() Gets the Bech32m token identifier for the issuer’s token. 
const tokenIdentifier = await wallet.getIssuerTokenIdentifier();
console.log("Token Identifier:", tokenIdentifier);

​
Identifier Usage Examples

​
For Token Transfers

// Get token identifier for transfers
const tokenIdentifier = await wallet.getIssuerTokenIdentifier();

// Use in single transfer
const transferTx = await wallet.transferTokens({
  tokenIdentifier: tokenIdentifier,
  tokenAmount: BigInt(1000000),
  receiverSparkAddress: "spark1..."
});

// Use in batch transfer
const batchTx = await wallet.batchTransferTokens({
  tokenIdentifier: tokenIdentifier,
  transfers: [
    { tokenAmount: BigInt(500000), receiverSparkAddress: "spark1..." },
    { tokenAmount: BigInt(500000), receiverSparkAddress: "spark1..." }
  ]
});

​
For Token Queries

// Get token identifier for querying transactions
const tokenIdentifier = await wallet.getIssuerTokenIdentifier();

// Query transactions for this specific token
const transactions = await wallet.queryTokenTransactions({
  tokenIdentifiers: [tokenIdentifier]
});

console.log(`Found ${transactions.length} transactions for token ${tokenIdentifier}`);

​
Best Practices

​
Metadata Management

  • Cache Metadata: Store token metadata locally to avoid repeated API calls
  • Validate Identifiers: Always validate token identifiers before using them in transfers
  • Monitor Changes: Track metadata changes if your token configuration evolves

​
Error Handling

  • Handle Missing Data: Implement fallbacks for when metadata is unavailable
  • Validate Responses: Check that returned data matches expected formats
  • Retry Logic: Implement retry mechanisms for network-related failures

​
Complete Example

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

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

    console.log("Issuer wallet initialized for metadata queries");

    // 2. Get complete token metadata
    const metadata = await wallet.getIssuerTokenMetadata();
    console.log("=== Token Metadata ===");
    console.log("Name:", metadata.tokenName);
    console.log("Symbol:", metadata.tokenSymbol);
    console.log("Decimals:", metadata.tokenDecimals);
    console.log("Max Supply:", metadata.maxSupply.toString());
    console.log("Freezable:", metadata.isFreezable);
    console.log("Public Key:", metadata.tokenPublicKey);
    console.log("Token ID:", metadata.bech32mTokenIdentifier);

    // 3. Get token identifier for transfers
    const tokenIdentifier = await wallet.getIssuerTokenIdentifier();
    console.log("Token Identifier:", tokenIdentifier);

    // 4. Use token identifier in transfers
    const transferTx = await wallet.transferTokens({
      tokenIdentifier: tokenIdentifier,
      tokenAmount: BigInt(1000000),
      receiverSparkAddress: "spark1..."
    });
    console.log("Transfer completed:", transferTx);

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

demonstrateTokenMetadata().catch(console.error);