Skip to main content
Gets the current balance of the SparkWallet, including Bitcoin balance and token balances.

​
Method Signature

async getBalance(): Promise<{
  /** @deprecated Use satsBalance.available instead */
  balance: bigint;
  satsBalance: {
    available: bigint;
    owned: bigint;
    incoming: bigint;
  };
  tokenBalances: TokenBalanceMap;
}>

// TokenBalanceMap = Map<Bech32mTokenIdentifier, { ownedBalance: bigint, availableToSendBalance: bigint, tokenMetadata: UserTokenMetadata }>

interface UserTokenMetadata {
  rawTokenIdentifier: Uint8Array; // Binary token identifier used to encode the bech32m identifier
  tokenPublicKey: string;         // Issuer's public key
  tokenName: string;
  tokenTicker: string;
  decimals: number;               // Number of decimal places
  maxSupply: bigint;
  extraMetadata?: Uint8Array;     // Arbitrary bytes set by the issuer
}

​
Returns

​
balance
bigint
required
Deprecated — Use satsBalance.available instead.
The wallet’s immediately spendable balance in satoshis. Kept for backwards compatibility.
​
satsBalance
object
required
Breakdown of the sats balance by status:
  • available: Immediately spendable satoshis
  • owned: All satoshis owned (available + locked in outgoing transfers/swaps)
  • incoming: Pending inbound transfers not yet claimed
​
tokenBalances
TokenBalanceMap
required
Map of Bech32m token identifiers to token balance and metadata objects. Each token balance contains:
  • ownedBalance: Total tokens owned (including those pending in outbound transfers)
  • availableToSendBalance: Tokens available to send (excludes pending outbound transfers)
  • tokenMetadata: Token metadata including name, ticker, decimals, etc.
The ownedBalance represents all tokens you own, while availableToSendBalance excludes tokens that are locked in pending outbound transfers. Use availableToSendBalance to determine how many tokens can be sent.

​
Example

const { satsBalance, tokenBalances } = await wallet.getBalance();
console.log("Available:", satsBalance.available);
console.log("Owned:", satsBalance.owned);
console.log("Incoming:", satsBalance.incoming);

// Iterate over token balances
for (const [tokenId, info] of tokenBalances) {
  console.log(`Token ${tokenId}:`);
  console.log(`  Owned: ${info.ownedBalance}`);
  console.log(`  Available to send: ${info.availableToSendBalance}`);
  console.log(`  Name: ${info.tokenMetadata.tokenName}`);
  console.log(`  Ticker: ${info.tokenMetadata.tokenTicker}`);
  console.log(`  Decimals: ${info.tokenMetadata.decimals}`);

  // Check for extra metadata
  if (info.tokenMetadata.extraMetadata) {
    console.log(`  Extra metadata: ${info.tokenMetadata.extraMetadata.length} bytes`);
  }
}