> ## 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 data with the TypeScript OMS Wallet SDK.

Use `oms.indexer` for wallet balance reads. Requests use the project access key configured on `OMSClient`, and balance amounts are returned as raw base-unit strings.

## Get Token Balances

```typescript theme={null}
import { Networks } from '@0xsequence/typescript-sdk'
import type { Address } from 'viem'

const walletAddress = oms.wallet.walletAddress
const tokenContract = '0xTokenContract' as Address

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

const result = await oms.indexer.getTokenBalances({
  network: Networks.polygon,
  contractAddress: tokenContract,
  walletAddress,
  includeMetadata: true,
})

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

**Parameters**

| Parameter         | Type                                                | Description                                                                                   |
| ----------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `network`         | `Network`                                           | SDK network entry, such as `Networks.polygon` or `Networks.amoy`.                             |
| `contractAddress` | `string` or undefined                               | Optional token contract address filter. Omit it to query balances across contracts.           |
| `walletAddress`   | `string`                                            | Wallet address to inspect. This can be the active non-custodial wallet or any wallet address. |
| `includeMetadata` | `boolean`                                           | Whether token metadata should be included in the response.                                    |
| `page`            | `{ page?: number; pageSize?: number }` or undefined | Optional pagination request. Defaults to page `0` with up to `40` entries.                    |

**Returns**

`getTokenBalances` returns `Promise<TokenBalancesResult>`.

| Field      | Type                             | Description                                    |
| ---------- | -------------------------------- | ---------------------------------------------- |
| `status`   | `number`                         | HTTP status code from the balance response.    |
| `page`     | `TokenBalancesPage` or undefined | Pagination metadata from the balance response. |
| `balances` | `TokenBalance[]`                 | Balances returned for the wallet.              |

## Get Native Token Balance

```typescript theme={null}
import { Networks } from '@0xsequence/typescript-sdk'

const nativeBalance = await oms.indexer.getNativeTokenBalance({
  network: Networks.amoy,
  walletAddress,
})

console.log(nativeBalance?.balance)
```

**Parameters**

| Parameter       | Type      | Description                                                       |
| --------------- | --------- | ----------------------------------------------------------------- |
| `network`       | `Network` | SDK network entry, such as `Networks.polygon` or `Networks.amoy`. |
| `walletAddress` | `string`  | Wallet address to inspect.                                        |

**Returns**

`getNativeTokenBalance` returns `Promise<TokenBalance | undefined>`.

It returns `undefined` when the response does not include a native balance.

## 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.                                           |
| `balance`         | `string` or undefined | Raw base-unit balance as a string.                                               |
| `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.                                                                |