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.

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

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.

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

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.

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

For an EVM wallet holding USDC across multiple chains:

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

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.

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:

{
  "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.