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
```