0
# Uniswap Default Token List
1

2
The Uniswap Default Token List is an npm package that provides the official default token list used by the Uniswap decentralized exchange interface. It contains comprehensive token metadata including addresses, symbols, names, decimals, and logo URIs for tokens across multiple blockchain networks including Ethereum mainnet, Arbitrum, Polygon, Optimism, Base, Avalanche, and other EVM-compatible chains.
3

4
## Package Information
5

6
- **Package Name**: @uniswap/default-token-list
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install @uniswap/default-token-list`
10

11
## Core Imports
12

13
Access the pre-built token list JSON (main package export):
14

15
```javascript
16
const tokenList = require("@uniswap/default-token-list");
17
```
18

19
ES modules:
20

21
```javascript
22
import tokenList from "@uniswap/default-token-list";
23
```
24

25
**Note**: The published package only includes the pre-built JSON file. The `buildList` function is not available in the published package - it exists only in the source code for generating the token list during the build process.
26

27
## Basic Usage
28

29
```javascript
30
const tokenList = require("@uniswap/default-token-list");
31

32
console.log("Token list name:", tokenList.name);
33
console.log("Version:", tokenList.version);
34
console.log("Total tokens:", tokenList.tokens.length);
35

36
// Find tokens on Ethereum mainnet
37
const mainnetTokens = tokenList.tokens.filter(token => token.chainId === 1);
38
console.log("Mainnet tokens:", mainnetTokens.length);
39

40
// Find a specific token by symbol
41
const wethToken = tokenList.tokens.find(
42
  token => token.symbol === "WETH" && token.chainId === 1
43
);
44
console.log("WETH address:", wethToken?.address);
45
```
46

47
## Architecture
48

49
The package follows a build-time generation pattern:
50

51
- **Source Structure**: Individual token files per network in `src/tokens/*.json`
52
- **Build System**: Node.js script (`src/buildList.js`) that combines token files
53
- **Cross-chain Mapping**: Uses `@uniswap/token-list-bridge-utils` for bridge information
54
- **Published Artifact**: Single JSON file (`build/uniswap-default.tokenlist.json`)
55
- **Package Export**: Direct JSON import as main entry point
56

57
The published npm package contains only the pre-built token list JSON - the source code and build system are not included in the published package.
58

59
## Capabilities
60

61
### Pre-built Token List Access
62

63
Direct access to the complete Uniswap default token list with all network tokens and metadata.
64

65
```javascript { .api }
66
/**
67
 * Pre-built token list JSON data (main package export)
68
 * Available as: require("@uniswap/default-token-list")
69
 */
70
const tokenList: TokenList;
71
```
72

73
### Token List Generation (Source Only)
74

75
The source code includes a build function for generating the token list, but this is not available in the published package.
76

77
```javascript { .api }
78
/**
79
 * Builds the complete Uniswap default token list (source code only)
80
 * Located at: src/buildList.js
81
 * @returns TokenList object (synchronous)
82
 */
83
function buildList(): TokenList;
84
```
85

86
**Note**: This function is only available in the source repository and is used during the build process. It is not included in the published npm package.
87

88
## Types
89

90
```javascript { .api }
91
interface TokenList {
92
  /** Name of the token list */
93
  name: string;
94
  /** ISO timestamp when the list was generated */
95
  timestamp: string;
96
  /** Semantic version object */
97
  version: {
98
    major: number;
99
    minor: number;
100
    patch: number;
101
  };
102
  /** Token classification tags (currently empty) */
103
  tags: Record<string, any>;
104
  /** IPFS URL for the list logo */
105
  logoURI: string;
106
  /** Keywords describing the list */
107
  keywords: string[];
108
  /** Array of all tokens in the list */
109
  tokens: Token[];
110
}
111

112
interface Token {
113
  /** Full token name (e.g., "Wrapped Ether") */
114
  name: string;
115
  /** Checksummed contract address */
116
  address: string;
117
  /** Token symbol (e.g., "WETH") */
118
  symbol: string;
119
  /** Number of decimal places (0-18) */
120
  decimals: number;
121
  /** Blockchain network ID */
122
  chainId: number;
123
  /** URL to token logo image */
124
  logoURI: string;
125
  /** Additional metadata including bridge information */
126
  extensions?: {
127
    bridgeInfo?: Record<string, {
128
      tokenAddress: string;
129
    }>;
130
  };
131
}
132
```
133

134
## Network Coverage
135

136
The token list includes tokens from the following blockchain networks:
137

138
- **Ethereum Mainnet** (chainId: 1)
139
- **Polygon** (chainId: 137)
140
- **Optimism** (chainId: 10)
141
- **Arbitrum** (chainId: 42161)
142
- **Base** (chainId: 8453)
143
- **Avalanche** (chainId: 43114)
144
- **BNB Chain** (chainId: 56)
145
- **Celo** (chainId: 42220)
146
- **Blast** (chainId: 81457)
147
- **zkSync Era** (chainId: 324)
148
- **Worldchain** (chainId: 480)
149
- **Zora** (chainId: 7777777)
150
- **Unichain** (chainId: 1301)
151
- **Sepolia Testnet** (chainId: 11155111)
152
- **Goerli Testnet** (chainId: 5)
153
- **Mumbai Testnet** (chainId: 80001)
154
- **Deprecated Testnets**: Ropsten (3), Rinkeby (4), Kovan (42)
155

156
## Data Structure
157

158
### Token List Structure
159

160
The token list follows the Uniswap token list specification:
161

162
- **name**: Always "Uniswap Labs Default"
163
- **timestamp**: ISO string of when the list was generated
164
- **version**: Semantic version matching package.json
165
- **logoURI**: IPFS URL for the Uniswap logo
166
- **keywords**: ["uniswap", "default"]
167
- **tokens**: Sorted array of all tokens (by chainId, then symbol)
168

169
### Token Metadata
170

171
Each token contains:
172

173
- **Core properties**: name, address, symbol, decimals, chainId
174
- **Visual**: logoURI pointing to token logo image
175
- **Cross-chain**: extensions.bridgeInfo mapping chainIds to bridge addresses
176

177
### Bridge Information
178

179
Many tokens include bridge information in the `extensions.bridgeInfo` field, mapping chain IDs to the corresponding token addresses on those chains:
180

181
```javascript
182
{
183
  "extensions": {
184
    "bridgeInfo": {
185
      "10": { "tokenAddress": "0x4200000000000000000000000000000000000006" },
186
      "137": { "tokenAddress": "0x7ceB23fD6bC0adD59E62ac25578270cFf1b9f619" }
187
    }
188
  }
189
}
190
```
191

192
## Common Use Cases
193

194
### Finding Tokens by Chain
195

196
```javascript
197
const tokenList = require("@uniswap/default-token-list");
198

199
// Get all Polygon tokens
200
const polygonTokens = tokenList.tokens.filter(token => token.chainId === 137);
201

202
// Get all tokens with bridge info to Arbitrum
203
const bridgeableToArbitrum = tokenList.tokens.filter(
204
  token => token.extensions?.bridgeInfo?.["42161"]
205
);
206
```
207

208
### Token Lookup by Symbol
209

210
```javascript
211
const tokenList = require("@uniswap/default-token-list");
212

213
// Find USDC on multiple chains
214
const usdcTokens = tokenList.tokens.filter(token => token.symbol === "USDC");
215

216
// Find specific token by symbol and chain
217
const usdcOnPolygon = tokenList.tokens.find(
218
  token => token.symbol === "USDC" && token.chainId === 137
219
);
220
```
221

222
### Address Validation
223

224
```javascript
225
const tokenList = require("@uniswap/default-token-list");
226

227
// Check if an address is in the default list
228
function isDefaultToken(address, chainId) {
229
  return tokenList.tokens.some(
230
    token => token.address.toLowerCase() === address.toLowerCase() && 
231
             token.chainId === chainId
232
  );
233
}
234

235
// Get token metadata by address
236
function getTokenByAddress(address, chainId) {
237
  return tokenList.tokens.find(
238
    token => token.address.toLowerCase() === address.toLowerCase() && 
239
             token.chainId === chainId
240
  );
241
}
242
```
243

244
## Build Process (Source Repository)
245

246
The source repository includes a build system that:
247

248
1. Loads individual token files from `src/tokens/*.json`
249
2. Combines them into a single token list  
250
3. Sorts tokens by chainId, then by symbol
251
4. Applies cross-chain bridge mapping using `@uniswap/token-list-bridge-utils`
252
5. Outputs to `build/uniswap-default.tokenlist.json`
253

254
**Note**: This build process is only available in the source repository. The published npm package contains only the pre-built JSON output.
255

256
## Dependencies
257

258
The published package has no runtime dependencies - it exports only static JSON data.
259

260
**Source repository dependencies:**
261
- **@uniswap/token-list-bridge-utils**: Provides `chainify()` function for cross-chain token mapping during build
262
- **Development dependencies**: Validation and testing tools including AJV schema validation
263

264
## Validation
265

266
The token list is validated against multiple criteria:
267

268
- Uniswap token list schema compliance
269
- No duplicate addresses per chain
270
- No duplicate symbols (with approved exceptions: "ust", "sol", "jup")
271
- No duplicate names (with approved exceptions: "solana", "jupiter")
272
- Valid checksummed addresses
273
- Decimal values between 0-18
274
- Version format matching package.json