Token list and address tags

What the list is

Two files per network. tokenlist.json lists the reviewed tokens, in the standard Uniswap Token Lists format, so any wallet, DEX interface or aggregator can import it as it is. tags.json gives well-known contracts a readable label - a name, a category and a project - so an explorer can show "Pepper router" where it would otherwise show a hexadecimal address.

A listed token gets the verified mark, its logo, its name and its symbol on the explorer, on Pepper, in the Toolkit, on Names and in the Account page. A tagged contract reads by its label in transaction lists, on address pages and in search.

Nothing is listed automatically. A token launched with Pepper's token launcher is not added because it exists; it is added when someone opens a pull request and it meets the criteria.

Where it lives

The list lives in a public GitHub repository, github.com/PickleChain/token-list, with one folder per network:

Inside a network folder:

The raw URLs, always the latest commit on main:

https://raw.githubusercontent.com/PickleChain/token-list/main/testnet/tokenlist.json
https://raw.githubusercontent.com/PickleChain/token-list/main/testnet/tags.json

For a website, fetch the files server-side and serve them from your own origin instead of hot-linking raw.githubusercontent.com from visitors' browsers: it keeps their IP addresses away from a third party, stays clear of GitHub's rate limits and lets you keep the last good copy when GitHub is unreachable. In a wallet or a DEX interface, add the tokenlist.json raw URL as a custom token list.

How the Pickle apps use it

The explorer API is the only part of the Pickle stack that talks to GitHub for these files. It fetches both about every ten minutes, validates each file as a whole - shape, chain ID, checksums, duplicates - and keeps the last good copy in memory and on disk. A file that fails is rejected entirely and the previous one stays in service, so a bad commit can never blank a label or a logo. Every Pickle site then reads the explorer's copy from its own origin:

The routes are on https://explorer.picklechain.xyz, behind the explorer's CORS allowlist: they serve the Pickle sites. Your own application reads the raw files above.

Add a token

Check the criteria first: a pull request for a token that does not meet them is closed. Then, on your fork of the repository:

1. Get the checksummed address. EIP-55 mixed case, not all lowercase. If yours is wrong, the validator prints the expected form.
2. Add the logo to testnet/logos/tokens/, named exactly after that address: testnet/logos/tokens/0x0000…dEaD.png (or .svg). It must follow the logo rules.
3. Append an entry to tokens in testnet/tokenlist.json, as in the example below.
4. Bump the version of tokenlist.json - adding a token is a minor bump, 1.4.2 becomes 1.5.0 - and set timestamp to now, in ISO 8601 UTC.
5. Run the checks with npm test. It needs Node 22 or later and nothing else: the validator has no dependencies, so there is nothing to install.
6. Open a pull request against main. In its description, link a post from the project's own website or official account that names the contract address.

{
  "chainId": 78270,
  "address": "0x0000…dEaD",
  "name": "Example Token",
  "symbol": "EXM",
  "decimals": 18,
  "logoURI": "https://raw.githubusercontent.com/PickleChain/token-list/main/testnet/logos/tokens/0x0000…dEaD.png",
  "extensions": {
    "website": "https://your-project.example",
    "explorer": "https://explorer.picklechain.xyz/address/0x0000…dEaD"
  }
}

0x0000…dEaD stands for your full 42-character checksummed address; it is a placeholder, not a token.

The whole round trip on the command line:

# Fork and clone (or fork on the website and clone your fork):
gh repo fork PickleChain/token-list --clone
cd token-list
git checkout -b add-exm

# Logo, entry, version and timestamp, then:
npm test

git add testnet/tokenlist.json testnet/logos/tokens/
git commit -m "Add Example Token (EXM)"
git push origin add-exm
# ...and open the pull request on GitHub.

Logo rules

Every file under logos/ must be referenced by the list or the tags. A logo that nothing points to fails the checks, so remove it in the same pull request as its entry.

Add an address tag

Tags are for contracts that people meet in transactions: protocol contracts, routers, factories, pools, vaults, games, bridges. Personal wallets are never tagged. The project must be live on Pickle Chain, and the address must be checkable in the project's own documentation or deployment files.

1. Add an entry to tags in testnet/tags.json, keyed by the checksummed address.
2. Optionally add a logo to testnet/logos/tags/ - same format rules as a token logo, any file name - and point logo at its raw URL. Several tags of one project can share one file.
3. Bump the version of tags.json and its timestamp, run npm test and open the pull request.

"0x0000…dEaD": {
  "name": "Example vault",
  "category": "protocol",
  "project": "Example",
  "url": "https://your-project.example",
  "logo": "https://raw.githubusercontent.com/PickleChain/token-list/main/testnet/logos/tags/example.png",
  "note": "Holds deposits and pays out the weekly yield."
}

The categories defined today:

If none fits, propose a new category in the same pull request: a lowercase key of up to 20 characters, with a name and a description.

Update or remove an entry

• Change an entry - a name, a note, a website, the decimals - by editing it in place and bumping the patch version. Open the pull request from the token's team, as for an addition.
• Change a logo by replacing the file. Switching between PNG and SVG renames it, so update logoURI and delete the old file.
• Replace a contract by adding the new address. For a tag, keep the old entry and suffix its name with (previous), so old transactions still read clearly.
• Remove an entry by deleting it and its logo file, with a major version bump.

Maintainers can remove a token at any time - after an exploit, a rug pull, a move to a new contract or a misleading change of metadata.

Versions

Each file carries its own version, and the bump follows the Token Lists rules. CI enforces it against the base branch of the pull request, and a changed version needs a newer timestamp.

npm test                                      # every list and logo, then the validator's own tests
node scripts/validate.mjs --base origin/main  # also the version bumps, as CI checks them

What review checks

Every pull request runs npm test and the version check in GitHub Actions, then a maintainer reviews it. A token is added when all of these hold:

• It is deployed on the network of that folder, and its source is verified or published.
• The pull request is opened or confirmed by the token's team, with a link to a post on the project's own website or official account that names the contract address.
• Its name and symbol do not imitate another token or project. A new PKL or WETH is refused.
• It has real use: liquidity on Pepper, holders or a live product - not a token launched a few minutes ago.
• The contract has no hidden mint, blacklist or fee switch the team has not disclosed.

A tag is added when the address is a contract, the project is live on Pickle Chain and the address can be checked in the project's own documentation or deployment files.

Common validation errors

npm test prints every problem, not just the first. The ones people meet most, and the fix: