Account Transactions

← Back to Indexer Client

Description

This example demonstrates how to query an account’s transaction history using the IndexerClient lookupAccountTransactions() method.

Prerequisites

• LocalNet running (via algokit localnet start)

Run This Example

From the repository root:

cd examples
npm run example indexer_client/05-account-transactions.ts

Code

View source on GitHub

05-account-transactions.ts

/**
 * Example: Account Transactions
 *
 * This example demonstrates how to query an account's transaction history using
 * the IndexerClient lookupAccountTransactions() method.
 *
 * Prerequisites:
 * - LocalNet running (via `algokit localnet start`)
 */

import { algo } from '@algorandfoundation/algokit-utils'
import {
  createAlgorandClient,
  createIndexerClient,
  formatMicroAlgo,
  printError,
  printHeader,
  printInfo,
  printStep,
  printSuccess,
  shortenAddress,
} from '../shared/utils.js'

async function main() {
  printHeader('Account Transactions 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 senderAddress: string
  let senderAccount: Awaited<ReturnType<typeof algorand.account.kmd.getLocalNetDispenserAccount>>

  try {
    senderAccount = await algorand.account.kmd.getLocalNetDispenserAccount()
    senderAddress = senderAccount.addr.toString()
    algorand.setSignerFromAccount(senderAccount)
    printSuccess(`Using dispenser account: ${shortenAddress(senderAddress)}`)
  } 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 transactions for demonstration
  // =========================================================================
  printStep(2, 'Creating test transactions for demonstration')

  let receiverAddress: string
  let assetId: bigint

  try {
    // Create a random receiver account
    const receiverAccount = algorand.account.random()
    receiverAddress = receiverAccount.addr.toString()
    algorand.setSignerFromAccount(receiverAccount)
    printInfo(`Created receiver account: ${shortenAddress(receiverAddress)}`)

    // Fund the receiver with some initial ALGO
    printInfo('Sending initial payment to receiver...')
    await algorand.send.payment({
      sender: senderAccount.addr,
      receiver: receiverAccount.addr,
      amount: algo(10),
    })
    printSuccess('Initial payment sent: 10 ALGO')

    // Send a few more payments with different amounts
    printInfo('Sending additional payments...')
    await algorand.send.payment({
      sender: senderAccount.addr,
      receiver: receiverAccount.addr,
      amount: algo(5),
    })
    printSuccess('Payment sent: 5 ALGO')

    await algorand.send.payment({
      sender: senderAccount.addr,
      receiver: receiverAccount.addr,
      amount: algo(0.5),
    })
    printSuccess('Payment sent: 0.5 ALGO')

    // Create an asset
    printInfo('Creating a test asset...')
    const assetCreateResult = await algorand.send.assetCreate({
      sender: senderAccount.addr,
      total: 1_000_000n,
      decimals: 6,
      assetName: 'TestToken',
      unitName: 'TEST',
    })
    assetId = assetCreateResult.assetId
    printSuccess(`Created asset: TestToken (ID: ${assetId})`)

    // Opt-in receiver to the asset
    printInfo('Opting receiver into asset...')
    await algorand.send.assetOptIn({
      sender: receiverAccount.addr,
      assetId: assetId,
    })
    printSuccess('Receiver opted into asset')

    // Transfer some assets
    printInfo('Sending asset transfer...')
    await algorand.send.assetTransfer({
      sender: senderAccount.addr,
      receiver: receiverAccount.addr,
      assetId: assetId,
      amount: 100_000n,
    })
    printSuccess('Asset transfer sent: 100,000 TestToken (0.1 TEST)')

    // Small delay to allow indexer to catch up
    printInfo('Waiting for indexer to index transactions...')
    await new Promise((resolve) => setTimeout(resolve, 3000))
    printInfo('')
  } catch (error) {
    printError(`Failed to create test transactions: ${error instanceof Error ? error.message : String(error)}`)
    printInfo('')
    printInfo('If LocalNet errors occur, try: algokit localnet reset')
    return
  }

  // =========================================================================
  // Step 3: Lookup account transactions with lookupAccountTransactions()
  // =========================================================================
  printStep(3, 'Looking up account transactions with lookupAccountTransactions()')

  try {
    // Note: Results are returned newest to oldest for account transactions
    const txnsResult = await indexer.lookupAccountTransactions(senderAddress)

    printSuccess(`Found ${txnsResult.transactions.length} transaction(s) for account`)
    printInfo('Note: Results are returned newest to oldest')
    printInfo('')

    if (txnsResult.transactions.length > 0) {
      printInfo('Recent transactions:')
      for (const tx of txnsResult.transactions.slice(0, 5)) {
        printInfo(`  Transaction ID: ${tx.id ? shortenAddress(tx.id, 8, 6) : 'N/A'}`)
        printInfo(`    - txType: ${tx.txType}`)
        printInfo(`    - sender: ${shortenAddress(tx.sender)}`)
        printInfo(`    - fee: ${formatMicroAlgo(tx.fee)}`)
        if (tx.confirmedRound !== undefined) {
          printInfo(`    - confirmedRound: ${tx.confirmedRound}`)
        }
        if (tx.roundTime !== undefined) {
          const date = new Date(tx.roundTime * 1000)
          printInfo(`    - roundTime: ${date.toISOString()}`)
        }
        // Show payment details if present
        if (tx.paymentTransaction) {
          printInfo(`    - receiver: ${shortenAddress(tx.paymentTransaction.receiver)}`)
          printInfo(`    - amount: ${formatMicroAlgo(tx.paymentTransaction.amount)}`)
        }
        // Show asset transfer details if present
        if (tx.assetTransferTransaction) {
          printInfo(`    - assetId: ${tx.assetTransferTransaction.assetId}`)
          printInfo(`    - amount: ${tx.assetTransferTransaction.amount}`)
          printInfo(`    - receiver: ${shortenAddress(tx.assetTransferTransaction.receiver)}`)
        }
        // Show asset config details if present
        if (tx.assetConfigTransaction) {
          printInfo(`    - assetId: ${tx.assetConfigTransaction.assetId ?? 'new asset'}`)
          if (tx.createdAssetId) {
            printInfo(`    - createdAssetId: ${tx.createdAssetId}`)
          }
        }
        printInfo('')
      }
    }

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

  // =========================================================================
  // Step 4: Filter by transaction type (pay, axfer, appl)
  // =========================================================================
  printStep(4, 'Filtering by transaction type (txType)')

  try {
    // Filter for payment transactions only
    printInfo('Querying payment transactions (txType=pay)...')
    const payTxns = await indexer.lookupAccountTransactions(senderAddress, { txType: 'pay' })
    printSuccess(`Found ${payTxns.transactions.length} payment transaction(s)`)

    if (payTxns.transactions.length > 0) {
      for (const tx of payTxns.transactions.slice(0, 3)) {
        printInfo(`  - ${tx.id ? shortenAddress(tx.id, 8, 6) : 'N/A'}: ${formatMicroAlgo(tx.paymentTransaction?.amount ?? 0n)}`)
      }
    }
    printInfo('')

    // Filter for asset transfer transactions
    printInfo('Querying asset transfer transactions (txType=axfer)...')
    const axferTxns = await indexer.lookupAccountTransactions(senderAddress, { txType: 'axfer' })
    printSuccess(`Found ${axferTxns.transactions.length} asset transfer transaction(s)`)

    if (axferTxns.transactions.length > 0) {
      for (const tx of axferTxns.transactions.slice(0, 3)) {
        printInfo(`  - ${tx.id ? shortenAddress(tx.id, 8, 6) : 'N/A'}: assetId=${tx.assetTransferTransaction?.assetId}, amount=${tx.assetTransferTransaction?.amount}`)
      }
    }
    printInfo('')

    // Filter for asset config transactions
    printInfo('Querying asset config transactions (txType=acfg)...')
    const acfgTxns = await indexer.lookupAccountTransactions(senderAddress, { txType: 'acfg' })
    printSuccess(`Found ${acfgTxns.transactions.length} asset config transaction(s)`)

    if (acfgTxns.transactions.length > 0) {
      for (const tx of acfgTxns.transactions.slice(0, 3)) {
        const assetIdDisplay = tx.createdAssetId ?? tx.assetConfigTransaction?.assetId ?? 'N/A'
        printInfo(`  - ${tx.id ? shortenAddress(tx.id, 8, 6) : 'N/A'}: assetId=${assetIdDisplay}`)
      }
    }
  } catch (error) {
    printError(`Transaction type filter failed: ${error instanceof Error ? error.message : String(error)}`)
  }

  // =========================================================================
  // Step 5: Filter by round range (minRound, maxRound)
  // =========================================================================
  printStep(5, 'Filtering by round range (minRound, maxRound)')

  try {
    // Get current round
    const allTxns = await indexer.lookupAccountTransactions(senderAddress, { limit: 1 })
    const currentRound = allTxns.currentRound

    // Filter to recent rounds only (last 100 rounds, but not negative)
    const minRound = currentRound > 100n ? currentRound - 100n : 0n
    printInfo(`Querying transactions from round ${minRound} to ${currentRound}...`)

    const roundFilteredTxns = await indexer.lookupAccountTransactions(senderAddress, {
      minRound: minRound,
      maxRound: currentRound,
    })

    printSuccess(`Found ${roundFilteredTxns.transactions.length} transaction(s) in round range ${minRound}-${currentRound}`)

    if (roundFilteredTxns.transactions.length > 0) {
      const rounds = roundFilteredTxns.transactions.map((tx) => tx.confirmedRound).filter((r) => r !== undefined)
      if (rounds.length > 0) {
        const minFoundRound = rounds.reduce((a, b) => (a! < b! ? a : b))
        const maxFoundRound = rounds.reduce((a, b) => (a! > b! ? a : b))
        printInfo(`  Rounds of found transactions: ${minFoundRound} to ${maxFoundRound}`)
      }
    }
  } catch (error) {
    printError(`Round filter failed: ${error instanceof Error ? error.message : String(error)}`)
  }

  // =========================================================================
  // Step 6: Filter by time (beforeTime, afterTime)
  // =========================================================================
  printStep(6, 'Filtering by time (beforeTime, afterTime)')

  try {
    // Get current time and a time window
    const now = new Date()
    const oneHourAgo = new Date(now.getTime() - 60 * 60 * 1000) // 1 hour ago

    // Format as RFC 3339 (ISO 8601 format that indexer expects)
    const afterTimeStr = oneHourAgo.toISOString()
    const beforeTimeStr = now.toISOString()

    printInfo(`Querying transactions from ${afterTimeStr} to ${beforeTimeStr}...`)

    const timeFilteredTxns = await indexer.lookupAccountTransactions(senderAddress, {
      afterTime: afterTimeStr,
      beforeTime: beforeTimeStr,
    })

    printSuccess(`Found ${timeFilteredTxns.transactions.length} transaction(s) in the last hour`)

    if (timeFilteredTxns.transactions.length > 0) {
      const times = timeFilteredTxns.transactions.map((tx) => tx.roundTime).filter((t) => t !== undefined)
      if (times.length > 0) {
        const minTime = Math.min(...(times as number[]))
        const maxTime = Math.max(...(times as number[]))
        printInfo(`  Time range of found transactions:`)
        printInfo(`    - Earliest: ${new Date(minTime * 1000).toISOString()}`)
        printInfo(`    - Latest: ${new Date(maxTime * 1000).toISOString()}`)
      }
    }
  } catch (error) {
    printError(`Time filter failed: ${error instanceof Error ? error.message : String(error)}`)
  }

  // =========================================================================
  // Step 7: Filter by amount (currencyGreaterThan, currencyLessThan)
  // =========================================================================
  printStep(7, 'Filtering by amount (currencyGreaterThan, currencyLessThan)')

  try {
    // Filter for transactions with amount greater than 1 ALGO (1,000,000 microAlgo)
    const minAmount = 1_000_000n
    printInfo(`Querying transactions with amount > ${formatMicroAlgo(minAmount)}...`)

    const largeAmountTxns = await indexer.lookupAccountTransactions(senderAddress, {
      currencyGreaterThan: minAmount,
    })

    printSuccess(`Found ${largeAmountTxns.transactions.length} transaction(s) with amount > 1 ALGO`)

    if (largeAmountTxns.transactions.length > 0) {
      for (const tx of largeAmountTxns.transactions.slice(0, 3)) {
        const amount = tx.paymentTransaction?.amount ?? tx.assetTransferTransaction?.amount ?? 0n
        printInfo(`  - ${tx.id ? shortenAddress(tx.id, 8, 6) : 'N/A'}: ${tx.txType}, amount=${amount}`)
      }
    }
    printInfo('')

    // Filter for transactions with amount less than 5 ALGO (5,000,000 microAlgo)
    const maxAmount = 5_000_000n
    printInfo(`Querying transactions with amount < ${formatMicroAlgo(maxAmount)}...`)

    const smallAmountTxns = await indexer.lookupAccountTransactions(senderAddress, {
      currencyLessThan: maxAmount,
    })

    printSuccess(`Found ${smallAmountTxns.transactions.length} transaction(s) with amount < 5 ALGO`)

    if (smallAmountTxns.transactions.length > 0) {
      for (const tx of smallAmountTxns.transactions.slice(0, 3)) {
        const amount = tx.paymentTransaction?.amount ?? tx.assetTransferTransaction?.amount ?? 0n
        printInfo(`  - ${tx.id ? shortenAddress(tx.id, 8, 6) : 'N/A'}: ${tx.txType}, amount=${amount}`)
      }
    }
    printInfo('')

    // Combine both filters to find transactions in a specific range
    printInfo(`Querying transactions with amount between ${formatMicroAlgo(minAmount)} and ${formatMicroAlgo(maxAmount)}...`)

    const rangeAmountTxns = await indexer.lookupAccountTransactions(senderAddress, {
      currencyGreaterThan: minAmount,
      currencyLessThan: maxAmount,
    })

    printSuccess(`Found ${rangeAmountTxns.transactions.length} transaction(s) with amount in range 1-5 ALGO`)
  } catch (error) {
    printError(`Amount filter failed: ${error instanceof Error ? error.message : String(error)}`)
  }

  // =========================================================================
  // Step 8: Pagination with limit and next
  // =========================================================================
  printStep(8, 'Demonstrating pagination with limit and next')

  try {
    printInfo('Querying transactions with limit=2...')
    const page1 = await indexer.lookupAccountTransactions(senderAddress, { limit: 2 })

    printInfo(`Page 1: Retrieved ${page1.transactions.length} transaction(s)`)
    for (const tx of page1.transactions) {
      printInfo(`  - ${tx.id ? shortenAddress(tx.id, 8, 6) : 'N/A'}: ${tx.txType}`)
    }

    if (page1.nextToken) {
      printInfo(`  - Next token available: ${page1.nextToken.substring(0, 20)}...`)
      printInfo('')

      // Get next page
      printInfo('Querying next page...')
      const page2 = await indexer.lookupAccountTransactions(senderAddress, {
        limit: 2,
        next: page1.nextToken,
      })

      printInfo(`Page 2: Retrieved ${page2.transactions.length} transaction(s)`)
      for (const tx of page2.transactions) {
        printInfo(`  - ${tx.id ? shortenAddress(tx.id, 8, 6) : 'N/A'}: ${tx.txType}`)
      }

      if (page2.nextToken) {
        printInfo(`  - More pages available (nextToken present)`)
      } else {
        printInfo(`  - No more pages (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. lookupAccountTransactions(address) - Get transaction history for an account')
  printInfo('  2. Results are returned newest to oldest')
  printInfo('  3. Filtering by txType (pay, axfer, acfg, appl, etc.)')
  printInfo('  4. Filtering by round range (minRound, maxRound)')
  printInfo('  5. Filtering by time (beforeTime, afterTime) using RFC 3339 format')
  printInfo('  6. Filtering by amount (currencyGreaterThan, currencyLessThan)')
  printInfo('  7. Pagination using limit and next parameters')
  printInfo('')
  printInfo('Key Transaction fields:')
  printInfo('  - id: Transaction ID (string)')
  printInfo('  - txType: Transaction type (pay, keyreg, acfg, axfer, afrz, appl, stpf, hb)')
  printInfo('  - sender: Sender address (string)')
  printInfo('  - fee: Transaction fee in microAlgos (bigint)')
  printInfo('  - confirmedRound: Round when confirmed (bigint)')
  printInfo('  - roundTime: Unix timestamp when confirmed (number)')
  printInfo('  - paymentTransaction: Payment details (receiver, amount, closeRemainderTo)')
  printInfo('  - assetTransferTransaction: Asset transfer details (assetId, amount, receiver)')
  printInfo('  - assetConfigTransaction: Asset config details (assetId, params)')
  printInfo('  - applicationTransaction: App call details (applicationId, onComplete, etc.)')
  printInfo('')
  printInfo('Filter parameters:')
  printInfo('  - txType: Filter by transaction type')
  printInfo('  - minRound/maxRound: Filter by round range')
  printInfo('  - beforeTime/afterTime: Filter by time (RFC 3339 format)')
  printInfo('  - currencyGreaterThan/currencyLessThan: Filter by amount')
  printInfo('  - assetId: Filter by specific asset')
  printInfo('  - limit/next: Pagination controls')
}

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