0
# Uniswap SDK Core
1

2
The Uniswap SDK Core provides foundational TypeScript utilities and abstractions for building applications on top of Uniswap V3, the decentralized exchange protocol on Ethereum. It serves as shared foundational code across multiple Uniswap TypeScript SDKs, offering essential primitives for working with tokens, addresses, mathematical operations, and blockchain interactions.
3

4
## Package Information
5

6
- **Package Name**: @uniswap/sdk-core
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @uniswap/sdk-core`
10

11
## Core Imports
12

13
```typescript
14
import { ChainId, Token, Ether, CurrencyAmount, Price, Percent, Fraction } from "@uniswap/sdk-core";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { ChainId, Token, Ether, CurrencyAmount, Price, Percent, Fraction } = require("@uniswap/sdk-core");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { ChainId, Token, Ether, CurrencyAmount, Fraction, Percent } from "@uniswap/sdk-core";
27

28
// Create a token (UNI token)
29
const UNI = new Token(
30
  ChainId.MAINNET,
31
  "0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984",
32
  18,
33
  "UNI",
34
  "Uniswap"
35
);
36

37
// Create native currency (Ether)
38
const ether = Ether.onChain(ChainId.MAINNET);
39

40
// Create currency amounts
41
const uniAmount = CurrencyAmount.fromRawAmount(UNI, "1000000000000000000"); // 1 UNI (18 decimals)
42
const etherAmount = CurrencyAmount.fromRawAmount(ether, "1000000000000000000"); // 1 ETH (18 decimals)
43

44
// Work with fractions and percentages
45
const fraction = new Fraction(1, 100);
46
const percent = new Percent(25, 100); // 25%
47

48
console.log(uniAmount.toExact()); // "1"
49
console.log(etherAmount.toExact()); // "1"
50
console.log(percent.toFixed(2)); // "25.00"
51
```
52

53
## Architecture
54

55
The SDK Core is built around several key components:
56

57
- **Chain Management**: Comprehensive support for 20+ blockchain networks with predefined chain IDs and contract addresses
58
- **Currency System**: Type-safe abstractions for native currencies (ETH, MATIC, etc.) and ERC20 tokens
59
- **Mathematical Operations**: Precise fraction-based arithmetic using JSBI to avoid floating-point errors
60
- **Price Calculations**: Type-safe price representations between currency pairs
61
- **Utility Functions**: Address validation, mathematical operations, and specialized blockchain utilities
62

63
## Capabilities
64

65
### Chain and Address Management
66

67
Comprehensive blockchain network support with pre-configured contract addresses for Uniswap protocols across multiple chains including Ethereum, Polygon, Arbitrum, Optimism, and more.
68

69
```typescript { .api }
70
enum ChainId {
71
  MAINNET = 1,
72
  OPTIMISM = 10,
73
  ARBITRUM_ONE = 42161,
74
  POLYGON = 137,
75
  // ... and many more
76
}
77

78
const SUPPORTED_CHAINS: readonly ChainId[];
79
```
80

81
[Chains and Addresses](./chains-and-addresses.md)
82

83
### Currency System
84

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

87
```typescript { .api }
88
abstract class BaseCurrency {
89
  readonly chainId: number;
90
  readonly decimals: number;
91
  readonly symbol?: string;
92
  readonly name?: string;
93
  abstract get wrapped(): Token;
94
  abstract equals(other: Currency): boolean;
95
}
96

97
class Token extends BaseCurrency {
98
  readonly address: string;
99
  constructor(
100
    chainId: number,
101
    address: string,
102
    decimals: number,
103
    symbol?: string,
104
    name?: string,
105
    bypassChecksum?: boolean
106
  );
107
}
108

109
class Ether extends NativeCurrency {
110
  static onChain(chainId: number): Ether;
111
}
112
```
113

114
[Currency System](./currency-system.md)
115

116
### Mathematical Operations
117

118
Precise fractional arithmetic and currency amount calculations using JSBI for handling large numbers without precision loss, essential for financial applications.
119

120
```typescript { .api }
121
class Fraction {
122
  readonly numerator: JSBI;
123
  readonly denominator: JSBI;
124
  constructor(numerator: BigintIsh, denominator?: BigintIsh);
125
  add(other: Fraction | BigintIsh): Fraction;
126
  multiply(other: Fraction | BigintIsh): Fraction;
127
  toSignificant(significantDigits: number): string;
128
}
129

130
class CurrencyAmount<T extends Currency> extends Fraction {
131
  readonly currency: T;
132
  static fromRawAmount<T extends Currency>(currency: T, rawAmount: BigintIsh): CurrencyAmount<T>;
133
  toExact(): string;
134
}
135

136
class Price<TBase extends Currency, TQuote extends Currency> extends Fraction {
137
  readonly baseCurrency: TBase;
138
  readonly quoteCurrency: TQuote;
139
  quote(currencyAmount: CurrencyAmount<TBase>): CurrencyAmount<TQuote>;
140
}
141
```
142

143
[Mathematical Operations](./mathematical-operations.md)
144

145
### Utilities
146

147
Essential utility functions for address validation, price impact calculations, mathematical operations, and specialized blockchain utilities.
148

149
```typescript { .api }
150
function validateAndParseAddress(address: string): string;
151
function computePriceImpact<TBase extends Currency, TQuote extends Currency>(
152
  midPrice: Price<TBase, TQuote>,
153
  inputAmount: CurrencyAmount<TBase>,
154
  outputAmount: CurrencyAmount<TQuote>
155
): Percent;
156
function sqrt(value: JSBI): JSBI;
157
```
158

159
[Utilities](./utilities.md)
160

161
## Types
162

163
```typescript { .api }
164
type BigintIsh = JSBI | string | number;
165
type Currency = NativeCurrency | Token;
166
type SupportedChainsType = (typeof SUPPORTED_CHAINS)[number];
167

168
enum TradeType {
169
  EXACT_INPUT,
170
  EXACT_OUTPUT,
171
}
172

173
enum Rounding {
174
  ROUND_DOWN,
175
  ROUND_HALF_UP,
176
  ROUND_UP,
177
}
178

179
interface AddressMap {
180
  [chainId: number]: string;
181
}
182

183
// External types from @ethersproject
184
type BytesLike = string | Uint8Array;
185
interface BigNumber {
186
  readonly _hex: string;
187
  readonly _isBigNumber: boolean;
188
}
189
```