# Token List API
> A live ERC-20 token metadata directory aggregated from the curated, on-chain token lists that wallets and dApps actually trust — Uniswap Labs Default, CoinGecko, 1inch, Aave and the Optimism Superchain list — read keyless from their public endpoints. Resolve any token contract address on any chain to its canonical name, symbol, decimals and logo; list a curated set in full (paged, filterable by chain); search across every list by symbol or name; and discover a token's bridged addresses on other chains. The metadata layer every wallet, swap UI and portfolio tracker needs before it can safely display or transact a token. Live, short cache only — nothing stored.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/tokenlist-api/..."
```

## Pricing
- **Free** (Free) — 5,000 calls/Mo, 3 req/s
- **Starter** ($12/Mo) — 110,000 calls/Mo, 8 req/s
- **Pro** ($39/Mo) — 700,000 calls/Mo, 20 req/s
- **Business** ($115/Mo) — 4,500,000 calls/Mo, 50 req/s

## Endpoints

### Tokens

#### `GET /v1/search` — Search tokens by symbol or name across all curated lists

**Parameters:**
- `q` (query, required, string) — Symbol or name to search (min 2 chars) Example: `usdc`
- `chain` (query, optional, string) — EVM chain id filter Example: `1`
- `limit` (query, optional, string) — Max results (1-200) Example: `10`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tokenlist-api/v1/search?q=usdc&chain=1&limit=10"
```

**Response:**
```json
{
    "data": {
        "note": "Tokens whose symbol or name matches, deduped by chain id + address across all curated lists. found_in lists where each appears.",
        "count": 10,
        "query": "usdc",
        "source": "tokenlists.org ecosystem",
        "results": [
            {
                "name": "USDCoin",
                "symbol": "USDC",
                "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
                "chain_id": 1,
                "decimals": 6,
                "found_in": [
                    "uniswap",
                    "coingecko",
                    "oneinch",
                    "aave",
                    "optimism"
                ],
                "logo_uri": "https://raw.githubusercontent.com/trustwallet/assets/master/blockchains/ethereum/assets/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48/logo.png"
            },
            {
                "name": "Aave v2 USDC",
                "symbol": "AUSDC",
                "address": "0xbcca60bb61934080951369a648fb03df4f96263c",
                "chain_id": 1,
                "decimals": 6,
                "found_in": [
                    "coingecko",
                    "oneinch",
                    "aave"
                ],
                "logo_uri": "https://assets.coingecko.com/coins/images/14318/thumb/aUSDC.e260d492.png?1696514006"
            },
            {
                "name": "Aave v3 USDC",
                "symbol": "AUSDC",
                "address": "0x98c23e
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/token` — Resolve a token by contract address (metadata + lists + bridges)

**Parameters:**
- `address` (query, required, string) — Token contract address (0x + 40 hex) Example: `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`
- `chain` (query, optional, string) — EVM chain id to disambiguate (1=Ethereum, 8453=Base, 42161=Arbitrum...) Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tokenlist-api/v1/token?address=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48&chain=1"
```

**Response:**
```json
{
    "data": {
        "name": "USDCoin",
        "note": "Canonical metadata for the token, the curated lists it appears in, and (where published) its bridged addresses on other chains keyed by chain id.",
        "source": "tokenlists.org ecosystem",
        "symbol": "USDC",
        "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "chain_id": 1,
        "decimals": 6,
        "found_in": [
            "uniswap",
            "coingecko",
            "oneinch",
            "aave",
            "optimism"
        ],
        "logo_uri": "https://raw.githubusercontent.com/trustwallet/assets/master/blockchains/ethereum/assets/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48/logo.png",
        "list_count": 5,
        "bridged_addresses": {
            "10": "0x0b2c639c533813f4aa9d7837caf62653d097ff85",
            "56": "0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d",
            "130": "0x078d782b760474a361dda0af3839290b0ef57ad6",
            "143": "0x754704bc059f8c67012fed69bc8a327a5aafb603",
            "1868": "0xba9986d2381edf1da03b0b9c1f8b00dc4aacc369",
            "42161": "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
            "42220": "0xceba9300f2b948710d2653dd7b07f33a8b32118c",
            "43114": "0xb97ef9ef8734c71904d8002f8b6bc66dd9c48a6e"
        }
    },
    "meta": {
        "timestamp": "2026-06-14T08:04:13.839Z",
        "request_id": "9682b558-4a8d-45c9-878c-8d535bd3a107"
    },
    "status": "ok",
    "message": "Token retrieved successfully",
    
…(truncated, see openapi.json for full schema)
```

### Lists

#### `GET /v1/lists` — The curated token lists and their token counts

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tokenlist-api/v1/lists"
```

**Response:**
```json
{
    "data": {
        "note": "Curated, trusted token lists. Use the key with /v1/tokens?list=<key>.",
        "count": 5,
        "lists": [
            {
                "key": "uniswap",
                "name": "Uniswap Labs Default",
                "version": "22.1.0",
                "timestamp": "2026-06-11T20:12:01.724Z",
                "source_url": "https://tokens.uniswap.org",
                "token_count": 1472
            },
            {
                "key": "coingecko",
                "name": "CoinGecko",
                "version": "1516.0.0",
                "timestamp": "2026-06-13T11:03:02.238+00:00",
                "source_url": "https://tokens.coingecko.com/uniswap/all.json",
                "token_count": 4922
            },
            {
                "key": "oneinch",
                "name": "1inch default token list",
                "version": "146.0.0",
                "timestamp": "2025-01-28T16:04:53.109+00:00",
                "source_url": "https://tokens.1inch.eth.limo",
                "token_count": 2570
            },
            {
                "key": "aave",
                "name": "Aave Token List",
                "version": "1.3.0",
                "timestamp": "2020-12-11T17:08:18.941Z",
                "source_url": "https://tokenlist.aave.eth.link",
                "token_count": 81
            },
            {
                "key": "optimism",
                "name": "Superchain Token List",
                "version": "10
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/tokens` — Tokens of one curated list, filterable by chain and paged

**Parameters:**
- `list` (query, required, string) — List key: uniswap, coingecko, 1inch, aave, optimism Example: `uniswap`
- `chain` (query, optional, string) — EVM chain id filter Example: `1`
- `limit` (query, optional, string) — Page size (1-1000) Example: `25`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tokenlist-api/v1/tokens?list=uniswap&chain=1&limit=25"
```

**Response:**
```json
{
    "data": {
        "list": "uniswap",
        "count": 25,
        "limit": 25,
        "total": 390,
        "offset": 0,
        "source": "tokenlists.org ecosystem",
        "tokens": [
            {
                "name": "1inch",
                "symbol": "1INCH",
                "address": "0x111111111117dc0aa78b770fa6a738034120c302",
                "chain_id": 1,
                "decimals": 18,
                "logo_uri": "https://assets.coingecko.com/coins/images/13469/thumb/1inch-token.png?1608803028"
            },
            {
                "name": "Ancient8",
                "symbol": "A8",
                "address": "0x3e5a19c91266ad8ce2477b91585d1856b84062df",
                "chain_id": 1,
                "decimals": 18,
                "logo_uri": "https://assets.coingecko.com/coins/images/39170/standard/A8_Token-04_200x200.png?1720798300"
            },
            {
                "name": "Aave",
                "symbol": "AAVE",
                "address": "0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9",
                "chain_id": 1,
                "decimals": 18,
                "logo_uri": "https://assets.coingecko.com/coins/images/12645/thumb/AAVE.png?1601374110"
            },
            {
                "name": "Arcblock",
                "symbol": "ABT",
                "address": "0xb98d4c97425d9908e66e53a6fdf673acca0be986",
                "chain_id": 1,
                "decimals": 18,
                "logo_uri": "https://assets.coingecko
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Service metadata & live sample

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tokenlist-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "sample": {
            "lists": 5,
            "uniswap_tokens": 1472
        },
        "source": "tokenlists.org ecosystem (Uniswap, CoinGecko, 1inch, Aave, Optimism), live",
        "service": "tokenlist-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/lists": "The curated token lists and their token counts.",
            "GET /v1/token": "Resolve a token by address (chain optional): metadata + which lists + bridged addresses.",
            "GET /v1/search": "Search tokens by symbol or name across all lists (q=usdc, optional chain).",
            "GET /v1/tokens": "Tokens of one list (list=uniswap), filterable by chain and paged (limit, offset)."
        },
        "chains_note": "chain is an EVM chain id (1=Ethereum, 10=Optimism, 56=BNB, 137=Polygon, 8453=Base, 42161=Arbitrum, 43114=Avalanche).",
        "description": "A live ERC-20 token metadata directory aggregated from the curated on-chain token lists wallets and dApps trust (Uniswap, CoinGecko, 1inch, Aave, Optimism). Resolve any token address to its name/symbol/decimals/logo, list a curated set (paged, chain-filterable), search by symbol or name across every list, and discover a token's bridged addresses on other chains. The metadata layer every wallet, swap UI and portfolio tracker needs. Live, short cache only.",
        "upstream_status": "ok"
    },
    "meta": {
        "timestamp": "2026-06-14T08:04:14.062Z",
        "request_id": "3286f8
…(truncated, see openapi.json for full schema)
```


---
Marketplace page: https://www.oanor.com/api/tokenlist-api
OpenAPI spec: https://www.oanor.com/api/tokenlist-api/openapi.json