Asset Balances

← Back to Indexer Client

Description

This example demonstrates how to lookup all holders of an asset using the IndexerClient lookupAssetBalances() method.

Prerequisites

• LocalNet running (via algokit localnet start)

Run This Example

From the repository root:

cd examples
npm run example indexer_client/09-asset-balances.ts

Code

View source on GitHub

09-asset-balances.ts

/**
 * Example: Asset Balances
 *
 * This example demonstrates how to lookup all holders of an asset using
 * the IndexerClient lookupAssetBalances() method.
 *
 * Prerequisites:
 * - LocalNet running (via `algokit localnet start`)
 */

import {
  createAlgorandClient,
  createIndexerClient,
  createRandomAccount,
  printError,
  printHeader,
  printInfo,
  printStep,
  printSuccess,
  shortenAddress,
} from '../shared/utils.js';

async function main() {
  printHeader('Asset Balances Example');

  // Create clients
  const indexer = createIndexerClient();
  const algorand = createAlgorandClient();

  // =========================================================================
  // Step 1: Get a funded account and create additional accounts
  // =========================================================================
  printStep(1, 'Setting up accounts for demonstration');

  let creatorAddress: string;
  let holder1Address: string;
  let holder2Address: string;
  let holder3Address: string;

  try {
    // Get the dispenser account as the creator
    const dispenser = await algorand.account.dispenserFromEnvironment();
    creatorAddress = dispenser.addr.toString();
    printSuccess(`Creator account (dispenser): ${shortenAddress(creatorAddress)}`);

    // Create additional accounts to hold the asset
    const holder1 = await createRandomAccount(algorand);
    holder1Address = holder1.addr.toString();
    printSuccess(`Holder 1: ${shortenAddress(holder1Address)}`);

    const holder2 = await createRandomAccount(algorand);
    holder2Address = holder2.addr.toString();
    printSuccess(`Holder 2: ${shortenAddress(holder2Address)}`);

    const holder3 = await createRandomAccount(algorand);
    holder3Address = holder3.addr.toString();
    printSuccess(`Holder 3: ${shortenAddress(holder3Address)}`);
  } catch (error) {
    printError(
      `Failed to set up accounts: ${error instanceof Error ? error.message : String(error)}`,
    );
    printInfo('');
    printInfo('Make sure LocalNet is running: algokit localnet start');
    printInfo('If issues persist, try: algokit localnet reset');
    return;
  }

  // =========================================================================
  // Step 2: Create a test asset
  // =========================================================================
  printStep(2, 'Creating a test asset');

  let assetId: bigint;

  try {
    printInfo('Creating test asset: BalanceToken (BAL)...');
    const result = await algorand.send.assetCreate({
      sender: creatorAddress,
      total: 10_000_000n, // 10,000 units with 3 decimals
      decimals: 3,
      assetName: 'BalanceToken',
      unitName: 'BAL',
      url: 'https://example.com/balancetoken',
      defaultFrozen: false,
    });
    assetId = result.assetId;
    printSuccess(`Created BalanceToken with Asset ID: ${assetId}`);
  } catch (error) {
    printError(
      `Failed to create test asset: ${error instanceof Error ? error.message : String(error)}`,
    );
    printInfo('');
    printInfo('If LocalNet errors occur, try: algokit localnet reset');
    return;
  }

  // =========================================================================
  // Step 3: Distribute asset to multiple accounts
  // =========================================================================
  printStep(3, 'Distributing asset to multiple accounts');

  try {
    // Holder 1: Opt-in and receive 1000 BAL
    printInfo(`Opting in Holder 1 and sending 1000 BAL...`);
    await algorand.send.assetOptIn({
      sender: holder1Address,
      assetId,
    });
    await algorand.send.assetTransfer({
      sender: creatorAddress,
      receiver: holder1Address,
      assetId,
      amount: 1_000_000n, // 1000 BAL (with 3 decimals)
    });
    printSuccess(`Holder 1 received 1000 BAL`);

    // Holder 2: Opt-in and receive 500 BAL
    printInfo(`Opting in Holder 2 and sending 500 BAL...`);
    await algorand.send.assetOptIn({
      sender: holder2Address,
      assetId,
    });
    await algorand.send.assetTransfer({
      sender: creatorAddress,
      receiver: holder2Address,
      assetId,
      amount: 500_000n, // 500 BAL (with 3 decimals)
    });
    printSuccess(`Holder 2 received 500 BAL`);

    // Holder 3: Opt-in only (0 balance but still a holder)
    printInfo(`Opting in Holder 3 (no transfer, will have 0 balance)...`);
    await algorand.send.assetOptIn({
      sender: holder3Address,
      assetId,
    });
    printSuccess(`Holder 3 opted in with 0 balance`);

    printInfo('');
    printInfo('Distribution summary:');
    printInfo(`  - Creator: ~8500 BAL (remainder)`);
    printInfo(`  - Holder 1: 1000 BAL`);
    printInfo(`  - Holder 2: 500 BAL`);
    printInfo(`  - Holder 3: 0 BAL (opted-in only)`);
  } catch (error) {
    printError(
      `Failed to distribute asset: ${error instanceof Error ? error.message : String(error)}`,
    );
    printInfo('');
    printInfo('If LocalNet errors occur, try: algokit localnet reset');
    return;
  }

  // =========================================================================
  // Step 4: Basic lookupAssetBalances() - Get all holders
  // =========================================================================
  printStep(4, 'Looking up all asset holders with lookupAssetBalances()');

  try {
    // lookupAssetBalances() returns all accounts that hold (or have opted into) an asset
    const balancesResult = await indexer.lookupAssetBalances(assetId);

    printSuccess(`Found ${balancesResult.balances.length} holder(s) for Asset ID ${assetId}`);
    printInfo('');

    if (balancesResult.balances.length > 0) {
      printInfo('Asset balances:');
      for (const balance of balancesResult.balances) {
        printInfo(`  Address: ${shortenAddress(balance.address)}`);
        printInfo(`    - amount: ${balance.amount.toLocaleString('en-US')}`);
        printInfo(`    - isFrozen: ${balance.isFrozen}`);
        if (balance.optedInAtRound !== undefined) {
          printInfo(`    - optedInAtRound: ${balance.optedInAtRound}`);
        }
        printInfo('');
      }
    }

    printInfo(`Query performed at round: ${balancesResult.currentRound}`);
  } catch (error) {
    printError(
      `lookupAssetBalances failed: ${error instanceof Error ? error.message : String(error)}`,
    );
  }

  // =========================================================================
  // Step 5: Filter by currencyGreaterThan
  // =========================================================================
  printStep(5, 'Filtering holders by currencyGreaterThan');

  try {
    // Filter to only show accounts with more than 500 BAL (500,000 base units)
    printInfo('Querying holders with amount > 500,000 base units (> 500 BAL)...');
    const highBalanceResult = await indexer.lookupAssetBalances(assetId, {
      currencyGreaterThan: 500_000n,
    });

    printSuccess(`Found ${highBalanceResult.balances.length} holder(s) with balance > 500 BAL`);
    for (const balance of highBalanceResult.balances) {
      printInfo(
        `  ${shortenAddress(balance.address)}: ${balance.amount.toLocaleString('en-US')} base units`,
      );
    }
  } catch (error) {
    printError(
      `currencyGreaterThan query failed: ${error instanceof Error ? error.message : String(error)}`,
    );
  }

  // =========================================================================
  // Step 6: Filter by currencyLessThan
  // =========================================================================
  printStep(6, 'Filtering holders by currencyLessThan');

  try {
    // Filter to only show accounts with less than 1,000,000 base units (< 1000 BAL)
    printInfo('Querying holders with amount < 1,000,000 base units (< 1000 BAL)...');
    const lowBalanceResult = await indexer.lookupAssetBalances(assetId, {
      currencyLessThan: 1_000_000n,
    });

    printSuccess(`Found ${lowBalanceResult.balances.length} holder(s) with balance < 1000 BAL`);
    for (const balance of lowBalanceResult.balances) {
      printInfo(
        `  ${shortenAddress(balance.address)}: ${balance.amount.toLocaleString('en-US')} base units`,
      );
    }
  } catch (error) {
    printError(
      `currencyLessThan query failed: ${error instanceof Error ? error.message : String(error)}`,
    );
  }

  // =========================================================================
  // Step 7: Combine currencyGreaterThan and currencyLessThan (range filter)
  // =========================================================================
  printStep(7, 'Filtering holders by balance range (combining currency filters)');

  try {
    // Filter to show accounts with balance between 100 BAL and 2000 BAL
    printInfo('Querying holders with 100,000 < amount < 2,000,000 base units (100-2000 BAL)...');
    const rangeResult = await indexer.lookupAssetBalances(assetId, {
      currencyGreaterThan: 100_000n,
      currencyLessThan: 2_000_000n,
    });

    printSuccess(
      `Found ${rangeResult.balances.length} holder(s) with balance between 100 and 2000 BAL`,
    );
    for (const balance of rangeResult.balances) {
      printInfo(
        `  ${shortenAddress(balance.address)}: ${balance.amount.toLocaleString('en-US')} base units`,
      );
    }
  } catch (error) {
    printError(
      `Range filter query failed: ${error instanceof Error ? error.message : String(error)}`,
    );
  }

  // =========================================================================
  // Step 8: Using includeAll to include 0 balance accounts
  // =========================================================================
  printStep(8, 'Using includeAll to include accounts with 0 balance');

  try {
    // By default, lookupAssetBalances may exclude accounts with 0 balance
    // Use includeAll=true to include opted-in accounts with no holdings
    printInfo('Querying with includeAll=true to include all opted-in accounts...');
    const allHoldersResult = await indexer.lookupAssetBalances(assetId, {
      includeAll: true,
    });

    printSuccess(`Found ${allHoldersResult.balances.length} holder(s) (including 0 balance)`);
    printInfo('');

    const zeroBalanceCount = allHoldersResult.balances.filter(b => b.amount === 0n).length;
    const nonZeroCount = allHoldersResult.balances.filter(b => b.amount > 0n).length;

    printInfo(`  - Accounts with balance > 0: ${nonZeroCount}`);
    printInfo(`  - Accounts with balance = 0: ${zeroBalanceCount}`);
    printInfo('');

    printInfo('All holders:');
    for (const balance of allHoldersResult.balances) {
      const balanceStr =
        balance.amount === 0n ? '0 (opted-in only)' : balance.amount.toLocaleString('en-US');
      printInfo(`  ${shortenAddress(balance.address)}: ${balanceStr}`);
    }
  } catch (error) {
    printError(
      `includeAll query failed: ${error instanceof Error ? error.message : String(error)}`,
    );
  }

  // =========================================================================
  // Step 9: Demonstrate pagination
  // =========================================================================
  printStep(9, 'Demonstrating pagination for assets with many holders');

  try {
    // First query: get only 2 holders
    printInfo('Querying with limit=2...');
    const page1 = await indexer.lookupAssetBalances(assetId, {
      limit: 2,
      includeAll: true,
    });

    printInfo(`Page 1: Retrieved ${page1.balances.length} holder(s)`);
    for (const balance of page1.balances) {
      printInfo(
        `  - ${shortenAddress(balance.address)}: ${balance.amount.toLocaleString('en-US')}`,
      );
    }

    // Check if there are more results
    if (page1.nextToken) {
      printInfo(`  Next token available: ${page1.nextToken.substring(0, 20)}...`);
      printInfo('');

      // Second query: use the next token to get more results
      printInfo('Querying next page with next parameter...');
      const page2 = await indexer.lookupAssetBalances(assetId, {
        limit: 2,
        includeAll: true,
        next: page1.nextToken,
      });

      printInfo(`Page 2: Retrieved ${page2.balances.length} holder(s)`);
      for (const balance of page2.balances) {
        printInfo(
          `  - ${shortenAddress(balance.address)}: ${balance.amount.toLocaleString('en-US')}`,
        );
      }

      if (page2.nextToken) {
        printInfo(`  More results available (nextToken present)`);
      } else {
        printInfo(`  No more results (no nextToken)`);
      }
    } else {
      printInfo('  No pagination needed (all results fit in one page)');
    }
  } catch (error) {
    printError(`Pagination demo failed: ${error instanceof Error ? error.message : String(error)}`);
  }

  // =========================================================================
  // Summary
  // =========================================================================
  printHeader('Summary');
  printInfo('This example demonstrated:');
  printInfo('  1. Creating a test asset and distributing to multiple accounts');
  printInfo('  2. lookupAssetBalances(assetId) - Get all holders of an asset');
  printInfo('  3. Balance fields: address, amount, isFrozen, optedInAtRound');
  printInfo('  4. Filtering with currencyGreaterThan (minimum balance)');
  printInfo('  5. Filtering with currencyLessThan (maximum balance)');
  printInfo('  6. Combining currency filters for range queries');
  printInfo('  7. Using includeAll=true to include accounts with 0 balance');
  printInfo('  8. Pagination using limit and next parameters');
  printInfo('');
  printInfo('Key MiniAssetHolding fields (from lookupAssetBalances):');
  printInfo('  - address: The account address holding the asset (string)');
  printInfo('  - amount: Number of base units held (bigint)');
  printInfo('  - isFrozen: Whether the holding is frozen (boolean)');
  printInfo('  - optedInAtRound: Round when account opted into asset (optional bigint)');
  printInfo('');
  printInfo('Filter parameters:');
  printInfo('  - currencyGreaterThan: Only return balances > this value (bigint)');
  printInfo('  - currencyLessThan: Only return balances < this value (bigint)');
  printInfo('  - includeAll: Include accounts with 0 balance (boolean)');
  printInfo('');
  printInfo('Pagination parameters:');
  printInfo('  - limit: Maximum number of results per page');
  printInfo('  - next: Token from previous response to get next page');
}

main().catch(error => {
  console.error('Fatal error:', error);
  process.exit(1);
});

---

Other examples in Indexer Client

• Indexer Health Check
• Account Lookup
• Account Assets
• Account Applications
• Account Transactions
• Transaction Lookup
• Transaction Search
• Asset Lookup
• Asset Balances
• Asset Transactions
• Application Lookup
• Application Logs Lookup
• Application Boxes Lookup
• Block Lookup
• Block Headers Search
• Pagination