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

Show Returns

balance

bigint

required

The wallet’s current balance in satoshis

tokenBalances

Map

required

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

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

limit

number

Maximum number of transfers to return (default: 20)

offset

number

Offset for pagination (default: 0)

createdAfter

Date

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

createdBefore

Date

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

Show Returns

transfers

WalletTransfer[]

required

Array of transfer objects containing transfer details

offset

number

required

The offset used for this request

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

Show Parameters

event

string

required

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

listener

Function

required

The callback function to execute when the event is emitted

Show Returns

this

SparkWallet

required

The SparkWallet instance for method chaining

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

Show Parameters

event

string

required

The event name to listen for

listener

Function

required

The callback function to execute when the event is emitted

Show Returns

this

SparkWallet

required

The SparkWallet instance for method chaining

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

Show Parameters

event

string

required

The event name to remove the listener from

listener

Function

required

The specific callback function to remove

Show Returns

this

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

​Check Wallet Balance

​View Transfer History

​Real-time Event Monitoring

​Available Events

​Available Events

​Use Sparkscan Explorer

​Example: Complete Balance Monitoring

Check Wallet Balance

View Transfer History

Real-time Event Monitoring

Available Events

Available Events

Use Sparkscan Explorer

Example: Complete Balance Monitoring