This package includes a JSON schema for token lists, and TypeScript utilities for working with token lists.

The JSON schema represents the specification for a token list which can be used in the Uniswap Interface.

The JSON schema ID is https://uniswap.org/tokenlist.schema.json

This package does not include code for token list validation. You can easily do this by including a library such as ajv to perform the validation against the JSON schema. The schema is exported from the package for ease of use.

The best way to manually author token lists is to use an editor that supports JSON schema validation. Most popular code editors do, such as IntelliJ or VSCode. Other editors can be found here.

The schema is registered in the SchemaStore, and any file that matches the pattern *.tokenlist.json should automatically utilize the schema (when supported by your text editor.)

In order for your token list to be able to be used, it must pass JSON schema validation.

If you want to automate token listing, e.g. by pulling from a smart contract, or other sources, you can use the npm package to take advantage of the JSON schema for validation and the TypeScript types. Otherwise, you are simply working with JSON. All the usual tools apply, e.g.:

import { TokenList, schema } from '@uniswap/token-lists'

// generate your token list however you like.
const myList: TokenList = generateMyTokenList();

// use a tool like `ajv` to validate your generated token list
validateMyTokenList(myList, schema);

process.stdout.write(JSON.stringify(myList));

Lists include a version field, which follows semantic versioning.

List versions must follow the rules:

• Increment major version when tokens are removed
• Increment minor version when tokens are added
• Increment patch version when tokens already on the list have minor details changed (name, symbol, logo URL)

Changing a token address or chain ID is considered both a remove and an add, and should be a major version update.

You can find a valid example of a token list here.

Instructions for developing in this repo are here.