Skip to main content
Learn how to check token balances on Spark. This guide covers getting issuer token balances and general wallet balances.
Token Balances

​
Get Issuer Token Balance

Check the token balance for a specific Spark address or your own issuer wallet. getIssuerTokenBalance(sparkAddress?) Gets the token balance of the wallet. 
// Get issuer's own token balance
const issuerBalance = await wallet.getIssuerTokenBalance();
console.log("Issuer balance:", issuerBalance.balance);

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

​
Balance Examples

​
Check Issuer Balance

// Get your own token balance
const myBalance = await wallet.getIssuerTokenBalance();
console.log("My token balance:", myBalance.balance, "base units");
console.log("Token ID:", myBalance.bech32mTokenIdentifier);

​
Check User Balance

// Get token balance for a specific user
const userAddress = "spark1s2h8nvdh4h7h43tcwjdcysf7v0fprz5uh6vshs4n0tvhgzz2xgcqpg8yqv7";
const userBalance = await wallet.getIssuerTokenBalance(userAddress);
console.log("User balance:", userBalance.balance, "base units");

​
Convert Base Units to Tokens

// Get metadata to understand decimal precision
const metadata = await wallet.getIssuerTokenMetadata();
const decimals = metadata.tokenDecimals;

// Get balance in base units
const balance = await wallet.getIssuerTokenBalance();
const baseUnits = balance.balance;

// Convert to display units
const displayAmount = Number(baseUnits) / (10 ** decimals);
console.log(`Balance: ${displayAmount} ${metadata.tokenSymbol}`);

​
Get Wallet Balance

Get the complete balance of your wallet including Bitcoin and all token balances. getBalance() Gets the current balance of the wallet. 
const balance = await wallet.getBalance();
console.log("Bitcoin balance:", balance.balance, "sats");
console.log("Token balances:", balance.tokenBalances);

​
Wallet Balance Examples

​
Basic Balance Check

const walletBalance = await wallet.getBalance();
console.log("Bitcoin Balance:", walletBalance.balance, "sats");

// Check if wallet has any tokens
if (walletBalance.tokenBalances.size > 0) {
  console.log("Token Balances:");
  walletBalance.tokenBalances.forEach((tokenData, tokenPublicKey) => {
    console.log(`- ${tokenData.tokenInfo.tokenName} (${tokenData.tokenInfo.tokenSymbol}): ${tokenData.balance} base units`);
  });
} else {
  console.log("No tokens in wallet");
}

​
Display All Token Balances

const walletBalance = await wallet.getBalance();

console.log("=== Wallet Balance Summary ===");
console.log("Bitcoin:", walletBalance.balance, "sats");

walletBalance.tokenBalances.forEach((tokenData, tokenPublicKey) => {
  const tokenInfo = tokenData.tokenInfo;
  const balance = tokenData.balance;
  const decimals = tokenInfo.tokenDecimals;
  
  // Convert to display units
  const displayAmount = Number(balance) / (10 ** decimals);
  
  console.log(`${tokenInfo.tokenName} (${tokenInfo.tokenSymbol}): ${displayAmount} tokens`);
  console.log(`  - Token ID: ${tokenData.bech32mTokenIdentifier}`);
  console.log(`  - Base Units: ${balance}`);
});

​
Check Specific Token Balance

const walletBalance = await wallet.getBalance();
const targetTokenId = "btkn1..."; // Your token identifier

// Find your token in the balance map
let myTokenBalance = null;
walletBalance.tokenBalances.forEach((tokenData, tokenPublicKey) => {
  if (tokenData.bech32mTokenIdentifier === targetTokenId) {
    myTokenBalance = tokenData;
  }
});

if (myTokenBalance) {
  console.log("My Token Balance:", myTokenBalance.balance, "base units");
  console.log("Token Info:", myTokenBalance.tokenInfo);
} else {
  console.log("Token not found in wallet");
}

​
Balance Monitoring

Set up real-time monitoring for balance changes.

​
Event-Based Monitoring

// Listen for transfer events that affect balance
wallet.on("transfer:claimed", (transferId, updatedBalance) => {
  console.log(`Transfer ${transferId} claimed. New balance: ${updatedBalance} sats`);
});

// Check token balances after events
wallet.on("transfer:claimed", async () => {
  const balance = await wallet.getBalance();
  console.log("Updated token balances:", balance.tokenBalances);
});

​
Periodic Balance Checks

// Check balances periodically
async function checkBalances() {
  try {
    // Check issuer token balance
    const issuerBalance = await wallet.getIssuerTokenBalance();
    console.log("Issuer token balance:", issuerBalance.balance);
    
    // Check complete wallet balance
    const walletBalance = await wallet.getBalance();
    console.log("Total Bitcoin balance:", walletBalance.balance);
    console.log("Number of tokens:", walletBalance.tokenBalances.size);
    
  } catch (error) {
    console.error("Error checking balances:", error);
  }
}

// Check every 30 seconds
setInterval(checkBalances, 30000);

​
Best Practices

​
Balance Management

  • Cache Balances: Store balance data locally to avoid repeated API calls
  • Handle BigInt: Always use BigInt for balance calculations to prevent precision loss
  • Convert for Display: Convert base units to display units using token decimals
  • Monitor Changes: Use event listeners to track balance changes in real-time

​
Error Handling

  • Network Issues: Implement retry logic for balance queries
  • Invalid Addresses: Validate Spark addresses before checking balances
  • Missing Tokens: Handle cases where tokens don’t exist in wallet

​
Performance

  • Batch Checks: When checking multiple addresses, consider batching requests
  • Selective Updates: Only check balances when necessary to reduce API calls
  • Local Storage: Cache balance data for better user experience

​
Complete Example

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

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

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

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

    // 3. Check issuer's own token balance
    const issuerBalance = await wallet.getIssuerTokenBalance();
    const issuerDisplayAmount = Number(issuerBalance.balance) / (10 ** metadata.tokenDecimals);
    console.log(`Issuer balance: ${issuerDisplayAmount} ${metadata.tokenSymbol}`);

    // 4. Check complete wallet balance
    const walletBalance = await wallet.getBalance();
    console.log("Bitcoin balance:", walletBalance.balance, "sats");
    console.log("Number of tokens in wallet:", walletBalance.tokenBalances.size);

    // 5. Display all token balances
    walletBalance.tokenBalances.forEach((tokenData, tokenPublicKey) => {
      const displayAmount = Number(tokenData.balance) / (10 ** tokenData.tokenInfo.tokenDecimals);
      console.log(`${tokenData.tokenInfo.tokenName}: ${displayAmount} tokens`);
    });

    // 6. Check balance for a specific address (if provided)
    const userAddress = "spark1..."; // Replace with actual address
    const userBalance = await wallet.getIssuerTokenBalance(userAddress);
    const userDisplayAmount = Number(userBalance.balance) / (10 ** metadata.tokenDecimals);
    console.log(`User balance: ${userDisplayAmount} ${metadata.tokenSymbol}`);

    // 7. Set up balance monitoring
    wallet.on("transfer:claimed", async (transferId, updatedBalance) => {
      console.log(`Transfer ${transferId} claimed. New Bitcoin balance: ${updatedBalance} sats`);
      
      // Refresh token balances
      const newBalance = await wallet.getBalance();
      console.log("Updated token balances:", newBalance.tokenBalances.size, "tokens");
    });

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

demonstrateTokenBalances().catch(console.error);