Skip to main content
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..."]);