Token Lists

CoW Swap default token lists and token image repository

Managing the tokens

The process has been automated, and it's now much simpler. The forms are self-explanatory and should contain all the info you need to proceed.

Notes:

• Images will be optimized in the background
• If you want to add a token/image to multiple networks, create one issue per network

Head to the issues section and pick your action:

Add or update token

For adding tokens to CoW Swap's default token list, or to update an existing one, use the Add Token form.

Remove token from the list

Use the Remove Token form.

Even though the token is removed from the default list, its image will be kept.

Add or update image only

Not all tokens should be in the default token list, but the more token images we have the better UX.

For this, use the Add Image form.

Flow overview

flowchart TD
    Start(User: Picks form) --> UserFillsForm(User: Fills in form and creates issue)
    UserFillsForm --> |Form ok| ImageProcessed("Automated: [Optional] Optimize image")
    ImageProcessed --> PRCreated(Automated: Creates Pull Request)
    ImageProcessed --> |Failed to process image| AutomatedIssueClosure
    PRCreated --> TeamReview(Team: Reviews Pull Request)
    UserFillsForm --> |Form invalid| AutomatedIssueClosure(Automated: Closes issue)
    TeamReview --> |Request approved| TeamMergesPR(Team: Merges Pull Request)
    TeamReview --> |Request rejected| TeamClosesPR(Team: Closes Pull Request and Issue)

Loading

Development

Instructions for setting up and running the various scripts locally

Setup

Prerequisites

Currently runs on Node.js LTS/Gallium v16.20.2

# Install dependencies
yarn

# Generate Coingecko list
yarn coingecko

Download images (deprecated)

There's a script that will fetch all images from the CowSwap list and store them in src/public/images/<chainId>/<address>.png

yarn downloadImages

Generating Auxiliary Token Lists

To generate updated token lists from Coingecko and Uniswap:

yarn generateAuxLists

This script fetches and processes token data from both Coingecko and Uniswap APIs to create auxiliary token lists. These lists are used to enhance token metadata and support across different networks.

• Coingecko lists contain up to the top 500 tokens per chain, sorted by volume
• Uniswap lists are a combination of:
  • Token for given chain already existing in the default Uniswap list
  • Mainnet tokens, mapped to the target chain, via Coingecko api

The version and timestamp are bumped according to token list standard.

Required Environment Variables

• COINGECKO_API_KEY: Your Coingecko API key (required for API access)

Generated Files

The script generates token list files in src/public/ for the following networks:

• Ethereum (CoinGecko.1.json)
• Arbitrum (CoinGecko.42161.json, Uniswap.42161.json)
• Avalanche (CoinGecko.43114.json, Uniswap.43114.json)
• Base (CoinGecko.8453.json, Uniswap.8453.json)
• BNB (CoinGecko.56.json, Uniswap.56.json)
• Gnosis Chain (CoinGecko.100.json, Uniswap.100.json)
• Linea (CoinGecko.59144.json, Uniswap.59144.json)
• Plasma (CoinGecko.9745.json, Uniswap.9745.json)
• Ink (CoinGecko.57073.json, Uniswap.57073.json)
• Polygon (CoinGecko.137.json, Uniswap.137.json)

Solana lists

yarn solana          # CowSwap.1000000001.json + Rwa.1000000001.json
yarn solanaWarnings  # TokenWarnings.1000000001.json

yarn solana rebuilds the two Solana token lists from Jupiter and CoinGecko, splitting tokenised real-world assets into the RWA list. yarn solanaWarnings then builds the risk warnings from Jupiter's Shield endpoint, for every mint on both lists.

Warnings are published under short codes (MINT, FREEZE, PERM_DEL, CONCENTRATED, LOW_LIQ, LOW_ORGANIC, LOW_VOLUME, UNVERIFIED, NO_SELL), with severity and copy carried once in a types dictionary rather than repeated on every mint — Shield reports a given type at the same severity everywhere, so the per-mint entry only needs the codes:

{
  "types": { "FREEZE": { "severity": "warning", "message": "The authority's owner can freeze…" } },
  "warnings": { "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v": ["FREEZE", "MINT"] }
}

The codes are the contract with the interface, so renaming one is a breaking change. Shield's transfer-fee warnings are dropped: the interface already surfaces fee-bearing tokens, and the rate is baked into the type name (2.69%_TRANSFER_FEES), so the set would grow without bound.

Run them in that order and commit the three files together. Order matters: the warnings are keyed by the mints on the lists, so building them from a stale list leaves a freshly added token looking unflagged.

Neither script is automated — unlike the auxiliary lists, there is no workflow behind these, so the committed files are a snapshot that only moves when someone runs the scripts by hand.

A mint absent from the warnings file has no warnings. Warnings are not folded into the token lists themselves because several warning types are not legal token-list extension keys, and because they change often enough to bump the list version on most runs.

Both scripts refuse to overwrite a list that shrinks by more than 30% in one run, since that usually means an upstream filter moved rather than the tokens going away — override with ALLOW_LIST_SHRINK=1 and ALLOW_WARNINGS_SHRINK=1 respectively. The warnings run also aborts rather than publishing a partial file if a batch cannot be fetched.

Adding a new network

To support a new network (e.g. Ink, chain ID 57073), run these steps in order:

1. Generate auxiliary token lists for the new chain (the chain must already be in COINGECKO_CHAINS in src/scripts/auxLists/utils.ts):

   COINGECKO_API_KEY=your_key yarn generateAuxLists

   This creates src/public/CoinGecko.<chainId>.json and src/public/Uniswap.<chainId>.json for the new network.

2. Fetch permit info for the new chain. The default token list (CowSwap.json) will not include tokens for new networks yet if you haven't added any, so you must pass the path to the chain-specific list as the second argument:

   yarn run fetchPermitInfo -- <chainId> CoinGecko.<chainId>.json

   Example for Ink:

   yarn run fetchPermitInfo -- 57073 CoinGecko.57073.json

   Without the second argument, the script would use CowSwap.json and skip all tokens (they would have the wrong chainId), leaving the permit file empty.

3. Include only the new network's files in your PR. The scripts above may have updated files for other networks too; do not include those changes, as they are updated daily by a cron job.