# Token list surfaces

The explorer uses two public token-list endpoints. Application code should pick the list through `getTokenListForSurface()` / `tokensApi.listForSurface()` rather than hard-coding `/api/config/token-list`.

| Surface | Endpoint | Use when |
|---------|----------|----------|
| `wallet` | `/api/v1/report/token-list?chainId=138` (fallback: config) | Wallet SSR, MetaMask watch list, featured-token dedup inputs |
| `catalog` | report (fallback: config) | `/tokens`, search token inference, homepage price feed curation |
| `extended` | `/api/config/token-list` | Full Metamask dual-chain catalog, provenance lookup merge, operations/liquidity/system/pools inventory |

Report list is the canonical Chain 138 trading set (31 tokens live). Config list is the extended catalog (190+ entries across chains).

## Page mapping

| Page / surface | Surface | Notes |
|----------------|---------|-------|
| `/wallet` | `wallet` | SSR + MetaMask watch list |
| `/tokens`, `/search`, homepage price feed | `catalog` | Canonical trading set with config fallback |
| `/liquidity`, `/operations`, `/system`, `/pools` | `extended` | Full catalog with `TokenListSurfaceNote` label |