Skip to main content
Learn how to transfer tokens between Spark wallets. This guide covers token transfers, error handling, and best practices for sending tokens on the Spark network.
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 Information

Before transferring tokens, you may want to check what tokens you own and their balances. getTokenInfo() Gets information about tokens owned by the wallet. 
const tokenInfo = await wallet.getTokenInfo();
console.log("Owned tokens:", tokenInfo);

// Example: Check balance of a specific token
const tokenBalance = await wallet.getBalance();
const specificToken = tokenBalance.tokenBalances.get("tokenPublicKey");
if (specificToken) {
  console.log("Token balance:", specificToken.balance);
  console.log("Token identifier:", specificToken.bech32mTokenIdentifier);
}

​
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;
  }
}

​
Best Practices

  • Verify addresses - Always validate recipient Spark addresses before sending
  • Check balances - Ensure you have sufficient token balance before transferring
  • Handle errors - Implement proper error handling for failed transfers
  • Use BigInt - Token amounts must be BigInt values, not regular numbers
  • Test first - Use regtest network for testing token transfers
  • Monitor events - Listen for transfer events to track transaction status

​
Example: Complete Token Transfer Flow

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

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

  try {
    // 1. Get token information
    const tokenInfo = await wallet.getTokenInfo();
    console.log("Available tokens:", tokenInfo);

    // 2. Check current balance
    const balance = await wallet.getBalance();
    console.log("Current balance:", balance.balance, "sats");
    console.log("Token balances:", balance.tokenBalances);

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

    // 4. 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);
  }
}