Repository files navigation

The Superchain token list is a list of tokens managed by the maintainers of this repo that have been deployed on Superchains including the OP Mainnet and Base. It serves as a source of truth for services such as theOptimism bridge UI.

It is worth noting that the Superchain Token List makes a distinction between token deployment / bridging and list curation. Tokens can be deployed / bridged in a permissionless manner,anyone can deploy / bridge a token on the Superchain.

Please note that by adding a token to the list we aren’t making any claims about the token itself; tokens are not reviewed for their quality, merits, or soundness as investments.

1. Follow the instructions below to create a PR that wouldadd your token to the list.
2. Wait for a reviewer to kick off theautomated checks.
3. After the automated checks pass and a reviewer approves the PR, then it will automatically be merged.

Note: The standard bridge doesnot support certain ERC-20 configurations:

• Fee on transfer tokens
• Tokens that modify balances without emitting a Transfer event

For right now, each OP Chain has their own review process. So, if you are adding tokens across multiple chains, please separate your pull request so that you have one PR for each chain, in order to streamline the review process.

• If you're adding a token toBase (e.g.base [mainnet] orbase-sepolia [testnet]), instead of using the predeploy token factory on Base, we recommend you use the token factorylisted here to avoid having a token address that may conflict with a different token on Optimism.
• If you are adding a token toZora: please use thezora label and add@tbtstl as a reviewer.
• If you are adding a token toMode: please use themode label.
• If you are adding a token toLisk (e.g.lisk [mainnet] orlisk-sepolia [testnet]): please use thelisk label and add@shuse2 as a reviewer.

Our CI performs a series of automated checks on every PR.These automated checks take place as part of theValidate PR check.Some issues raised by CI will trigger an error and must be resolved before your PR will be approved.These issues are marked below as "auto-reject" issues.Other issues will surface a warning, and will require a manual review from a reviewer.These issues are marked below as "requires manual review".

• Given tokens actually exist on all specified chains (auto-reject)
• L1 tokens are verified on Etherscan (auto-reject)
• Description is under 1000 characters (auto-reject)
• Tokenname,symbol, anddecimals matches on-chain data (auto-reject)
  • Ifoverrides are used (requires manual review)
• L2 token was deployed by theStandardTokenFactory or is anL2StandardERC20 token that uses the standard L2 bridge address (0x4200000000000000000000000000000000000010) (requires manual review)
• Ethereum token listed on theCoinGecko Token List(requires manual review)
  • Why CoinGecko? CoinGecko's token list updates every hour which means we get token list updates very quickly. CoinGecko also uses an in-depthlisting criteria.

If your automated checks failed, you can see the reason for the failure by downloadingvalidation-artifacts.zip, unzipping it and opening thevalidation_results.txt file. To locate thevalidation-artifacts follow these steps:

1. Click on theDetails link forValidate PR check in your PR
2. ClickSummary in the left panel
3. Find the section on the page labeledArtifacts and click onvalidation-artifacts
4. After download ofvalidation-artifacts.zip, unzip it and openvalidation_results.txt

If you make changes and need to run the validation check again, you will need to wait for a reviewer to approve the checks to run again. However, if you do not want to wait for a reviewer to approve the checks to run again to see if the failures have been resolved, you can run the validation checks locally by running:

npx tsx ./bin/cli.ts validate --datadir ./data --tokens <data folder name (e.g. ETH)>

All PRs are subject to a light-weight final approval, even if not marked asrequires manual review.

Create a folder inside of thedata folder with the same name as the symbol of the token you are trying to add. For example, if you are adding a token with the symbol "ETH" you must create a folder called ETH.

Add a logo to the data folder you just created. Your logo MUST be an SVG calledlogo.svg. Your logo should be at least 200x200 pt minimum and 256x256 pt preferred.

Add a file to your folder calleddata.json with the following format:

{"name":"Token Name","symbol":"SYMBOL","decimals":18,"description":"A multi-chain token","website":"https://token.com","twitter":"@token","tokens": {"ethereum": {"address":"0x1234123412341234123412341234123412341234"    },"optimism": {"address":"0x2345234523452345234523452345234523452345"    },"sepolia": {"address":"0x5678567856785678567856785678567856785678"    },"optimism-sepolia": {"address":"0x6789678967896789678967896789678967896789"    },"base": {"address":"0x7890789078907890789078907890789078907890"    },"base-sepolia": {"address":"0x1011121011121011121011121011121011121011"    }  }}

Please include the token addresses forall of the below chains where the token you are submitting has been deployed.We currently accept tokens on the following chains:

• ethereum
• optimism
• sepolia
• base
• base-sepolia
• optimism-sepolia
• mode
• pgn
• lisk
• lisk-sepolia
• redstone

If you would like to add your token to this token list but you do not want your token to be included on the Optimism Bridge app, please include thenobridge option.

{"name":"Token Name","symbol":"SYMBOL","decimals":18,"description":"A multi-chain token","website":"https://token.com","twitter":"@token","nobridge":true,"tokens": {...  }}

If your token is not a standard ERC20 (e.g., DSToken), please include thenonstandard option.

{"name":"Token Name","symbol":"SYMBOL","decimals":18,"description":"A multi-chain token","website":"https://token.com","twitter":"@token","nonstandard":true,"tokens": {...  }}

If you require overrides for specific tokens, you can include theoverrides field. You are able to override thename,symbol,decimals, orbridge for any token. You do not need to override every token at the same time.

{"name":"Token Name","symbol":"SYMBOL","decimals":18,"description":"A multi-chain token","website":"https://token.com","twitter":"@token","tokens": {"ethereum": {"address":"0x1234123412341234123412341234123412341234","overrides": {"name":"My Ethereum Token"      }    },"optimism": {"address":"0x2345234523452345234523452345234523452345","overrides": {"bridge":"0x1111111111111111111111111111111111111111"      }    }  }}

To override an L1 bridge address, specify the L2 chain it bridges to along with the address of the L1 bridge. For an L2 bridge address override, just specify the address of the L2 bridge.

Here is an example:

{  "name": "Synthetix",  "symbol": "SNX",  "decimals": 18,  "tokens": {    "ethereum": {      "address": "0xc011a73ee8576fb46f5e1c5751ca3b9fe0af2a6f",      "overrides": {        "bridge": {          "optimism": "0x39Ea01a0298C315d149a490E34B59Dbf2EC7e48F"        }      }    },    "optimism": {      "address": "0x8700daec35af8ff88c16bdf0418774cb3d7599b4",      "overrides": {        "bridge": "0x136b1EC699c62b0606854056f02dC7Bb80482d63"      }    },    "sepolia": {      "address": "0x51f44ca59b867E005e48FA573Cb8df83FC7f7597",      "overrides": {        "bridge": {          "optimism-sepolia": "0x1427Bc44755d9Aa317535B1feE38922760Aa4e65"        }      }    },    "optimism-sepolia": {      "address": "0x2E5ED97596a8368EB9E44B1f3F25B2E813845303",      "overrides": {        "bridge": "0xD2b3F0Ea40dB68088415412b0043F37B3088836D"      }    }  }}

Open apull request with the changes that you've made. Please only add one token per pull request to simplify the review process. This means two new files inside of one new folder. If you want to add multiple tokens, please open different PRs for each token.

Your pull request will be validated by a series of automated checks. If one of these checks fails, please resolve these issues and make sure that validation succeeds. We will review your pull request for final approval once automated validation succeeds.

Once your PR is merged, the token list will update automatically to include your token. Please do NOT update the token list (optimism.tokenlist.json) directly. All token list updates will be handled automatically when PRs are merged into themaster branch.

Note thatthe bridge UI is updated approximately once every work day, so it might take a day (or three in the case of an update on Friday) until your token is available there.