getCachedBalance

Get wallet balance from the in-memory cache without network calls.

Returns the wallet balance from the in-memory cache without making network calls for sats. The cache is kept up-to-date by the event stream (deposits, transfers, swaps). For guaranteed-fresh data, use getBalance() instead.

Method Signature

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

Returns

balance · bigint · required

satsBalance · object · required

Breakdown of the sats balance by status (read from cache, no network call):

• 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. Token metadata may require a network call if not yet cached.

getCachedBalance() reads sats data from the event-driven in-memory cache — no network call is made for sats. Use this for instant balance reads (e.g., in a UI). For a guaranteed-fresh balance, call getBalance().

Example

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