Skip to main content
Query balances, view transfer history, and monitor wallet activity in real-time.
Balances & Activity

​
Check Wallet Balance

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

​
View Transfer History

Track all incoming and outgoing transfers for your wallet with pagination support. getTransfers(limit?, offset?) Gets all transfers for the wallet with optional pagination.
getTransfers() includes Spark transfers, Lightning sends/receives, and cooperative exits. For token transaction details (e.g., sender address), use queryTokenTransactions().
// Get first 20 transfers
const transfers = await wallet.getTransfers();
console.log("Transfers:", transfers.transfers);

// Get next 10 transfers with pagination
const nextTransfers = await wallet.getTransfers(10, 20);
console.log("Next page:", nextTransfers.transfers);

// Get transfers from the last 24 hours
const yesterday = new Date(Date.now() - 24 * 60 * 60 * 1000);
const recentTransfers = await wallet.getTransfers(50, 0, yesterday);

​
Real-time Event Monitoring

Monitor wallet activity in real-time using EventEmitter methods for instant updates. on(event, listener) Adds a listener for the specified event to monitor wallet activity. 
// Listen for incoming transfer claims
wallet.on("transfer:claimed", (transferId, updatedBalance) => {
  console.log(`Transfer ${transferId} claimed. New balance: ${updatedBalance}`);
});

// Listen for deposit confirmations (after 3 L1 confirmations)
wallet.on("deposit:confirmed", (depositId, updatedBalance) => {
  console.log(`Deposit ${depositId} confirmed. New balance: ${updatedBalance}`);
});
once(event, listener) Adds a one-time listener for the specified event. 
// Listen for a single incoming transfer
wallet.once("transfer:claimed", (transferId, updatedBalance) => {
  console.log(`Transfer ${transferId} claimed! New balance: ${updatedBalance}`);
});
off(event, listener) Removes the specified listener from the specified event. 
// Remove a specific listener
const handleTransfer = (transferId) => console.log(`Transfer: ${transferId}`);
wallet.on("transfer:claimed", handleTransfer);

// Later, remove the listener
wallet.off("transfer:claimed", handleTransfer);

​
Available Events

Spark wallets emit various events for different types of activity:

​
Available Events

EventDescription
transfer:claimedEmitted when an incoming transfer is claimed
deposit:confirmedEmitted when a pending L1 deposit becomes spendable
stream:connectedEmitted when the event stream connects
stream:disconnectedEmitted when the stream disconnects
stream:reconnectingEmitted when attempting to reconnect
Events only fire for incoming funds. For outgoing operations (Lightning sends, withdrawals), poll the status using getLightningSendRequest() or getCoopExitRequest().

​
Use Sparkscan Explorer

Monitor your wallet activity using the Sparkscan block explorer for a visual interface.
Sparkscan provides a web interface to view your wallet’s transaction history, balance, and activity without needing to implement the API calls yourself.

​
Example: Complete Balance Monitoring

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

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

  // Get initial balance
  const balance = await wallet.getBalance();
  console.log("Initial balance:", balance.balance, "sats");

  // Set up event listeners
  wallet.on("transfer:claimed", (transferId, newBalance) => {
    console.log(`Transfer ${transferId} claimed. New balance: ${newBalance} sats`);
  });

  // Get recent transfers
  const transfers = await wallet.getTransfers(10);
  console.log("Recent transfers:", transfers.transfers);

  return wallet;
}