0
# Uniswap Router SDK
1

2
The Uniswap Router SDK is a TypeScript library for routing swaps across Uniswap V2, V3, and V4 protocols. It provides unified access to liquidity across different AMM implementations with automatic route optimization, gas-efficient swap execution, and cross-protocol trade aggregation.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { SwapRouter, Trade, Protocol } from "@uniswap/router-sdk";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { SwapRouter, Trade, Protocol } = require("@uniswap/router-sdk");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { 
27
  SwapRouter, 
28
  Trade, 
29
  Protocol, 
30
  SwapOptions 
31
} from "@uniswap/router-sdk";
32
import { CurrencyAmount, TradeType, Percent } from "@uniswap/sdk-core";
33

34
// Create a trade across multiple protocols
35
const trade = new Trade({
36
  v2Routes: [/* V2 routes */],
37
  v3Routes: [/* V3 routes */], 
38
  v4Routes: [/* V4 routes */],
39
  mixedRoutes: [/* Mixed routes */],
40
  tradeType: TradeType.EXACT_INPUT
41
});
42

43
// Configure swap options
44
const options: SwapOptions = {
45
  slippageTolerance: new Percent(50, 10000), // 0.5%
46
  recipient: "0x...", // recipient address
47
  deadlineOrPreviousBlockhash: Math.floor(Date.now() / 1000) + 1800 // 30 min
48
};
49

50
// Generate swap call parameters
51
const { calldata, value } = SwapRouter.swapCallParameters(trade, options);
52
```
53

54
## Architecture
55

56
The Uniswap Router SDK is built around several key components:
57

58
- **SwapRouter**: Core class for encoding swap transactions across all Uniswap protocols
59
- **Trade System**: Unified trade representation aggregating routes from multiple protocols  
60
- **Route Wrappers**: Protocol-specific route classes (V2, V3, V4, Mixed) with common interfaces
61
- **Protocol Support**: Native support for Uniswap V2, V3, and V4 with mixed routing capabilities
62
- **Utility System**: Path encoding, multicall, and payment utilities for transaction construction
63
- **Type Safety**: Full TypeScript integration with generic type preservation
64

65
## Capabilities
66

67
### Swap Routing
68

69
Core swap routing functionality for encoding transactions across Uniswap V2, V3, and V4 protocols. Handles single and multi-protocol routes with automatic optimization.
70

71
```typescript { .api }
72
abstract class SwapRouter {
73
  static INTERFACE: Interface;
74
  static swapCallParameters(
75
    trades: Trade | V2Trade | V3Trade | MixedRouteTrade | (V2Trade | V3Trade | MixedRouteTrade)[],
76
    options: SwapOptions
77
  ): MethodParameters;
78
  static swapAndAddCallParameters(
79
    trades: AnyTradeType,
80
    options: SwapAndAddOptions,
81
    position: Position,
82
    addLiquidityOptions: CondensedAddLiquidityOptions,
83
    tokenInApprovalType: ApprovalTypes,
84
    tokenOutApprovalType: ApprovalTypes
85
  ): MethodParameters;
86
}
87

88
interface SwapOptions {
89
  slippageTolerance: Percent;
90
  recipient?: string;
91
  deadlineOrPreviousBlockhash?: Validation;
92
  inputTokenPermit?: PermitOptions;
93
  fee?: FeeOptions;
94
}
95
```
96

97
[Swap Routing](./swap-routing.md)
98

99
### Trade Management  
100

101
Multi-protocol trade aggregation system supporting V2, V3, V4, and mixed routes. Provides price impact calculation, slippage protection, and execution optimization.
102

103
```typescript { .api }
104
class Trade<TInput extends Currency, TOutput extends Currency, TTradeType extends TradeType> {
105
  readonly routes: IRoute<TInput, TOutput, Pair | V3Pool | V4Pool>[];
106
  readonly tradeType: TTradeType;
107
  readonly swaps: {
108
    route: IRoute<TInput, TOutput, Pair | V3Pool | V4Pool>;
109
    inputAmount: CurrencyAmount<TInput>;
110
    outputAmount: CurrencyAmount<TOutput>;
111
  }[];
112
  
113
  get inputAmount(): CurrencyAmount<TInput>;
114
  get outputAmount(): CurrencyAmount<TOutput>;
115
  get executionPrice(): Price<TInput, TOutput>;
116
  get priceImpact(): Percent;
117
  
118
  minimumAmountOut(slippageTolerance: Percent): CurrencyAmount<TOutput>;
119
  maximumAmountIn(slippageTolerance: Percent): CurrencyAmount<TInput>;
120
}
121
```
122

123
[Trade Management](./trade-management.md)
124

125
### Route Handling
126

127
Route wrapper classes providing unified interfaces for V2, V3, V4, and mixed protocol routes. Enables seamless integration across different Uniswap versions.
128

129
```typescript { .api }
130
interface IRoute<TInput extends Currency, TOutput extends Currency, TPool extends Pair | V3Pool | V4Pool> {
131
  protocol: Protocol;
132
  pools: TPool[];
133
  path: Currency[];
134
  midPrice: Price<TInput, TOutput>;
135
  input: TInput;
136
  output: TOutput;
137
  pathInput: Currency;
138
  pathOutput: Currency;
139
}
140

141
enum Protocol {
142
  V2 = 'V2',
143
  V3 = 'V3', 
144
  V4 = 'V4',
145
  MIXED = 'MIXED'
146
}
147
```
148

149
[Route Handling](./route-handling.md)
150

151
### Approval & Liquidity
152

153
Token approval and liquidity management utilities for position management and swap-and-add operations. Supports various approval strategies and NFT position handling.
154

155
```typescript { .api }
156
abstract class ApproveAndCall {
157
  static INTERFACE: Interface;
158
  static encodeApproveMax(token: Token): string;
159
  static encodeApproveZeroThenMax(token: Token): string;
160
  static encodeAddLiquidity(
161
    position: Position,
162
    minimalPosition: Position, 
163
    addLiquidityOptions: CondensedAddLiquidityOptions,
164
    slippageTolerance: Percent
165
  ): string;
166
}
167

168
enum ApprovalTypes {
169
  NOT_REQUIRED = 0,
170
  MAX = 1,
171
  MAX_MINUS_ONE = 2,
172
  ZERO_THEN_MAX = 3,
173
  ZERO_THEN_MAX_MINUS_ONE = 4
174
}
175
```
176

177
[Approval & Liquidity](./approval-liquidity.md)
178

179
### Mixed Route System
180

181
Advanced routing system for trades that span multiple Uniswap protocols. Optimizes paths across V2, V3, and V4 pools for maximum efficiency.
182

183
```typescript { .api }
184
class MixedRouteSDK<TInput extends Currency, TOutput extends Currency> {
185
  readonly pools: TPool[];
186
  readonly path: Currency[];
187
  readonly input: TInput;
188
  readonly output: TOutput;
189
  get midPrice(): Price<TInput, TOutput>;
190
}
191

192
class MixedRouteTrade<TInput extends Currency, TOutput extends Currency, TTradeType extends TradeType> {
193
  readonly swaps: {
194
    route: MixedRouteSDK<TInput, TOutput>;
195
    inputAmount: CurrencyAmount<TInput>;
196
    outputAmount: CurrencyAmount<TOutput>;
197
  }[];
198
  
199
  static async bestTradeExactIn<TInput extends Currency, TOutput extends Currency>(
200
    pools: TPool[],
201
    currencyAmountIn: CurrencyAmount<TInput>,
202
    currencyOut: TOutput,
203
    options?: BestTradeOptions
204
  ): Promise<MixedRouteTrade<TInput, TOutput, TradeType.EXACT_INPUT>[]>;
205
}
206
```
207

208
[Mixed Route System](./mixed-routes.md)
209

210
### Utilities & Extensions
211

212
Extended multicall and payment utilities for transaction batching and native ETH handling. Provides enhanced functionality beyond standard Uniswap SDK utilities.
213

214
```typescript { .api }
215
abstract class MulticallExtended {
216
  static INTERFACE: Interface;
217
  static encodeMulticall(calldatas: string | string[], validation?: Validation): string;
218
}
219

220
abstract class PaymentsExtended {
221
  static INTERFACE: Interface;
222
  static encodeUnwrapWETH9(amountMinimum: JSBI, recipient?: string, feeOptions?: FeeOptions): string;
223
  static encodeSweepToken(token: Token, amountMinimum: JSBI, recipient?: string, feeOptions?: FeeOptions): string;
224
  static encodePull(token: Token, amount: JSBI): string;
225
  static encodeWrapETH(amount: JSBI): string;
226
}
227
```
228

229
[Utilities & Extensions](./utilities.md)
230

231
## Types
232

233
Core type definitions used throughout the SDK:
234

235
```typescript { .api }
236
type TPool = Pair | V3Pool | V4Pool;
237

238
type Validation = BigintIsh | string;
239

240
interface MethodParameters {
241
  calldata: string;
242
  value: string;
243
}
244

245
type CondensedAddLiquidityOptions = Omit<MintSpecificOptions, 'createPool'> | IncreaseSpecificOptions;
246

247
interface BestTradeOptions {
248
  maxNumResults?: number;
249
  maxHops?: number;
250
}
251

252
type AnyTradeType = 
253
  | Trade<Currency, Currency, TradeType>
254
  | V2Trade<Currency, Currency, TradeType>
255
  | V3Trade<Currency, Currency, TradeType>
256
  | MixedRouteTrade<Currency, Currency, TradeType>
257
  | (V2Trade<Currency, Currency, TradeType> | V3Trade<Currency, Currency, TradeType> | MixedRouteTrade<Currency, Currency, TradeType>)[];
258
```