Indexer lookups / searching

Indexer lookups / searching is a higher-order use case capability provided by AlgoKit Utils that builds on top of the core capabilities. It provides type-safe indexer API wrappers (no more Record<string, any> pain), including automatic pagination control.

To see some usage examples check out the automated tests.

To import the indexer functions you can:

import { indexer } from '@algorandfoundation/algokit-utils'

All of the indexer functions require you to pass in an indexer SDK client, which you can get from AlgorandClient via algorand.client.indexer. These calls are not made more easy to call by exposing via AlgorandClient and thus not requiring the indexer SDK client to be passed in. This is because we want to add a tiny bit of friction to using indexer, given it’s an expensive API to run for node providers, the data from it can sometimes be slow and stale, and there are alternatives that allow individual projects to index subsets of chain data specific to them as a preferred option. In saying that, it’s a very useful API for doing ad hoc data retrieval, writing automated tests, and many other uses.

Indexer wrapper functions

There is a subset of indexer API calls that are exposed as easy to use methods with correct typing exposed and automatic pagination for multi item returns.

• indexer.lookupTransactionById(transactionId, algorand.client.indexer) - Finds a transaction by ID
• indexer.lookupAccountByAddress(accountAddress, algorand.client.indexer) - Finds an account by address
• indexer.lookupAccountCreatedApplicationByAddress(algorand.client.indexer, address, getAll?, paginationLimit?) - Finds all applications created for an account
• indexer.lookupAssetHoldings(algorand.client.indexer, assetId, options?, paginationLimit?) - Finds all asset holdings for the given asset
• indexer.searchTransactions(algorand.client.indexer, searchCriteria, paginationLimit?) - Search for transactions with a given set of criteria
• indexer.executePaginatedRequest(extractItems, buildRequest) - Execute the given indexer request with automatic pagination

Search transactions example

To use the indexer.searchTransaction method, you can follow this example as a starting point:

const transactions = await indexer.searchTransactions(algorand.client.indexer, (s) =>
  s.txType('pay').addressRole('sender').address(myAddress),
)

Automatic pagination example

To use the indexer.executePaginatedRequest method, you can follow this example as a starting point:

const transactions = await executePaginatedRequest(
  (response: TransactionsResponse) => {
    return response.transactions
  },
  (nextToken) => {
    let s = algorand.client.indexer.searchForTransactions().txType('pay').address(myAddress).limit(1000)
    if (nextToken) {
      s = s.nextToken(nextToken)
    }
    return s
  },
)

It takes the first lambda to translate the raw response into the array that should keep getting appended as the pagination is followed and the second lambda constructs the request (without the .do() call), including populating the pagination token.

Indexer API response types

The response model type definitions for the indexer API are autogenerated and available from the @algorandfoundation/algokit-indexer-client package, which is re-exported via AlgoKit Utils.

To access these types you can import them:

import { TransactionResponse, AccountResponse, /* ... */ } from '@algorandfoundation/algokit-utils/indexer-client'

The types follow the naming conventions from the official Algorand indexer API specification (e.g., TransactionResponse, AccountResponse, ApplicationResponse, AssetResponse, etc.).