# Understanding balances

When viewing wallet balances in Ripple Custody (Wallet), 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 [Configure transaction freeze controls](/products/wallet/compliance/transaction-freeze) 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 Ripple Custody (Wallet) console from:

* The vault overview, which displays the **Balance** of each wallet in the vault
* The **Assets** tab of an individual wallet, which shows the **Total**, **Available**, **Pending**, and **Frozen** balance of each asset. Turn on **Show all assets** to include assets with a zero balance.


## Refreshing balances

**Required role:** Owner, Administrator, or Proposer.

To manually refresh a wallet's balances:

* Navigate to the wallet page
* Select the **Refresh balances** 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 Ripple Custody (Wallet) 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 Ripple Custody (Wallet)
* Contact support to have the token added to your wallet


On EVM chains and Tron, Ripple Custody (Wallet) doesn't detect native assets, such as ETH, that a smart contract sends to your wallet. A block explorer lists these transfers as internal transactions. Your Ripple Custody (Wallet) balance includes them only after you refresh the wallet's balances, and the transaction history never includes them. See [Native-asset deposits sent by smart contracts](/products/wallet/vaults-and-wallets/supported-blockchains-and-tokens#native-asset-deposits-sent-by-smart-contracts).

## 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. `eq` is case-sensitive; `contains`, `startsWith`, and `endsWith` aren't. 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`. |
| `filter.source.eq`, `.notEq`, `.in`, `.notIn` | Filter by asset source: `ASSET_SOURCE_LEGACY`, `ASSET_SOURCE_AUTO`, `ASSET_SOURCE_COINGECKO`, `ASSET_SOURCE_PALISADE`, or `ASSET_SOURCE_CUSTOMER`. |
| `search` | Case-insensitive search across asset ID, symbol, name, contract address, blockchain value (such as `XRP_LEDGER`), source label (such as `coingecko`), and standard label (such as `native`). |
| `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`, Ripple Custody (Wallet) 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](/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",
      "rate": "1",
      "fiatValue": "200",
      "availableBalance": "200",
      "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` is `null` unless you set a `pagination` parameter. It includes page tokens only when there are more pages. 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
To retrieve balances programmatically, see [Check balances](/products/wallet/vaults-and-wallets/wallets/manage-wallets-api#check-balances-via-the-api) in Manage wallets via the API.