Icon Resolution

Crypto icons need good defaults and clean escape hatches. Common networks should work with a chainId, while obscure networks and long-tail tokens should still render without broken images.

Goals

• chainId should be enough for supported networks.
• Explicit app data should always win.
• Unknown assets should degrade to readable fallbacks.
• Components should not require one specific icon provider.
• Token identity should not rely on symbol alone.

Network Icons

Networks are identified by chainId, so NetworkLogo resolves in this order:

1. src
2. Crypto icons adapter result for the chainId (built-in logos for supported chains)
3. fallback
4. symbol
5. name
6. chainId
7. ?

<NetworkLogo chainId={8453} />

Supported chains render built-in logos automatically. If your app needs an unsupported chain, pass a src, name, symbol, or fallback.

<NetworkLogo
  chainId={7777777}
  name="Zora"
  symbol="ZORA"
  src="/chains/zora.svg"
/>

Token Icons

Tokens are harder than networks. A symbol is not a unique identifier: USDC can exist on multiple chains, and unknown tokens often share symbols with known assets.

TokenLogo resolves in this order:

1. src
2. Crypto icons adapter result for chainId + address
3. fallback
4. symbol
5. name
6. address
7. ?

Prefer token metadata from your app, token list, indexer, or API:

<TokenLogo
  chainId={8453}
  address="0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"
  symbol="USDC"
  name="USD Coin"
  src={token.logoURI}
/>

Provider Strategy

onchain-ui components are provider-agnostic. All icon lookups flow through the crypto-icons adapter — one editable file that can map assets to an icon package, app-owned SVGs, token-list URLs, or another provider, while the component contract stays the same:

<NetworkLogo chainId={8453} />
<TokenLogo symbol="USDC" src={token.logoURI} />

Use an icon package when it gives your app better coverage, but keep explicit overrides available for obscure chains and tokens.

Recommended Data Shape

type NetworkMetadata = {
  chainId: number
  name: string
  symbol?: string
  logoURI?: string
}

type TokenMetadata = {
  chainId: number
  address?: `0x${string}`
  symbol: string
  name?: string
  logoURI?: string
}

That shape lets components render good defaults while preserving enough identity for product code, tables, token selectors, and portfolio rows.