TypeScript Balances & History - Polygon Developer Docs

Use oms.indexer for wallet balance and transaction history reads. Requests use the publishable key configured on OMSClient, and balance amounts are returned as raw base-unit strings. Pass explicit SDK Network entries with networks, or omit networks and use networkType. When both are omitted, the indexer request defaults to mainnets.

Get Balances

import { Networks } from '@0xsequence/typescript-sdk'

const walletAddress = oms.wallet.walletAddress

if (!walletAddress) {
  throw new Error('No active wallet session')
}

const result = await oms.indexer.getBalances({
  walletAddress,
  networks: [Networks.polygon],
  contractAddresses: ['0x2222222222222222222222222222222222222222'],
  includeMetadata: true,
})

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

for (const balance of result.balances) {
  console.log(balance.contractAddress, balance.balance)
}

Parameters

Parameter	Type	Description
`walletAddress`	`string`	Wallet address to inspect. This can be the active non-custodial wallet or any wallet address.
`networks`	`Network[]` or undefined	Explicit SDK network entries, such as `[Networks.polygon]`.
`networkType`	`'MAINNETS'`, `'TESTNETS'`, or `'ALL'`	Network group used when `networks` is omitted. Defaults to `'MAINNETS'`.
`contractAddresses`	`string[]` or undefined	Optional token contract address filters. Omit them to query balances across contracts.
`includeMetadata`	`boolean` or undefined	Whether token metadata should be included. Defaults to `true`.
`omitPrices`	`boolean` or undefined	Whether price fields should be omitted.
`tokenIds`	`string[]` or undefined	Optional token ID filter.
`contractStatus`	`ContractVerificationStatus` or undefined	Optional contract verification filter.
`page`	`TokenBalancesPage` or undefined	Optional pagination request. Defaults to page `0` with up to `40` entries.

Returns getBalances returns Promise<BalancesResult>.

Field	Type	Description
`status`	`number`	HTTP status code from the indexer response.
`page`	`TokenBalancesPage` or undefined	Pagination metadata from the indexer response.
`nativeBalances`	`TokenBalance[]`	Native token balances returned for the wallet.
`balances`	`TokenBalance[]`	Token contract balances returned for the wallet.

Get Transaction History

import { Networks } from '@0xsequence/typescript-sdk'

const walletAddress = oms.wallet.walletAddress

if (!walletAddress) {
  throw new Error('No active wallet session')
}

const history = await oms.indexer.getTransactionHistory({
  walletAddress,
  networks: [Networks.polygon],
  includeMetadata: true,
})

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

Parameters

Parameter	Type	Description
`walletAddress`	`string`	Wallet address whose history should be fetched.
`networks`	`Network[]` or undefined	Explicit SDK network entries.
`networkType`	`'MAINNETS'`, `'TESTNETS'`, or `'ALL'`	Network group used when `networks` is omitted. Defaults to `'MAINNETS'`.
`contractAddresses`	`string[]` or undefined	Optional contract address filters.
`transactionHashes`	`string[]` or undefined	Optional transaction hash filters.
`metaTransactionIds`	`string[]` or undefined	Optional wallet transaction ID filters, such as `txnId` returned by transaction APIs.
`fromBlock`	`number` or undefined	Optional starting block number.
`toBlock`	`number` or undefined	Optional ending block number.
`tokenId`	`string` or undefined	Optional token ID filter.
`includeMetadata`	`boolean` or undefined	Whether token and contract metadata should be included. Defaults to `true`.
`omitPrices`	`boolean` or undefined	Whether price fields should be omitted.
`metadataOptions`	`MetadataOptions` or undefined	Optional metadata enrichment filters.
`page`	`TokenBalancesPage` or undefined	Optional pagination request.

Returns getTransactionHistory returns Promise<TransactionHistoryResult>.

Field	Type	Description
`status`	`number`	HTTP status code from the indexer response.
`page`	`TokenBalancesPage` or undefined	Pagination metadata from the indexer response.
`transactions`	`Transaction[]`	Transactions returned for the wallet.

Token Balance Shape

Each TokenBalance can include:

Field	Type	Description
`contractType`	`string` or undefined	Token contract type, such as ERC20, ERC721, or `NATIVE`.
`contractAddress`	`string` or undefined	Token contract address. Native token balances do not include a contract address.
`accountAddress`	`string` or undefined	Wallet address queried.
`tokenId`	`string` or undefined	Token ID for token types that use IDs.
`name`	`string` or undefined	Token name when returned by the indexer.
`symbol`	`string` or undefined	Token symbol when returned by the indexer.
`balance`	`string` or undefined	Raw base-unit balance as a string.
`balanceUSD`	`string` or undefined	Balance value in USD when price data is returned.
`priceUSD`	`string` or undefined	Token price in USD when price data is returned.
`priceUpdatedAt`	`string` or undefined	Timestamp for the returned price data.
`blockHash`	`string` or undefined	Block hash for the balance snapshot.
`blockNumber`	`number` or undefined	Block number for the balance snapshot.
`chainId`	`number` or undefined	Numeric chain ID.
`uniqueCollectibles`	`string` or undefined	Unique collectible count for NFT summary rows.
`isSummary`	`boolean` or undefined	Whether the row is a summary balance.
`contractInfo`	`TokenContractInfo` or undefined	Contract metadata when `includeMetadata` is true.
`tokenMetadata`	`TokenMetadata` or undefined	Token metadata when `includeMetadata` is true.

Transaction Shape

Each Transaction can include:

Field	Type	Description
`txnHash`	`string`	Onchain transaction hash.
`blockNumber`	`number`	Block number.
`blockHash`	`string`	Block hash.
`chainId`	`number`	Numeric chain ID.
`metaTxnId`	`string` or undefined	Wallet transaction ID when available.
`transfers`	`TransactionTransfer[]` or undefined	Token and native transfers detected in the transaction.
`timestamp`	`string`	Transaction timestamp.

​Get Balances

​Get Transaction History

​Token Balance Shape

​Transaction Shape

Get Balances

Get Transaction History

Token Balance Shape

Transaction Shape