TypeScript balances and history - Polygon Developer Docs

omsWallet.indexer is independent from the stateful wallet client. Its read-only methods accept any address and use the project’s publishable key. They do not require authentication, an active session, or the active wallet address.

Query balances for an address

import {
  Networks,
  OMSWallet,
  type BalancesResult,
} from '@polygonlabs/oms-wallet'

const omsWallet = new OMSWallet({
  publishableKey: 'YOUR_PUBLISHABLE_KEY',
})

const result: BalancesResult = await omsWallet.indexer.getBalances({
  walletAddress: '0x1111111111111111111111111111111111111111',
  networks: [Networks.polygon],
  includeMetadata: true,
})

for (const balance of result.nativeBalances) {
  console.log(balance.chainId, balance.symbol, balance.balance)
}

for (const balance of result.balances) {
  console.log(
    balance.chainId,
    balance.contractAddress,
    balance.tokenId,
    balance.balance,
    balance.contractInfo?.decimals,
  )
}

Balance amounts are raw base-unit strings. Convert them for display with a trusted decimal count, for example formatUnits(BigInt(balance.balance), decimals) from viem. Contract token decimals can be absent from metadata; do not infer them from the network’s native token. Price and metadata fields are optional even when requested. BalancesResult separates native assets into NativeTokenBalance[] and contract assets into ContractTokenBalance[]. Contract balances carry a contract address and token ID; optional contract, token, and price metadata is undefined when unavailable. Use the package API reference when you need every response field.

Query transaction history

import {
  Networks,
  type TransactionHistoryResult,
} from '@polygonlabs/oms-wallet'

const history: TransactionHistoryResult =
  await omsWallet.indexer.getTransactionHistory({
    walletAddress: '0x1111111111111111111111111111111111111111',
    networks: [Networks.polygon],
    includeMetadata: true,
  })

for (const transaction of history.transactions) {
  console.log(
    transaction.txnHash,
    transaction.blockNumber,
    transaction.timestamp,
  )

  for (const transfer of transaction.transfers) {
    console.log(transfer.from, transfer.to, transfer.amounts)
  }
}

Each transaction includes its chain, hash, block position, timestamp, and transfers. The OMS transaction ID and transfer metadata are optional. Consult the package reference when your application needs fields beyond the workflow shown here.

Choose network scope

Pass networks when you know the exact SDK networks to query. If networks is omitted or empty, networkType controls the group:

'MAINNETS' is the default.
'TESTNETS' queries configured test networks.
'ALL' queries both groups.

Explicit nonempty networks take precedence over networkType. Network values must come from the SDK’s closed network registry.

Filter results

Balance requests can filter by contract address, token ID, and verification status. Set omitPrices: true to omit price data. includeMetadata defaults to true; set it to false when contract and token metadata are unnecessary. History requests can filter by contract addresses, EVM transaction hashes, OMS transaction IDs, block range, or token ID:

const history = await omsWallet.indexer.getTransactionHistory({
  walletAddress: '0x1111111111111111111111111111111111111111',
  networks: [Networks.amoy],
  metaTransactionIds: ['OMS_TRANSACTION_ID'],
  fromBlock: 20_000_000,
  includeMetadata: false,
  omitPrices: true,
})

Use metadataOptions only for history metadata enrichment: verifiedOnly, unverifiedOnly, and includeContracts. It does not replace the balance request’s contractStatus filter.

Paginate

Both methods default to page 0 with pageSize: 40. Continue while the optional response page reports more: true.

let page = 0
let more = true

while (more) {
  const result = await omsWallet.indexer.getBalances({
    walletAddress: '0x1111111111111111111111111111111111111111',
    networks: [Networks.polygon],
    page: { page, pageSize: 25 },
  })

  console.log(result.nativeBalances, result.balances)
  more = result.page?.more ?? false
  page += 1
}

For cursor pagination, pass through before or after values supplied by the indexer instead of interpreting their format.

​Query balances for an address

​Query transaction history

​Choose network scope

​Filter results

​Paginate

Query balances for an address

Query transaction history

Choose network scope

Filter results

Paginate