Balances - Polygon Developer Docs

Balance reads are read-only and accept any address. They need no authenticated wallet, no credential, and none of the durable storage that stateful operations require.

Read balances

import { IndexerClient } from '@polygonlabs/oms-server-wallet-sdk'

const indexer = new IndexerClient('YOUR_PUBLISHABLE_KEY', omsFetch)

const balances = await indexer.getBalances('0x1111111111111111111111111111111111111111')

for (const item of balances.items) {
  console.log(item.chainId, item.symbol, item.balance)
}

IndexerClient takes the same publishable key and origin-setting fetch as the wallet transport. It is independent of ServerWallet, so you can construct it on its own.

Result shape

export interface Balance {
  chainId: number
  asset: string
  name: string
  symbol: string
  balance: string
  decimals?: number
  balanceUSD?: string
}

export interface Balances {
  items: Balance[]
  errors: { chainId: number; message: string }[]
  nextPage?: number
  fetchedAt: string
}

balance is a string in the asset’s base units. Convert it with the asset’s decimals for display. decimals and balanceUSD are optional and absent when the indexer does not know them. Do not default an unknown decimals to 18: an unknown precision makes the balance undisplayable, and guessing it misreports the amount by orders of magnitude. fetchedAt records when the result was read, which matters because balances move independently of your read.

Errors are not zero balances

errors reports the chains that failed, while items holds the results that succeeded. A chain in errors has an unknown balance, not a zero balance.

if (balances.errors.length > 0) {
  // These chains are unknown, not empty. Retry or report them as unavailable.
  console.warn('Incomplete result:', balances.errors)
}

Treating a failed chain as zero understates holdings, so keep the two apart in anything that sums balances or decides whether funds exist.

Paginate

let page = 0
const items = []

for (;;) {
  const result = await indexer.getBalances(address, page)
  items.push(...result.items)
  if (result.nextPage === undefined) break
  page = result.nextPage
}

nextPage is absent on the final page. A result with a nextPage is incomplete, so follow it before reporting a total.

Supported networks

import { CHAINS } from '@polygonlabs/oms-server-wallet-sdk'

CHAINS lists the networks this SDK build accepts, each with its id, name, native symbol, and block explorer. Read it rather than hardcoding a list, and expect a chainId outside it to raise UNSUPPORTED_CHAIN. For the networks available to OMS wallets generally, see Supported networks.

​Read balances

​Result shape

​Errors are not zero balances

​Paginate

​Supported networks

Read balances

Result shape

Errors are not zero balances

Paginate

Supported networks