tokenlist.schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://uniswap.org/tokenlist.schema.json",
  "title": "Uniswap Token List",
  "description": "Schema for lists of tokens compatible with the Uniswap Interface",
  "definitions": {
    "Version": {
      "type": "object",
      "description": "The version of the list, used in change detection",
      "examples": [
        {
          "major": 1,
          "minor": 0,
          "patch": 0
        }
      ],
      "additionalProperties": false,
      "properties": {
        "major": {
          "type": "integer",
          "description": "The major version of the list. Must be incremented when tokens are removed from the list or token addresses are changed.",
          "minimum": 0,
          "examples": [
            1,
            2
          ]
        },
        "minor": {
          "type": "integer",
          "description": "The minor version of the list. Must be incremented when tokens are added to the list.",
          "minimum": 0,
          "examples": [
            0,
            1
          ]
        },
        "patch": {
          "type": "integer",
          "description": "The patch version of the list. Must be incremented for any changes to the list.",
          "minimum": 0,
          "examples": [
            0,
            1
          ]
        }
      },
      "required": [
        "major",
        "minor",
        "patch"
      ]
    },
    "TagIdentifier": {
      "type": "string",
      "description": "The unique identifier of a tag",
      "minLength": 1,
      "maxLength": 10,
      "pattern": "^[\\w]+$",
      "examples": [
        "compound",
        "stablecoin"
      ]
    },
    "ExtensionIdentifier": {
      "type": "string",
      "description": "The name of a token extension property",
      "minLength": 1,
      "maxLength": 40,
      "pattern": "^[\\w]+$",
      "examples": [
        "color",
        "is_fee_on_transfer",
        "aliases"
      ]
    },
    "ExtensionMap": {
      "type": "object",
      "description": "An object containing any arbitrary or vendor-specific token metadata",
      "maxProperties": 10,
      "propertyNames": {
        "$ref": "#/definitions/ExtensionIdentifier"
      },
      "additionalProperties": {
        "$ref": "#/definitions/ExtensionValue"
      },
      "examples": [
        {
          "color": "#000000",
          "is_verified_by_me": true
        },
        {
          "x-bridged-addresses-by-chain": {
            "1": {
              "bridgeAddress": "0x4200000000000000000000000000000000000010",
              "tokenAddress": "0x4200000000000000000000000000000000000010"
            }
          }
        }
      ]
    },
    "ExtensionPrimitiveValue": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1,
          "maxLength": 42,
          "examples": [
            "#00000"
          ]
        },
        {
          "type": "boolean",
          "examples": [
            true
          ]
        },
        {
          "type": "number",
          "examples": [
            15
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "ExtensionValue": {
      "anyOf": [
        {
          "$ref": "#/definitions/ExtensionPrimitiveValue"
        },
        {
          "type": "object",
          "maxProperties": 10,
          "propertyNames": {
            "$ref": "#/definitions/ExtensionIdentifier"
          },
          "additionalProperties": {
            "$ref": "#/definitions/ExtensionValueInner0"
          }
        }
      ]
    },
    "ExtensionValueInner0": {
      "anyOf": [
        {
          "$ref": "#/definitions/ExtensionPrimitiveValue"
        },
        {
          "type": "object",
          "maxProperties": 10,
          "propertyNames": {
            "$ref": "#/definitions/ExtensionIdentifier"
          },
          "additionalProperties": {
            "$ref": "#/definitions/ExtensionValueInner1"
          }
        }
      ]
    },
    "ExtensionValueInner1": {
      "anyOf": [
        {
          "$ref": "#/definitions/ExtensionPrimitiveValue"
        }
      ]
    },
    "TagDefinition": {
      "type": "object",
      "description": "Definition of a tag that can be associated with a token via its identifier",
      "additionalProperties": false,
      "properties": {
        "name": {
          "type": "string",
          "description": "The name of the tag",
          "pattern": "^[ \\w]+$",
          "minLength": 1,
          "maxLength": 20
        },
        "description": {
          "type": "string",
          "description": "A user-friendly description of the tag",
          "pattern": "^[ \\w\\.,:]+$",
          "minLength": 1,
          "maxLength": 200
        }
      },
      "required": [
        "name",
        "description"
      ],
      "examples": [
        {
          "name": "Stablecoin",
          "description": "A token with value pegged to another asset"
        }
      ]
    },
    "TokenInfo": {
      "type": "object",
      "description": "Metadata for a single token in a token list",
      "additionalProperties": false,
      "properties": {
        "chainId": {
          "type": "integer",
          "description": "The chain ID of the Ethereum network where this token is deployed",
          "minimum": 1,
          "examples": [
            1,
            42
          ]
        },
        "address": {
          "type": "string",
          "description": "The checksummed address of the token on the specified chain ID",
          "pattern": "^0x[a-fA-F0-9]{40}$",
          "examples": [
            "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
          ]
        },
        "decimals": {
          "type": "integer",
          "description": "The number of decimals for the token balance",
          "minimum": 0,
          "maximum": 255,
          "examples": [
            18
          ]
        },
        "name": {
          "type": "string",
          "description": "The name of the token",
          "minLength": 0,
          "maxLength": 60,
          "anyOf": [
            {
              "const": ""
            },
            {
              "pattern": "^[ \\S+]+$"
            }
          ],
          "examples": [
            "USD Coin"
          ]
        },
        "symbol": {
          "type": "string",
          "description": "The symbol for the token",
          "minLength": 0,
          "maxLength": 20,
          "anyOf": [
            {
              "const": ""
            },
            {
              "pattern": "^\\S+$"
            }
          ],
          "examples": [
            "USDC"
          ]
        },
        "logoURI": {
          "type": "string",
          "description": "A URI to the token logo asset; if not set, interface will attempt to find a logo based on the token address; suggest SVG or PNG of size 64x64",
          "format": "uri",
          "examples": [
            "ipfs://QmXfzKRvjZz3u5JRgC4v5mGVbm9ahrUiB4DgzHBsnWbTMM"
          ]
        },
        "tags": {
          "type": "array",
          "description": "An array of tag identifiers associated with the token; tags are defined at the list level",
          "items": {
            "$ref": "#/definitions/TagIdentifier"
          },
          "maxItems": 10,
          "examples": [
            "stablecoin",
            "compound"
          ]
        },
        "extensions": {
          "$ref": "#/definitions/ExtensionMap"
        }
      },
      "required": [
        "chainId",
        "address",
        "decimals",
        "name",
        "symbol"
      ]
    }
  },
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the token list",
      "minLength": 1,
      "maxLength": 30,
      "pattern": "^[\\w ]+$",
      "examples": [
        "My Token List"
      ]
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "The timestamp of this list version; i.e. when this immutable version of the list was created"
    },
    "version": {
      "$ref": "#/definitions/Version"
    },
    "tokens": {
      "type": "array",
      "description": "The list of tokens included in the list",
      "items": {
        "$ref": "#/definitions/TokenInfo"
      },
      "minItems": 1,
      "maxItems": 10000
    },
    "tokenMap": {
      "type": "object",
      "description": "A mapping of key 'chainId_tokenAddress' to its corresponding token object",
      "minProperties": 1,
      "maxProperties": 10000,
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "$ref": "#/definitions/TokenInfo"
      },
      "examples": [
        {
          "4_0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984":  {
            "name": "Uniswap",
            "address": "0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984",
            "symbol": "UNI",
            "decimals": 18,
            "chainId": 4,
            "logoURI": "ipfs://QmXttGpZrECX5qCyXbBQiqgQNytVGeZW5Anewvh2jc4psg"
          }
        }
      ]
    },
    "keywords": {
      "type": "array",
      "description": "Keywords associated with the contents of the list; may be used in list discoverability",
      "items": {
        "type": "string",
        "description": "A keyword to describe the contents of the list",
        "minLength": 1,
        "maxLength": 20,
        "pattern": "^[\\w ]+$",
        "examples": [
          "compound",
          "lending",
          "personal tokens"
        ]
      },
      "maxItems": 20,
      "uniqueItems": true
    },
    "tags": {
      "type": "object",
      "description": "A mapping of tag identifiers to their name and description",
      "propertyNames": {
        "$ref": "#/definitions/TagIdentifier"
      },
      "additionalProperties": {
        "$ref": "#/definitions/TagDefinition"
      },
      "maxProperties": 20,
      "examples": [
        {
          "stablecoin": {
            "name": "Stablecoin",
            "description": "A token with value pegged to another asset"
          }
        }
      ]
    },
    "logoURI": {
      "type": "string",
      "description": "A URI for the logo of the token list; prefer SVG or PNG of size 256x256",
      "format": "uri",
      "examples": [
        "ipfs://QmXfzKRvjZz3u5JRgC4v5mGVbm9ahrUiB4DgzHBsnWbTMM"
      ]
    }
  },
  "required": [
    "name",
    "timestamp",
    "version",
    "tokens"
  ]
}