> Feedback: If these docs are stale, missing, or confusing, post sanitized feedback to `https://docs.tempo.xyz/api/feedback` with `source: "mcp"`, a short `message`, and any relevant `toolName`, `relatedResource`, or `client`.
import { TokenListDemo } from '../../../components/TokenList.tsx'

# Tempo Token List Registry

A [Uniswap Token Lists](https://tokenlists.org)-compatible API for token metadata and icons on Tempo.

As an example, here's Tempo's tokenlist, fetched from [tokenlist.tempo.xyz/list/4217](https://tokenlist.tempo.xyz/list/4217):

<TokenListDemo />

## Endpoints

| Endpoint | Description |
|----------|-------------|
[`/list/{chain_id}`](https://tokenlist.tempo.xyz/list/4217) | Token list for a chain |
[`/asset/{chain_id}/{id}`](https://tokenlist.tempo.xyz/asset/4217/pathUSD) | Get a single token by symbol or address​
[`/icon/{chain_id}`](https://tokenlist.tempo.xyz/icon/4217) | Chain icon (SVG) |
[`/icon/{chain_id}/{address}`](https://tokenlist.tempo.xyz/icon/4217/0x20c0000000000000000000000000000000000000) | Token icon (SVG) |

| Chain | `chain_id` |
|-------|------------|
| Mainnet | `4217` |
| Testnet (Moderato) | `42431` |

## Adding a New Token

1. **Fork** [tempoxyz/tempo-apps](https://github.com/tempoxyz/tempo-apps)

2. **Add token** to `data/<chain_id>/tokenlist.json` in `apps/tokenlist`:
   ```json
   {
     "name": "piUSD",
     "symbol": "PiUSD",
     "decimals": 6,
     "chainId": 4217,
     "address": "0x...",
     "extensions": {
       "chain": "tempo",
       "coingeckoId": "pi-usd"
     }
   }
   ```

3. **Add icon** to `data/<chain_id>/icons/<address>.svg` (lowercase address) in `apps/tokenlist`

   Separately, TIP-20 tokens can also carry an optional on-chain `logoURI` ([TIP-1026](https://tips.sh/1026)) that wallets and explorers read directly from the token contract. Because that icon is fetched from an untrusted source, TIP-1026 recommends a square, rasterized PNG or WebP (max 256 bytes; `https`, `http`, `ipfs`, or `data` scheme). Setting it is optional and independent of this PR — registering here still adds richer metadata (`coingeckoId`, `bridgeInfo`, display `label`) and a fallback icon for clients that don't read on-chain `logoURI`.

4. **Submit PR** with as much information as you think is helpful for review.

### Token Extensions

Tokens support optional `extensions` for richer metadata:

| Field | Description |
|-------|-------------|
| `chain` | Always `"tempo"` by convention |
| `coingeckoId` | [CoinGecko](https://www.coingecko.com) identifier for price mapping |
| `label` | Display label override (used by the Explorer) |
| `bridgeInfo` | Origin chain and contract info for bridged tokens |

For **bridged tokens**, include `bridgeInfo` so aggregators like DeFi Llama can automatically map to the canonical asset:

```json
{
  "extensions": {
    "chain": "tempo",
    "coingeckoId": "usd-coin",
    "bridgeInfo": {
      "sourceChainId": 1,
      "sourceAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
    }
  }
}
```

For **native tokens** (e.g., PathUSD), omit `bridgeInfo`:

```json
{
  "extensions": {
    "chain": "tempo",
    "coingeckoId": "pathusd"
  }
}
```

### Icon Requirements

* Format: SVG
* Address filename must be lowercase (e.g., `0xabcd...1234.svg`)
* Recommended: square aspect ratio, minimal whitespace

<Callout type="info">
  A token that gets added to the tokenlist will automatically reflect in the Explorer in the next deployment.
</Callout>

[Full OpenAPI Spec →](https://tokenlist.tempo.xyz/docs)