> ## 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.

# Kotlin Balances & History

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

Use `client.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` values with `networks`, or omit `networks` and use `networkType`. When both are omitted, the indexer request defaults to mainnets.

## Get Balances

```kotlin theme={null}
import com.omsclient.kotlin_sdk.Network

val walletAddress = requireNotNull(client.wallet.walletAddress) {
    "No wallet selected"
}

val result = client.indexer.getBalances(
    walletAddress = walletAddress,
    networks = listOf(Network.POLYGON),
    contractAddresses = listOf("0x2222222222222222222222222222222222222222"),
    includeMetadata = true,
)

for (balance in result.nativeBalances) {
    println("${balance.symbol}: ${balance.balance}")
}

for (balance in result.balances) {
    println("${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`          | `List<Network>`               | Explicit SDK network values, such as `listOf(Network.POLYGON)`.                               |
| `networkType`       | `IndexerNetworkType`          | Network group used when `networks` is empty. Defaults to `IndexerNetworkType.MAINNETS`.       |
| `contractAddresses` | `List<String>`                | Optional token contract address filters. Omit them to query balances across contracts.        |
| `includeMetadata`   | `Boolean`                     | Whether token metadata should be included. Defaults to `true`.                                |
| `omitPrices`        | `Boolean?`                    | Whether price fields should be omitted.                                                       |
| `tokenIds`          | `List<String>`                | Optional token ID filter.                                                                     |
| `contractStatus`    | `ContractVerificationStatus?` | Optional contract verification filter.                                                        |
| `page`              | `TokenBalancesPageRequest`    | Optional pagination request. Defaults to page `0` with up to `40` entries.                    |

**Returns**

`getBalances` returns `TokenBalancesResult`.

| Field            | Type                 | Description                                      |
| ---------------- | -------------------- | ------------------------------------------------ |
| `status`         | `Int`                | HTTP status code from the indexer response.      |
| `page`           | `TokenBalancesPage?` | Pagination metadata from the indexer response.   |
| `nativeBalances` | `List<TokenBalance>` | Native token balances returned for the wallet.   |
| `balances`       | `List<TokenBalance>` | Token contract balances returned for the wallet. |

## Get Transaction History

```kotlin theme={null}
import com.omsclient.kotlin_sdk.Network

val walletAddress = requireNotNull(client.wallet.walletAddress) {
    "No wallet selected"
}

val history = client.indexer.getTransactionHistory(
    walletAddress = walletAddress,
    networks = listOf(Network.POLYGON),
    includeMetadata = true,
)

for (transaction in history.transactions) {
    println("${transaction.txnHash}: ${transaction.timestamp}")
}
```

**Parameters**

| Parameter            | Type                       | Description                                                                             |
| -------------------- | -------------------------- | --------------------------------------------------------------------------------------- |
| `walletAddress`      | `String`                   | Wallet address whose history should be fetched.                                         |
| `networks`           | `List<Network>`            | Explicit SDK network values.                                                            |
| `networkType`        | `IndexerNetworkType`       | Network group used when `networks` is empty. Defaults to `IndexerNetworkType.MAINNETS`. |
| `contractAddresses`  | `List<String>`             | Optional contract address filters.                                                      |
| `transactionHashes`  | `List<String>`             | Optional transaction hash filters.                                                      |
| `metaTransactionIds` | `List<String>`             | Optional wallet transaction ID filters, such as `txnId` returned by transaction APIs.   |
| `fromBlock`          | `Long?`                    | Optional starting block number.                                                         |
| `toBlock`            | `Long?`                    | Optional ending block number.                                                           |
| `tokenId`            | `String?`                  | Optional token ID filter.                                                               |
| `includeMetadata`    | `Boolean`                  | Whether token and contract metadata should be included. Defaults to `true`.             |
| `omitPrices`         | `Boolean?`                 | Whether price fields should be omitted.                                                 |
| `metadataOptions`    | `MetadataOptions?`         | Optional metadata enrichment filters.                                                   |
| `page`               | `TokenBalancesPageRequest` | Optional pagination request.                                                            |

**Returns**

`getTransactionHistory` returns `TransactionHistoryResult`.

| Field          | Type                 | Description                                    |
| -------------- | -------------------- | ---------------------------------------------- |
| `status`       | `Int`                | HTTP status code from the indexer response.    |
| `page`         | `TokenBalancesPage?` | Pagination metadata from the indexer response. |
| `transactions` | `List<Transaction>`  | Transactions returned for the wallet.          |

## Token Balance Shape

Each `TokenBalance` can include:

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

## Transaction Shape

Each `Transaction` can include:

| Field         | Type                         | Description                                             |
| ------------- | ---------------------------- | ------------------------------------------------------- |
| `txnHash`     | `String?`                    | Onchain transaction hash.                               |
| `blockNumber` | `Long?`                      | Block number.                                           |
| `blockHash`   | `String?`                    | Block hash.                                             |
| `chainId`     | `Long?`                      | Numeric chain ID.                                       |
| `metaTxnId`   | `String?`                    | Wallet transaction ID when available.                   |
| `transfers`   | `List<TransactionTransfer>?` | Token and native transfers detected in the transaction. |
| `timestamp`   | `String?`                    | Transaction timestamp.                                  |