getTokenBalance

Get token balances and metadata for a Spark address.

Gets token balances with metadata for a Spark address. Automatically paginates through all token outputs.

Method Signature

async getTokenBalance(
  sparkAddress: string,
  tokenIdentifiers?: string[],
): Promise<TokenBalanceMap>

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

interface UserTokenMetadata {
  rawTokenIdentifier: Uint8Array;
  tokenPublicKey: string;
  tokenName: string;
  tokenTicker: string;
  decimals: number;
  maxSupply: bigint;
  extraMetadata?: Uint8Array;
}

Parameters

sparkAddress · string · required

The Spark address to query.

tokenIdentifiers · string[]

Optional array of Bech32m token identifiers to filter by. If omitted, returns all tokens.

Returns

tokenBalances · TokenBalanceMap · required

Map of token identifiers to balance and metadata objects. Each entry contains:

• ownedBalance: Total tokens owned (including pending outbound)
• availableToSendBalance: Tokens available to send
• tokenMetadata: Name, ticker, decimals, issuer key, max supply

Example

// All tokens
const balances = await client.getTokenBalance("sp1...");
for (const [tokenId, info] of balances) {
  console.log(`${info.tokenMetadata.tokenTicker}: ${info.availableToSendBalance}`);
}

// Specific tokens
const filtered = await client.getTokenBalance("sp1...", ["btkn1..."]);