Balances & Activity

Query balances, view transfer history, and monitor wallet activity in real-time.

Check Wallet Balance

Get your current Bitcoin balance and token holdings in your Spark wallet. Gets the current balance of the wallet, including Bitcoin balance and token balances.

const balance = await wallet.getBalance();
console.log("Available:", balance.satsBalance.available, "sats");
console.log("Owned:", balance.satsBalance.owned, "sats");
console.log("Incoming:", balance.satsBalance.incoming, "sats");
console.log("Token Balances:", balance.tokenBalances);

Show Returns

object

required

Bitcoin balances in satoshis: available (spendable), owned (includes funds locked in outgoing transfers and swaps), and incoming (pending inbound transfers not yet claimed).

Map

required

Map of Bech32m token identifiers to token balance objects. Each balance includes ownedBalance (total owned), availableToSendBalance (excludes pending transfers), and token metadata.

Received does not mean spendable

An incoming Bitcoin transfer must be claimed by the receiving wallet before it becomes owned and available. A payment to an offline receiver can appear in getPendingTransfers() while both read-only getAvailableBalance() and getOwnedBalance() remain zero. The read-only client cannot claim it. An initialized SparkWallet claims incoming transfers automatically. Use satsBalance.incoming for pending funds known to the wallet, and transfer:claimed followed by a balance refresh to update spendable funds. A Lightning receive request reaching TRANSFER_COMPLETED is not a substitute for checking the receiving wallet’s balance. owned is not “available plus every incoming payment.” Show pending receipts separately, and use available when deciding whether a payment can be sent.

View Transfer History

Track all incoming and outgoing transfers for your wallet with pagination support. 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 queryTokenTransactionsWithFilters().

// 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);

Show Parameters

number

Maximum number of transfers to return (default: 20)

number

Offset for pagination (default: 0)

Date

Only return transfers created after this date (mutually exclusive with createdBefore)

Date

Only return transfers created before this date (mutually exclusive with createdAfter)

Show Returns

WalletTransfer[]

required

Array of transfer objects containing transfer details

number

required

The offset used for this request

For newest-first token history, use the cursor pagination example.

Real-time Event Monitoring

Monitor wallet activity in real-time using EventEmitter methods for instant updates. 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}`);
});

Show Parameters

string

required

The event name to listen for (e.g., “transfer:claimed”, “deposit:confirmed”)

Function

required

The callback function to execute when the event is emitted

Show Returns

SparkWallet

required

The SparkWallet instance for method chaining

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}`);
});

Show Parameters

string

required

The event name to listen for

Function

required

The callback function to execute when the event is emitted

Show Returns

SparkWallet

required

The SparkWallet instance for method chaining

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);

Show Parameters

string

required

The event name to remove the listener from

Function

required

The specific callback function to remove

Show Returns

SparkWallet

required

The SparkWallet instance for method chaining

Available Events

Spark wallets emit various events for different types of activity:

Available Events

Event	Description
`transfer:claimed`	Emitted when an incoming transfer is claimed
`deposit:confirmed`	Emitted when a pending L1 deposit becomes spendable
`stream:connected`	Emitted when the event stream connects
`stream:disconnected`	Emitted when the stream disconnects
`stream:reconnecting`	Emitted 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.satsBalance.available, "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;
}

Introduction

Installation

Wallet

Transfers

Deposits

Withdrawals

Fees

Spark Signer Interface

Tools

Balances & Activity

Check Wallet Balance

Received does not mean spendable

View Transfer History

Real-time Event Monitoring

Available Events

Available Events

Use Sparkscan Explorer

Example: Complete Balance Monitoring

​Check Wallet Balance

​Received does not mean spendable

​View Transfer History

​Real-time Event Monitoring

​Available Events

​Available Events

​Use Sparkscan Explorer

​Example: Complete Balance Monitoring

Check Wallet Balance

Received does not mean spendable

View Transfer History

Real-time Event Monitoring

Available Events

Available Events

Use Sparkscan Explorer

Example: Complete Balance Monitoring