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

​
Method Signature

async getBalance(): Promise<{
  balance: 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
The wallet’s current balance in satoshis as a bigint. Use Number(balance) for display or arithmetic with regular numbers.
​
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 { balance, tokenBalances } = await wallet.getBalance();
console.log("Balance:", balance);

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