Skip to main content
Send tokens to any Spark address with single or batch transfers.
Transfer Tokens

​
Transfer Tokens

Send tokens to another Spark wallet using the token identifier and amount. transferTokens(params) Transfers tokens to another user on the Spark network. 
const transferResult = await wallet.transferTokens({
  tokenIdentifier: "btkn1p...", // Bech32m token identifier
  tokenAmount: BigInt(1000),    // Amount of tokens to transfer
  receiverSparkAddress: "spark1p...", // Recipient's Spark address
});

console.log("Transfer successful:", transferResult);

​
Get Token Balances

Before transferring tokens, check what tokens you own and their balances using getBalance(). 
const { balance, tokenBalances } = await wallet.getBalance();
console.log("Sats balance:", balance);

// Iterate over token balances
for (const [tokenId, tokenData] of tokenBalances) {
  console.log(`Token ${tokenId}:`);
  console.log("  Balance:", tokenData.balance);
  console.log("  Name:", tokenData.tokenMetadata.tokenName);
  console.log("  Ticker:", tokenData.tokenMetadata.tokenTicker);
}

// Check balance of a specific token
const specificToken = tokenBalances.get("btkn1...");
if (specificToken) {
  console.log("Token balance:", specificToken.balance);
}

​
Error Handling

Proper error handling is essential when transferring tokens to ensure a smooth user experience. 
async function transferTokensSafely(params) {
  try {
    // Check if you have enough tokens
    const balance = await wallet.getBalance();
    const tokenBalance = balance.tokenBalances.get(params.tokenIdentifier);
    
    if (!tokenBalance || tokenBalance.balance < params.tokenAmount) {
      throw new Error("Insufficient token balance");
    }

    // Attempt the transfer
    const result = await wallet.transferTokens(params);
    console.log("Transfer successful:", result);
    return result;
    
  } catch (error) {
    console.error("Transfer failed:", error.message);
    
    // Handle specific error types
    if (error.message.includes("Insufficient")) {
      console.log("Please check your token balance");
    } else if (error.message.includes("Invalid address")) {
      console.log("Please verify the recipient address");
    } else {
      console.log("Transfer failed. Please try again.");
    }
    
    throw error;
  }
}

​
Example: Complete Token Transfer Flow

import { SparkWallet } from "@buildonspark/spark-sdk";

async function completeTokenTransfer() {
  const { wallet } = await SparkWallet.initialize({
    options: { network: "REGTEST" }
  });

  try {
    // 1. Check current balance and token holdings
    const { balance, tokenBalances } = await wallet.getBalance();
    console.log("Current balance:", balance, "sats");
    console.log("Token balances:", tokenBalances);

    // 2. Set up event listeners
    wallet.on("transfer:claimed", (transferId, newBalance) => {
      console.log(`Token transfer ${transferId} claimed!`);
    });

    // 3. Transfer tokens
    const transferResult = await wallet.transferTokens({
      tokenIdentifier: "btkn1p...", // Replace with actual token ID
      tokenAmount: BigInt(100),     // Transfer 100 tokens
      receiverSparkAddress: "spark1p..." // Replace with recipient address
    });

    console.log("Transfer initiated:", transferResult);

  } catch (error) {
    console.error("Transfer failed:", error);
  }
}