Transaction History

This guide explains how to retrieve all transfers, filter by direction, paginate results, and track transaction finality.

Retrieve All Transfers

You can retrieve the account's transfer history using account.getTransfers():

const transfers = await account.getTransfers()
console.log('Recent transfers:', transfers)

Filter by Direction

You can filter transfers by direction using the direction option in account.getTransfers():

const incoming = await account.getTransfers({ direction: 'incoming' })
console.log('Incoming transfers:', incoming)

You can retrieve outgoing transfers with a custom limit using account.getTransfers():

const outgoing = await account.getTransfers({
  direction: 'outgoing',
  limit: 5
})
console.log('Outgoing transfers:', outgoing)

Paginate Results

You can paginate through transfer history using the limit and skip options in account.getTransfers():

const page = await account.getTransfers({
  direction: 'all',
  limit: 20,
  skip: 10
})
console.log('Transfers 11-30:', page)

Track Transaction Finality

Use account.getTransaction() to read normalized status for a transaction that appears in this account address's history:

const receipt = await account.getTransaction(transactionHash)
console.log(receipt.finality)      // pending, confirmed, or final
console.log(receipt.confirmations) // 0, a positive number, or null

An included transaction becomes final after six confirmations. If a custom client cannot provide the current block height, confirmations is null and finality remains confirmed.

Wait for a required finality level with waitForTransaction():

const receipt = await account.waitForTransaction(transactionHash, {
  target: 'final'
})

console.log('Final at height:', receipt.block)

The Bitcoin defaults are a 30-second polling interval and one-hour timeout. The module cannot reliably classify mempool eviction as dropped; an unseen or evicted transaction eventually times out. Invalid transaction IDs throw ValueError, while valid IDs absent from this account's history throw NoSuchElementError.

Next Steps

Learn how to sign and verify messages.