# Understanding balances

When viewing wallet balances in Wallet-as-a-Service, you'll see different balance types that reflect the availability and status of your funds.

## Balance types

| Balance Type | Description |
|  --- | --- |
| **Total** | The sum of all funds in the wallet (available + frozen + pending) |
| **Available** | Funds that can be used immediately for outgoing transactions |
| **Frozen** | Funds from transactions that have been frozen for compliance review |
| **Pending** | Funds from transactions currently awaiting a freeze decision |


## When balances differ

Your available balance may be less than your total balance when:

* **Transactions are frozen**: Incoming deposits have been manually frozen or automatically frozen for review. These funds remain in the "Frozen" balance until unfrozen. See [Manage transactions](/pt-br/products/wallet/user-interface/transactions/manage-transactions) for more information on freezing transactions.
* **Transactions are pending**: Incoming transactions that are awaiting a freeze decision. Once confirmed, these amounts move to either "Available" or "Frozen".


## Viewing balances

You can view your wallet balances in the Wallet-as-a-Service console from:

* The vault overview, which displays balances for all wallets
* Individual wallet pages, which show balances for that specific wallet


## Refreshing balances

To manually refresh a wallet's balances:

* Navigate to the wallet page
* Click the refresh icon next to the wallet balance
* Balances will update automatically once the sync completes


Manual refresh is useful when a balance appears outdated or incorrect

### Limitations

Manual refresh only updates balances for tokens that Wallet-as-a-Service is already tracking for that wallet. It will not detect new tokens that have never been seen before.

If you've received a token that isn't appearing in your wallet:

* The token may not yet be tracked by Wallet-as-a-Service
* Contact support to have the token added to your wallet


## Multi-chain balances (EVM wallets)

For EVM wallets, balances are tracked separately for each blockchain where you hold assets. This provides complete visibility into your cross-chain holdings.

### Per-chain balance breakdown

| Aspect | Description |
|  --- | --- |
| **Chain-specific balances** | See exactly how much you hold on each blockchain (e.g., 500 USDC on Ethereum, 200 USDC on Arbitrum) |
| **Aggregated totals** | Total holdings automatically sum across all chains |
| **Fiat valuations** | Portfolio value calculated across all chains in your preferred currency |


### Example balance view

For an EVM wallet holding USDC across multiple chains:

| Blockchain | Asset | Quantity |
|  --- | --- | --- |
| Ethereum | USDC | 500.00 |
| Arbitrum | USDC | 200.00 |
| Polygon | USDC | 150.00 |
| **Total** | **USDC** | **850.00** |


## Filter, search, and page balances

To narrow or page the balances that the `GET /v2/vaults/{vaultId}/wallets/{walletId}/balances` operation returns, add these optional query parameters.

| Parameter | Description |
|  --- | --- |
| `filter.blockchain.eq`, `.notEq`, `.in`, `.notIn` | Filter by blockchain, such as `ETHEREUM` or `ARBITRUM`. |
| `filter.contract.eq`, `.notEq`, `.in`, `.notIn`, `.contains`, `.startsWith`, `.endsWith`, `.isNull` | Filter by token contract address. To return native assets only, set `filter.contract.isNull=true`. |
| `filter.symbol.*` | Filter by asset symbol. Supports the same operators as `filter.contract`. |
| `filter.standard.eq`, `.notEq`, `.in`, `.notIn` | Filter by asset standard: `NATIVE`, `ERC20`, `ISSUED_CURRENCY`, `ERC721`, `SPL`, or `CUSTOM`. |
| `search` | Case-insensitive search across asset ID, symbol, name, contract address, blockchain name, source label, and standard label. |
| `pagination.pageSize` | The number of results per page. The default is 50, and the maximum is 1,000. |
| `pagination.pageToken` | The page token from the `pagination.nextPageToken` or `pagination.previousPageToken` field of an earlier response. |
| `pagination.orderBy` | The field to sort by: `symbol`, `name`, `blockchain`, `contract_address`, `source`, or `standard`. |
| `pagination.order` | The sort direction: `SORT_ORDER_ASC` or `SORT_ORDER_DESC`. |
| `refreshRegistryMetadata` | When `true`, Wallet-as-a-Service bypasses cached registry metadata for this wallet's assets. If registry resolution fails, the request fails. Use this parameter only for a read immediately after a [registry](/pt-br/products/wallet/changelogs/asset-registry) change. |


A balance must match every filter you set, and `search` if you set it. In an `in` filter, a balance must match at least one of the values. Setting any `pagination` parameter turns on paging. If you don't set any of these parameters, the operation keeps its original behavior.

**Example:** Return the ERC-20 balances on Arbitrum, 20 per page, sorted by symbol.

```bash
curl -X GET "https://api.sandbox.palisade.co/v2/vaults/$VAULT_ID/wallets/$WALLET_ID/balances?filter.blockchain.eq=ARBITRUM&filter.standard.eq=ERC20&pagination.pageSize=20&pagination.orderBy=symbol&pagination.order=SORT_ORDER_ASC" \
  -H "Authorization: Bearer $TOKEN"
```

**Response:**

```json
{
  "currencyCode": "USD",
  "aggregatedFiatValue": "200.00",
  "balances": [
    {
      "asset": {
        "symbol": "USDC",
        "displaySymbol": "USDC",
        "name": "USD Coin",
        "blockchain": "ARBITRUM",
        "standard": "ERC20",
        "contract": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
        "decimals": 6
      },
      "balance": "200.00",
      "availableBalance": "200.00",
      "pendingBalance": "0",
      "frozenBalance": "0"
    }
  ],
  "pagination": {
    "total": 1
  }
}
```

- `aggregatedFiatValue` covers every balance that matches your filters, not only the current page. It's `"0"` when nothing matches.
- `pagination` appears only in responses to paged requests. Pass `pagination.nextPageToken` as `pagination.pageToken` to fetch the next page.
- A request that matches no balances returns HTTP 200 with an empty `balances` array.
- `asset.displaySymbol` holds the symbol with the capitalization its source uses, for example `weETH`. Use it when you show the symbol to users.


API documentation
See the [Wallet-as-a-Service API reference](/pt-br/products/wallet/api-docs/palisade-api/palisade-api) for information on how to retrieve balance information via the API.