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.

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

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

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

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