> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polygon.technology/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript Balances & History

> Read wallet balance and transaction history data with the TypeScript OMS Wallet SDK.

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

```typescript theme={null}
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

```typescript theme={null}
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.                                  |