0
# Currency System
1

2
Type-safe currency abstractions for native currencies and ERC20 tokens with comprehensive equality checking and wrapping functionality.
3

4
## Capabilities
5

6
### Base Currency Class
7

8
Abstract base class providing the foundation for all currency types.
9

10
```typescript { .api }
11
/**
12
 * A currency is any fungible financial instrument, including Ether, all ERC20 tokens, and other chain-native currencies
13
 */
14
abstract class BaseCurrency {
15
  /** Returns whether the currency is native to the chain and must be wrapped (e.g. Ether) */
16
  abstract readonly isNative: boolean;
17
  /** Returns whether the currency is a token that is usable in Uniswap without wrapping */
18
  abstract readonly isToken: boolean;
19
  /** The chain ID on which this currency resides */
20
  readonly chainId: number;
21
  /** The decimals used in representing currency amounts */
22
  readonly decimals: number;
23
  /** The symbol of the currency, i.e. a short textual non-unique identifier */
24
  readonly symbol?: string;
25
  /** The name of the currency, i.e. a descriptive textual non-unique identifier */
26
  readonly name?: string;
27

28
  /**
29
   * Constructs an instance of the base class `BaseCurrency`
30
   * @param chainId - The chain ID on which this currency resides
31
   * @param decimals - Decimals of the currency
32
   * @param symbol - Symbol of the currency
33
   * @param name - Name of the currency
34
   */
35
  protected constructor(chainId: number, decimals: number, symbol?: string, name?: string);
36

37
  /**
38
   * Returns whether this currency is functionally equivalent to the other currency
39
   * @param other - The other currency to compare
40
   */
41
  abstract equals(other: Currency): boolean;
42

43
  /**
44
   * Return the wrapped version of this currency that can be used with the Uniswap contracts
45
   */
46
  abstract get wrapped(): Token;
47
}
48
```
49

50
### Native Currency Class
51

52
Abstract class for native currencies like Ether, MATIC, etc.
53

54
```typescript { .api }
55
/**
56
 * Represents the native currency of the chain on which it resides
57
 */
58
abstract class NativeCurrency extends BaseCurrency {
59
  readonly isNative: true;
60
  readonly isToken: false;
61
}
62
```
63

64
### Ether Class
65

66
Concrete implementation for Ethereum's native currency.
67

68
```typescript { .api }
69
/**
70
 * Ether is the main usage of a 'native' currency, i.e. for Ethereum mainnet and all testnets
71
 */
72
class Ether extends NativeCurrency {
73
  /**
74
   * Get or create an Ether instance for the specified chain
75
   * @param chainId - The chain ID to get Ether for
76
   * @returns Ether instance for the chain
77
   */
78
  static onChain(chainId: number): Ether;
79

80
  /**
81
   * Get the wrapped version of Ether (WETH9) for this chain
82
   */
83
  get wrapped(): Token;
84

85
  /**
86
   * Check if this Ether instance equals another currency
87
   * @param other - Currency to compare against
88
   */
89
  equals(other: Currency): boolean;
90
}
91
```
92

93
### Token Class
94

95
Represents ERC20 tokens with full address and metadata support.
96

97
```typescript { .api }
98
/**
99
 * Represents an ERC20 token with a unique address and some metadata
100
 */
101
class Token extends BaseCurrency {
102
  readonly isNative: false;
103
  readonly isToken: true;
104
  /** The contract address on the chain on which this token lives */
105
  readonly address: string;
106
  /** Buy fee tax for FOT tokens, in basis points */
107
  readonly buyFeeBps?: BigNumber;
108
  /** Sell fee tax for FOT tokens, in basis points */
109
  readonly sellFeeBps?: BigNumber;
110

111
  /**
112
   * @param chainId - Chain ID for this token
113
   * @param address - The contract address on the chain on which this token lives
114
   * @param decimals - Decimals for this token
115
   * @param symbol - Symbol for this token
116
   * @param name - Name for this token
117
   * @param bypassChecksum - If true it only checks for length === 42, startsWith 0x and contains only hex characters
118
   * @param buyFeeBps - Buy fee tax for FOT tokens, in basis points
119
   * @param sellFeeBps - Sell fee tax for FOT tokens, in basis points
120
   */
121
  constructor(
122
    chainId: number,
123
    address: string,
124
    decimals: number,
125
    symbol?: string,
126
    name?: string,
127
    bypassChecksum?: boolean,
128
    buyFeeBps?: BigNumber,
129
    sellFeeBps?: BigNumber
130
  );
131

132
  /**
133
   * Returns true if the two tokens are equivalent, i.e. have the same chainId and address
134
   * @param other - Other currency to compare
135
   */
136
  equals(other: Currency): boolean;
137

138
  /**
139
   * Returns true if the address of this token sorts before the address of the other token
140
   * @param other - Other token to compare
141
   * @throws if the tokens have the same address
142
   * @throws if the tokens are on different chains
143
   */
144
  sortsBefore(other: Token): boolean;
145

146
  /**
147
   * Return this token, which does not need to be wrapped
148
   */
149
  get wrapped(): Token;
150
}
151
```
152

153
### WETH9 Token Instances
154

155
Pre-configured WETH9 token instances for supported chains.
156

157
```typescript { .api }
158
/**
159
 * Known WETH9 implementation addresses, used in Ether#wrapped
160
 */
161
const WETH9: { [chainId: number]: Token };
162
```
163

164
**Usage Examples:**
165

166
```typescript
167
import { ChainId, Token, Ether, WETH9 } from "@uniswap/sdk-core";
168

169
// Create a custom ERC20 token
170
const USDC = new Token(
171
  ChainId.MAINNET,
172
  "0xA0b86a33E6424b73E63872f681e2230aDC3D3dC",
173
  6,
174
  "USDC",
175
  "USD Coin"
176
);
177

178
// Create native Ether currency
179
const ether = Ether.onChain(ChainId.MAINNET);
180

181
// Get wrapped version of native currency
182
const weth = ether.wrapped;
183
console.log(weth.address); // WETH9 address for mainnet
184

185
// Access pre-configured WETH9 instances
186
const wethMainnet = WETH9[ChainId.MAINNET];
187
console.log(wethMainnet.symbol); // "WETH"
188

189
// Compare currencies
190
const usdc2 = new Token(
191
  ChainId.MAINNET,
192
  "0xA0b86a33E6424b73E63872f681e2230aDC3D3dC",
193
  6,
194
  "USDC",
195
  "USD Coin"
196
);
197

198
console.log(USDC.equals(usdc2)); // true - same chain and address
199
console.log(USDC.equals(ether)); // false - different currency types
200

201
// Token sorting (useful for pair ordering)
202
const tokenA = new Token(ChainId.MAINNET, "0x1111111111111111111111111111111111111111", 18);
203
const tokenB = new Token(ChainId.MAINNET, "0x2222222222222222222222222222222222222222", 18);
204

205
console.log(tokenA.sortsBefore(tokenB)); // true - address A < address B
206

207
// Fee-on-transfer token support
208
import { BigNumber } from "@ethersproject/bignumber";
209

210
const fotToken = new Token(
211
  ChainId.MAINNET,
212
  "0x3333333333333333333333333333333333333333",
213
  18,
214
  "FOT",
215
  "Fee on Transfer Token",
216
  false,
217
  BigNumber.from(100), // 1% buy fee
218
  BigNumber.from(200)  // 2% sell fee
219
);
220

221
console.log(fotToken.buyFeeBps?.toString()); // "100"
222
console.log(fotToken.sellFeeBps?.toString()); // "200"
223
```
224

225
## Types
226

227
```typescript { .api }
228
/**
229
 * Union type representing any currency (native or token)
230
 */
231
type Currency = NativeCurrency | Token;
232
```