Open almost any swap screen and you will see a tidy list of tokens with names, symbols and logos. It is easy to assume that someone carefully checked every entry. In reality, that tidy list usually comes from a simple file called a token list, and what it does and does not tell you is worth understanding before you swap anything.
The problem token lists solve
On Base, a token is a smart contract. The chain itself only knows the contract's address. It does not store a nice logo, and the name and symbol are just text the contract returns when asked. Anyone can deploy a contract that calls itself "USDC" or "ETH".
That creates two practical problems for a wallet or swap interface:
- Discovery. Out of millions of contracts, which ones should the interface show in a dropdown?
- Presentation. Where does it get the logo, the correct number of decimals and a readable name?
Token lists are the common answer. Instead of every app maintaining its own private spreadsheet, the community agreed on a shared file format that any app can read.
What a token list actually is
A token list is a JSON file published at a web address. The specification was created by the Uniswap team and is now used widely across Ethereum and its layer 2 networks, including Base. The format is public, and the specification itself states that anyone can create and maintain a token list as long as they follow it.
At the top level, a list has a few fields:
- name, a human readable title for the list.
- version and timestamp, so apps can tell when it changed.
- keywords and tags, to help people find and categorize lists.
- logoURI, an image for the list itself.
Then comes the array of tokens. Each entry describes one token with fields such as:
- chainId, the network the token lives on (Base mainnet uses chain ID 8453).
- address, the contract address on that network.
- name, symbol and decimals.
- logoURI, a link to the token's image.
The combination of chain ID and address is what identifies a token in the standard. The symbol is only a label. This matters because two different contracts can share the same symbol, which is exactly how impersonation tokens work.
Where lists are hosted and how they change
A list is just a file, so it can be hosted in several ways: on an ordinary HTTPS website, pinned to IPFS, or linked through an ENS name. The specification recommends IPFS pinning where possible, since it makes the content harder to alter silently.
Lists also follow simple versioning rules. Adding tokens raises the minor version. Changing a token's name, symbol, logo or decimals raises the patch version. Removing a token, or changing a token's address or chain, raises the major version. An interface can read these numbers to decide whether a list has changed in a meaningful way.
The specification also says plainly that its version numbers are not meant to protect against malicious updates. If a list maintainer publishes a bad change, the version number will not save you. Trust in a list comes from trusting whoever maintains it.
Being on a list is not an endorsement
This is the most important point for everyday users. Uniswap's own default list documentation notes that listing is not required to use a token in its interface, and that filing a request does not guarantee inclusion. The reverse is also worth remembering: appearing in a list is not a safety certificate.
A token list can tell an app things like "this address is called XYZ, has 18 decimals and uses this logo." It cannot tell you:
- whether the token's contract has hidden owner privileges,
- whether liquidity can be pulled,
- whether the token charges a fee on every transfer,
- whether the project behind it is honest.
Different lists have different standards. Some are curated conservatively by a team. Others are broad and automated, adding almost anything that meets a technical threshold. Some wallets show a token because it appears on a list, and others show it because your address happens to hold it, which is a different thing entirely.
Why a token may be hidden or shown as "unknown"
If a swap screen does not display a token you expect, there are usually ordinary explanations:
- It is not on the lists that the app uses. Many interfaces let you paste a contract address to find such a token, and then show a warning before you continue.
- It was recently deployed. Lists take time to update.
- The app filters low quality tokens to reduce scam exposure.
- You are looking at the wrong network. The same token name can exist at different addresses on different chains.
Similarly, an unfamiliar token that appears in your wallet without you doing anything is a reason for caution, not excitement. See our guide on unsolicited tokens and airdrop scams for how those work.
How to verify a token yourself
Do not treat a logo or a list entry as proof. A short habit is more reliable:
- Get the contract address from an official source, such as the project's own website or documentation, and compare it with the address in your swap screen character by character.
- Check the address on a block explorer. Confirm the contract is verified, look at the holder distribution and read the token's transfer history. Our guide to using a block explorer walks through this.
- Look for warning signs described in spotting scam tokens on Base and how to research a token before you swap it.
- Start small if you decide to proceed, and remember that any token can lose value or become impossible to sell.
Key takeaways
- A token list is a public JSON file that maps token addresses to names, symbols, decimals and logos.
- Anyone can publish one, and lists vary widely in how carefully they are curated.
- The address and chain ID identify a token. The name and symbol do not.
- Appearing in a list is convenience, not endorsement, and version numbers do not protect against a bad update.
- Verify contract addresses from official sources and on a block explorer before you swap.
Simple Base Swap is built around Base only, which removes one common source of confusion, but the same caution applies to every swap you make. This article is educational and is not financial advice.