Asset Lookup

← Back to Indexer Client

Description

This example demonstrates how to lookup and search for assets using the IndexerClient lookupAssetById() and searchForAssets() methods.

Prerequisites

• LocalNet running (via algokit localnet start)

Run This Example

From the repository root:

cd examples
npm run example indexer_client/08-asset-lookup.ts

Code

View source on GitHub

08-asset-lookup.ts

/**
 * Example: Asset Lookup
 *
 * This example demonstrates how to lookup and search for assets using
 * the IndexerClient lookupAssetById() and searchForAssets() methods.
 *
 * Prerequisites:
 * - LocalNet running (via `algokit localnet start`)
 */

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

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

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

  // =========================================================================
  // Step 1: Get a funded account from LocalNet
  // =========================================================================
  printStep(1, 'Getting a funded account from LocalNet');

  let creatorAddress: string;

  try {
    const dispenser = await algorand.account.dispenserFromEnvironment();
    creatorAddress = dispenser.addr.toString();
    printSuccess(`Using dispenser account: ${shortenAddress(creatorAddress)}`);
  } catch (error) {
    printError(
      `Failed to get dispenser account: ${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 test assets using AlgorandClient
  // =========================================================================
  printStep(2, 'Creating test assets for demonstration');

  let assetId1: bigint;
  let assetId2: bigint;

  try {
    // Create first test asset with full configuration
    printInfo('Creating first test asset: AlphaToken (ALPHA)...');
    const result1 = await algorand.send.assetCreate({
      sender: creatorAddress,
      total: 1_000_000_000_000n, // 1,000,000 units with 6 decimals
      decimals: 6,
      assetName: 'AlphaToken',
      unitName: 'ALPHA',
      url: 'https://example.com/alpha',
      defaultFrozen: false,
      manager: creatorAddress,
      reserve: creatorAddress,
      freeze: creatorAddress,
      clawback: creatorAddress,
    });
    assetId1 = result1.assetId;
    printSuccess(`Created AlphaToken with Asset ID: ${assetId1}`);

    // Create second test asset with different unit name
    printInfo('Creating second test asset: BetaCoin (BETA)...');
    const result2 = await algorand.send.assetCreate({
      sender: creatorAddress,
      total: 500_000_000n, // 500,000 units with 3 decimals
      decimals: 3,
      assetName: 'BetaCoin',
      unitName: 'BETA',
      url: 'https://example.com/beta',
      defaultFrozen: false,
    });
    assetId2 = result2.assetId;
    printSuccess(`Created BetaCoin with Asset ID: ${assetId2}`);
    printInfo('');
  } catch (error) {
    printError(
      `Failed to create test assets: ${error instanceof Error ? error.message : String(error)}`,
    );
    printInfo('');
    printInfo('If LocalNet errors occur, try: algokit localnet reset');
    return;
  }

  // =========================================================================
  // Step 3: Lookup asset by ID with lookupAssetById()
  // =========================================================================
  printStep(3, 'Looking up asset by ID with lookupAssetById()');

  try {
    // lookupAssetById() returns detailed asset information
    const assetResult = await indexer.lookupAssetById(assetId1);

    printSuccess(`Found asset with ID: ${assetResult.asset.id}`);
    printInfo('');

    // Display asset params
    const params = assetResult.asset.params;
    printInfo('Asset Parameters:');
    printInfo(`  - index: ${assetResult.asset.id}`);
    printInfo(`  - creator: ${shortenAddress(params.creator)}`);
    printInfo(`  - total: ${params.total.toLocaleString('en-US')}`);
    printInfo(`  - decimals: ${params.decimals}`);
    printInfo(`  - name: ${params.name ?? '(not set)'}`);
    printInfo(`  - unitName: ${params.unitName ?? '(not set)'}`);
    printInfo(`  - url: ${params.url ?? '(not set)'}`);
    printInfo(
      `  - metadataHash: ${params.metadataHash ? Buffer.from(params.metadataHash).toString('hex') : '(not set)'}`,
    );
    printInfo(`  - defaultFrozen: ${params.defaultFrozen ?? false}`);
    printInfo('');

    // Display manager addresses
    printInfo('Manager Addresses:');
    printInfo(`  - manager: ${params.manager ? shortenAddress(params.manager) : '(not set)'}`);
    printInfo(`  - reserve: ${params.reserve ? shortenAddress(params.reserve) : '(not set)'}`);
    printInfo(`  - freeze: ${params.freeze ? shortenAddress(params.freeze) : '(not set)'}`);
    printInfo(`  - clawback: ${params.clawback ? shortenAddress(params.clawback) : '(not set)'}`);
    printInfo('');

    // Display creation/destruction info
    if (assetResult.asset.createdAtRound !== undefined) {
      printInfo(`Created at round: ${assetResult.asset.createdAtRound}`);
    }
    if (assetResult.asset.destroyedAtRound !== undefined) {
      printInfo(`Destroyed at round: ${assetResult.asset.destroyedAtRound}`);
    }
    if (assetResult.asset.deleted !== undefined) {
      printInfo(`Deleted: ${assetResult.asset.deleted}`);
    }

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

  // =========================================================================
  // Step 4: Search for assets with searchForAssets()
  // =========================================================================
  printStep(4, 'Searching for assets with searchForAssets()');

  try {
    // searchForAssets() returns a list of assets matching the criteria
    const searchResult = await indexer.searchForAssets({ limit: 10 });

    printSuccess(`Found ${searchResult.assets.length} asset(s)`);
    printInfo('');

    if (searchResult.assets.length > 0) {
      printInfo('Assets found:');
      for (const asset of searchResult.assets.slice(0, 5)) {
        printInfo(`  Asset ID: ${asset.id}`);
        printInfo(`    - name: ${asset.params.name ?? '(not set)'}`);
        printInfo(`    - unitName: ${asset.params.unitName ?? '(not set)'}`);
        printInfo(`    - creator: ${shortenAddress(asset.params.creator)}`);
        printInfo('');
      }
      if (searchResult.assets.length > 5) {
        printInfo(`  ... and ${searchResult.assets.length - 5} more`);
      }
    }

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

  // =========================================================================
  // Step 5: Filter by name
  // =========================================================================
  printStep(5, 'Filtering assets by name');

  try {
    // Search for assets with a specific name
    printInfo('Searching for assets with name "Alpha"...');
    const nameResult = await indexer.searchForAssets({ name: 'Alpha' });

    printSuccess(`Found ${nameResult.assets.length} asset(s) matching name "Alpha"`);
    if (nameResult.assets.length > 0) {
      for (const asset of nameResult.assets) {
        printInfo(`  - Asset ID ${asset.id}: ${asset.params.name} (${asset.params.unitName})`);
      }
    }
  } catch (error) {
    printError(`Filter by name failed: ${error instanceof Error ? error.message : String(error)}`);
  }

  // =========================================================================
  // Step 6: Filter by unit name
  // =========================================================================
  printStep(6, 'Filtering assets by unit name');

  try {
    // Search for assets with a specific unit name
    printInfo('Searching for assets with unit "BETA"...');
    const unitResult = await indexer.searchForAssets({ unit: 'BETA' });

    printSuccess(`Found ${unitResult.assets.length} asset(s) matching unit "BETA"`);
    if (unitResult.assets.length > 0) {
      for (const asset of unitResult.assets) {
        printInfo(`  - Asset ID ${asset.id}: ${asset.params.name} (${asset.params.unitName})`);
      }
    }
  } catch (error) {
    printError(`Filter by unit failed: ${error instanceof Error ? error.message : String(error)}`);
  }

  // =========================================================================
  // Step 7: Filter by creator
  // =========================================================================
  printStep(7, 'Filtering assets by creator');

  try {
    // Search for assets created by a specific account
    printInfo(`Searching for assets created by ${shortenAddress(creatorAddress)}...`);
    const creatorResult = await indexer.searchForAssets({ creator: creatorAddress });

    printSuccess(`Found ${creatorResult.assets.length} asset(s) created by this account`);
    if (creatorResult.assets.length > 0) {
      for (const asset of creatorResult.assets) {
        printInfo(
          `  - Asset ID ${asset.id}: ${asset.params.name ?? '(unnamed)'} (${asset.params.unitName ?? 'N/A'})`,
        );
      }
    }
  } catch (error) {
    printError(
      `Filter by creator failed: ${error instanceof Error ? error.message : String(error)}`,
    );
  }

  // =========================================================================
  // Step 8: Filter by asset ID for exact match
  // =========================================================================
  printStep(8, 'Filtering by assetId for exact match');

  try {
    // Use assetId parameter for exact matching
    printInfo(`Searching for exact asset ID ${assetId2}...`);
    const exactResult = await indexer.searchForAssets({ assetId: assetId2 });

    if (exactResult.assets.length > 0) {
      const asset = exactResult.assets[0];
      printSuccess(`Found exact match for Asset ID ${assetId2}`);
      printInfo(`  - name: ${asset.params.name ?? '(not set)'}`);
      printInfo(`  - unitName: ${asset.params.unitName ?? '(not set)'}`);
      printInfo(`  - total: ${asset.params.total.toLocaleString('en-US')}`);
    } else {
      printInfo(`No asset found with ID ${assetId2}`);
    }
  } catch (error) {
    printError(
      `Exact match search failed: ${error instanceof Error ? error.message : String(error)}`,
    );
  }

  // =========================================================================
  // Step 9: Handle asset not found
  // =========================================================================
  printStep(9, 'Handling asset not found');

  try {
    // Try to look up a non-existent asset ID
    const nonExistentId = 999999999n;
    printInfo(`Looking up non-existent asset ID ${nonExistentId}...`);

    await indexer.lookupAssetById(nonExistentId);
    printInfo('Asset found (unexpected)');
  } catch (error) {
    const message = error instanceof Error ? error.message : String(error);
    if (
      message.includes('no asset found') ||
      message.includes('not found') ||
      message.includes('404')
    ) {
      printSuccess('Asset not found error handled correctly');
      printInfo(`  Error message: ${message}`);
    } else {
      printError(`Unexpected error: ${message}`);
    }
  }

  // =========================================================================
  // Step 10: Include deleted assets with includeAll
  // =========================================================================
  printStep(10, 'Including deleted/destroyed assets with includeAll');

  try {
    // The includeAll parameter includes assets that have been deleted/destroyed
    printInfo('Searching with includeAll=true to include deleted assets...');
    const allAssetsResult = await indexer.searchForAssets({
      creator: creatorAddress,
      includeAll: true,
    });

    printSuccess(`Found ${allAssetsResult.assets.length} asset(s) (including any deleted)`);
    for (const asset of allAssetsResult.assets) {
      const status = asset.deleted ? ' [DELETED]' : '';
      printInfo(`  - Asset ID ${asset.id}: ${asset.params.name ?? '(unnamed)'}${status}`);
    }
  } catch (error) {
    printError(
      `Include all search failed: ${error instanceof Error ? error.message : String(error)}`,
    );
  }

  // =========================================================================
  // Summary
  // =========================================================================
  printHeader('Summary');
  printInfo('This example demonstrated:');
  printInfo('  1. Creating test assets using AlgorandClient.send.assetCreate()');
  printInfo('  2. lookupAssetById(assetId) - Get detailed asset information');
  printInfo('  3. searchForAssets() - Search for assets with various filters');
  printInfo('  4. Filtering by name, unit, and creator');
  printInfo('  5. Filtering by assetId for exact match');
  printInfo('  6. Handling asset not found errors');
  printInfo('  7. Including deleted assets with includeAll parameter');
  printInfo('');
  printInfo('Key Asset fields:');
  printInfo('  - id: Unique asset identifier (bigint)');
  printInfo('  - deleted: Whether asset is deleted (optional boolean)');
  printInfo('  - createdAtRound: Round when created (optional bigint)');
  printInfo('  - destroyedAtRound: Round when destroyed (optional bigint)');
  printInfo('');
  printInfo('Key AssetParams fields:');
  printInfo('  - creator: Address that created the asset');
  printInfo('  - total: Total supply in base units (bigint)');
  printInfo('  - decimals: Number of decimal places (0-19)');
  printInfo('  - name: Full asset name (optional)');
  printInfo('  - unitName: Short unit name like "ALGO" (optional)');
  printInfo('  - url: URL for more info (optional)');
  printInfo('  - metadataHash: 32-byte metadata hash (optional)');
  printInfo('');
  printInfo('Manager address fields:');
  printInfo('  - manager: Can reconfigure or destroy the asset');
  printInfo('  - reserve: Holds non-minted units');
  printInfo('  - freeze: Can freeze/unfreeze holdings');
  printInfo('  - clawback: Can revoke holdings');
  printInfo('');
  printInfo('Search filter parameters:');
  printInfo('  - name: Filter by asset name (prefix match)');
  printInfo('  - unit: Filter by unit name (prefix match)');
  printInfo('  - creator: Filter by creator address');
  printInfo('  - assetId: Filter by exact asset ID');
  printInfo('  - includeAll: Include deleted/destroyed assets');
  printInfo('  - limit/next: Pagination parameters');
}

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