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

# tRPC V2 Wallet Balances API

> Backend-owned connected wallet balance lookup for money-movement UX.

The `v2.wallets.balances` procedure returns a normalized, priced balance view for
the active connected wallet session. It is intended for product UX surfaces such
as deposit asset pickers, Max and percentage shortcuts, USD estimates, and
disabled states.

* Base endpoint: `POST /v1/trpc`
* Procedure: `v2.wallets.balances`
* Auth: wallet session plus app access
* Supported chains: EIP-155 assets
* Scope: active session wallet only
* Asset limit: 100 CAIP asset ids per request

This response is advisory UI state. Final execution validation still happens at
simulation/send time, because a user can move funds after the balance snapshot is
read.

## Input

```json theme={null}
{
  "address": "0x1111111111111111111111111111111111111111",
  "assetIds": [
    "eip155:8453/erc20:0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "eip155:8453/slip44:60"
  ],
  "chainIds": [8453]
}
```

* `address` is optional when the active wallet session already resolves an EVM
  wallet address.
* When supplied, `address` must match the active wallet session. The procedure
  must not be used as a generic wallet-balance oracle.
* `assetIds` must be CAIP asset ids from Glider's supported asset universe.
* `chainIds` optionally narrows the lookup to one or more EIP-155 chains.

## Response

```json theme={null}
{
  "address": "0x1111111111111111111111111111111111111111",
  "asOf": "2026-05-12T00:00:00.000Z",
  "balances": [
    {
      "assetId": "eip155:8453/erc20:0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "chainId": 8453,
      "symbol": "USDC",
      "contractAddress": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "decimals": 6,
      "rawAmount": "4200000000",
      "amount": "4200",
      "usdPrice": "1",
      "usdValue": "4200.00",
      "stale": false
    }
  ],
  "warnings": []
}
```

## Warning Kinds

* `INVALID_ASSET_ID`: the supplied asset id could not be parsed.
* `MISSING_ASSET`: the asset is not in the supported asset universe.
* `BLOCKLISTED_ASSET`: the asset is blocklisted and should not be offered.
* `UNSUPPORTED_CHAIN`: the asset is not currently readable through the connected
  wallet balance service.
* `RPC_ERROR`: backend balance reading failed for a chain.
* `MISSING_PRICE`: the balance was readable, but no USD price was available.

## Runtime Notes

The backend owns RPC quality, batching, retries, supported-asset filtering,
decimal normalization, price hydration, and short-lived cache behavior. Browser
wallet libraries still own connected wallet identity, chain/account state, and
signing or transaction submission.

## Multi-VM Balance Procedure

`v2.wallets.multiVmBalances` is the VM-discriminated balance contract for new
connected-wallet UX. It leaves the legacy EVM `balances` procedure stable and
requires each wallet and asset request to carry VM and chain identity together.

```json theme={null}
{
  "wallet": {
    "vm": "svm",
    "address": "So11111111111111111111111111111111111111112"
  },
  "assets": [
    {
      "assetId": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/spl:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "chain": {
        "vm": "svm",
        "chainNamespace": "solana",
        "chainReference": "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"
      }
    }
  ]
}
```

The selected wallet must be linked to the session. EVM addresses are normalized
case-insensitively; Solana base58 addresses are preserved exactly.

## Dashboard Deposit Balances

`v2.wallets.depositBalances` is the product-facing procedure for dashboard
deposit asset rows. It resolves the current supported deposit universe for the
selected wallet VM, reads balances through `multiVmBalances`, and annotates each
row with capability metadata:

* `capability.balanceRead`: whether the balance was available.
* `capability.depositExecution`: whether direct submit is enabled for the asset.
* `capability.reason`: user-facing disabled reason when a row cannot execute.

Current behavior:

* Base USDC EVM balance rows can execute direct deposits when the destination
  Investing Account has a matching EVM vault.
* Solana USDC balance rows are read-only. SVM transaction preparation/submission
  is intentionally not enabled in this slice.
* Missing assets, blocked assets, unsupported chains, and RPC failures return
  chain-scoped warnings and disable execution.

```json theme={null}
{
  "mode": "supported_deposit_assets",
  "wallet": {
    "vm": "svm",
    "address": "So11111111111111111111111111111111111111112"
  },
  "investingAccountId": "portfolio_123"
}
```