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

# getBalances

> Retrieves a flat list of token balances for the wallet on a specific chain.

## Function Signature

```dart theme={null}
Future<List<PortalBalance>> getBalances(String chainId)
```

## Description

Returns a flat list of token balances for the wallet on the specified chain — each entry includes a contract address, balance, and (optionally) token name and symbol.

This is a lighter-weight alternative to [`getAssets`](./getassets) when you only need basic balance information without the additional metadata (logos, decimals, asset type) that `getAssets` returns.

## Parameters

| Parameter | Type     | Required | Description                                                            |
| --------- | -------- | -------- | ---------------------------------------------------------------------- |
| `chainId` | `String` | Yes      | The chain ID in CAIP-2 format (e.g., `eip155:1` for Ethereum mainnet). |

## Returns

**`List<PortalBalance>`** — A list of token balances on the chain.

### PortalBalance

| Property          | Type      | Description                                                   |
| ----------------- | --------- | ------------------------------------------------------------- |
| `contractAddress` | `String`  | The contract address of the token.                            |
| `balance`         | `String`  | The token balance as a string (in the token's smallest unit). |
| `name`            | `String?` | Optional token name.                                          |
| `symbol`          | `String?` | Optional token symbol (e.g., `USDC`).                         |

## Example

### Basic balance check

```dart theme={null}
import 'package:portal_flutter/portal_flutter.dart';

final portal = Portal();

final balances = await portal.getBalances('eip155:1');

for (final balance in balances) {
  print('${balance.symbol ?? balance.contractAddress}: ${balance.balance}');
}
```

### Multi-chain balances

```dart theme={null}
Future<void> printBalancesAcrossChains(Portal portal) async {
  final chains = ['eip155:1', 'eip155:137', 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp'];

  for (final chainId in chains) {
    final balances = await portal.getBalances(chainId);
    print('--- $chainId ---');
    for (final balance in balances) {
      final label = balance.symbol ?? balance.name ?? balance.contractAddress;
      print('  $label: ${balance.balance}');
    }
  }
}
```

### Filtering non-zero balances

```dart theme={null}
final balances = await portal.getBalances('eip155:1');

final nonZero = balances
    .where((b) => (BigInt.tryParse(b.balance) ?? BigInt.zero) != BigInt.zero)
    .toList();

print('${nonZero.length} tokens with non-zero balances');
```

## Errors

Throws a `PortalException` on failure:

| Code                 | Description                 |
| -------------------- | --------------------------- |
| `NOT_INITIALIZED`    | Portal was not initialized. |
| `GET_BALANCES_ERROR` | Failed to fetch balances.   |

```dart theme={null}
try {
  final balances = await portal.getBalances('eip155:1');
  // Use the balances...
} on PortalException catch (e) {
  print('Failed to fetch balances: ${e.code} - ${e.message}');
}
```

## Implementation Notes

* Balances are returned as raw string values in the token's smallest unit (e.g., wei for ETH, lamports for SOL). Apply token decimals when displaying balances to users.
* Both EVM and Solana chains are supported — pass the appropriate CAIP-2 chain ID.
* For richer metadata (logos, asset type, native vs. token grouping), use [`getAssets`](./getassets) instead.
* Consider rate limiting when polling balances frequently.

## Related

* [getAssets](./getassets) — richer per-asset metadata (logos, decimals, native + token grouping)
* [getNftAssets](./getnftassets)
* [getTransactions](./gettransactions)