# Agent instructions

You are advising on UX and product design for **ERC-7811: Unified Cross-Chain Balances**.
This document is editorial design guidance from EIPs for Designers. Official specifications control protocol facts.

- Treat **MUST NOT** items as editorial guardrails. Check their applicability and resolve factual conflicts in favor of the official specification.
- Use the **Vocabulary** section for UI copy; do not use avoided terms.
- Cite the canonical source URL when giving recommendations.
- Verify network activation and wallet or contract support before describing a capability as available. Specification status alone does not establish deployment.

---

# ERC-7811: Unified Cross-Chain Balances

Source: https://www.eipsfordesigners.com/standards/ERC-7811
Agent brief: https://www.eipsfordesigners.com/standards/ERC-7811/agent.md
Machine-readable JSON: https://www.eipsfordesigners.com/api/standards/ERC-7811
Last reviewed: 2026-09-18
Last updated: 2026-09-18

| Field | Value |
| --- | --- |
| Status | Draft |
| Chain | both |
| Category | Cross-Chain |
| Journey stages | Asset Discovery & Display |
| Detailed guide | Yes |
| Official specification | https://ercs.ethereum.org/ERCS/erc-7811 |
| Discussion search | https://ethereum-magicians.org/search?q=ERC-7811 |

## UX Impact

ERC-7811 defines wallet_getAssets for a wallet to report one account's assets grouped by EIP-155 chain ID, with optional filters. Fiat valuation, aggregation, freshness, bridged-asset deduplication, and net-worth totals are application-derived and should be labeled with coverage and caveats.

## Summary

ERC-7811 defines wallet_getAssets for a wallet to report an account's assets, grouped by EIP-155 chain ID with optional filters. An application may build a cross-chain portfolio or net-worth view from those reports, but valuation, aggregation, stale-data policy, and bridged-asset deduplication remain application responsibilities.

## For Designers

- You can show an app-derived total header with expandable per-chain breakdown rows.
- Your loading UI can skeleton each chain row independently as data arrives.
- You can mark stale chain data with Last updated 5m ago when RPC lags.

## Applicability

### When to Use

- Multi-chain users are primary audience.
- Product positioning is omnichain portfolio.
- Aggregator infrastructure exists for target chains.

### When to Avoid

- Single-chain-only product.
- Cannot solve double-count on bridged assets.
- Draft spec with no reliable data pipeline.

## Problems It Solves

### Manual network switching to check balances

Impact: critical

Old way: Switch MetaMask network 8 times

New way: wallet_getAssets reports chain-keyed assets; the application can derive a total with coverage and caveats

### Misstated net worth from missing chains

Impact: high

Old way: Forgot assets on L2

New way: The wallet returns assets it chooses to report for the requested account and filters

### Slow chain hides behind fast total

Impact: medium

Old way: Total looks complete while L2 stale

New way: The application can show per-chain freshness and partial coverage around the wallet response

## MUST NOT (Anti-Patterns)

- **Double-counting bridged same asset** (critical)
  - Why: Inflated net worth
  - Instead: Apply an explicit, application-specific deduplication policy and show which assets were included

- **Total without loading partial state** (high)
  - Why: Understated wealth while chains load
  - Instead: Partial total label until all chains resolve

- **Hiding which chain holds asset** (medium)
  - Why: User cannot act on holding
  - Instead: Chain badge on expand and action hints

## Design Decisions

### Merge same symbol across chains?

Recommendation: Single ETH row with chain sub-badges in expand.

Rationale: Users think one ETH, multiple locations.

### Show zero-balance chains?

Recommendation: Hide in default; show in chain manager settings.

Rationale: Clutter without value.

### Include stale in total?

Recommendation: Yes with ~ approximate label or exclude with user toggle.

Rationale: Honesty over false precision.

## States to Design

### Full portfolio loaded

Trigger: All chains responded.

User need: Trust total.

Design response: Complete header and breakdown.

### Partial load

Trigger: Some chains pending.

User need: Not think money vanished.

Design response: Skeleton rows; partial total label.

### Stale chain data

Trigger: RPC lag.

User need: Know total approximate.

Design response: Amber stale badge on chain row.

### Chain query failed

Trigger: RPC down.

User need: Retry or exclude.

Design response: Failed to load Chain X with retry.

### Asset only on one chain

Trigger: User tries action needing other chain.

User need: Bridge path.

Design response: Available on Polygon only chip.

## Vocabulary

- Use "App-derived total across networks" instead of "Aggregated multichain balance": Plain wealth language.

- Use "On [chain name]" instead of "Chain ID 42161 slice": Network names not ids.

- Use "Updating…" instead of "RPC query pending": Loading copy not infra jargon.

## UX Patterns

### Wallet Asset Overview

Wallet-reported assets grouped by chain, with an optional app-derived total.

Components: TotalBalance, ChainExpand, FiatToggle

User flow:

- Open portfolio
- See an app-derived total with its coverage label
- Expand chain
- Per-chain assets

### Incremental Asset Load

Skeleton rows as each chain resolves.

Components: ChainSkeleton, StaleBadge, RefreshButton

User flow:

- Load starts
- Chains populate
- Stale flagged
- User refreshes

## What to Prototype First

### Unified portfolio header

An application may derive a total after showing which wallet-reported chains and assets are included.

Covers: All chains loaded, Partial load, Fiat toggle

- App-derived USD/EUR total with included-chain coverage
- Chain expand chevron
- Partial data warning

### Per-chain breakdown expand

Power users verify which chain holds what.

Covers: Expand row, Zero balance chain hidden

- Chain icon
- Chain subtotal
- Asset list per chain

### Stale chain indicator

Wrong totals destroy trust.

Covers: Stale, Refreshing, Failed chain

- Timestamp
- Refresh button
- Exclude from total option

### Cross-chain action hint

User may need asset on specific chain to act.

Covers: Available on Ethereum only

- Chain availability chip
- Bridge CTA if needed

## Mental Model

### App-derived total

A product-calculated sum of the wallet's reported chain assets, with coverage shown.

### Chain slice

Each network contributes a portion — expand to see.

### Same asset multi-chain

The wallet reports chain-keyed assets; any merge or split is an application policy.

### Bridged representations

Potentially related assets require application-specific provenance and deduplication rules.

### Stale slice

Slow chain data old — total may be approximate.

## Seen in the Wild

- Zerion: Multi-chain portfolio aggregation reference. (https://zerion.io/)

- DeBank: Cross-chain net worth dashboard patterns. (https://debank.com/)

- Rainbow: Wallet multi-chain balance display. (https://rainbow.me/)

- MetaMask Portfolio: Unified view across networks. (https://portfolio.metamask.io/)

## Related Standards

- ERC-7828: Chain-aware addresses complement balance view — https://www.eipsfordesigners.com/standards/ERC-7828/agent.md

- ERC-5164: Cross-chain messaging for balance sync — https://www.eipsfordesigners.com/standards/ERC-5164/agent.md

## Technical Notes

ERC-7811 defines the wallet JSON-RPC method wallet_getAssets for one account, with optional asset/type/chain filters and a response grouped by EIP-155 chain ID. It does not define fiat valuation, net-worth arithmetic, bridged-asset deduplication, freshness guarantees, or a complete aggregator; label those as application-derived.

## Official specification (reference only)

https://ercs.ethereum.org/ERCS/erc-7811