/v4-sdk-integration

name: v4-sdk-integration
description: >
  App-layer SDK guide for building swap and liquidity experiences directly with the Uniswap v4 SDK.
  Use when user asks about "v4 sdk", "uniswap v4", "v4 swap", "v4 liquidity", "PoolManager",
  "V4Planner", "StateView", "PositionManager", "pool state", "v4 position", "uniswap sdk",
  or when building swap/liquidity UX directly with SDKs rather than via the Trading API.
allowed-tools: Read, Write, Edit, Glob, Grep, Bash(npm:*), Bash(npx:*), Bash(yarn:*), Bash(curl:*), WebFetch
model: opus
license: MIT
metadata:
  author: uniswap
  version: '1.0.1'

Uniswap v4 SDK Integration

> App-layer SDK for swaps, quotes, and liquidity. For Solidity hook contracts, use the > `uniswap-hooks` skill. For Trading API or v3-centric swaps, use the `swap-integration` skill.

When to Use

• Token swap UI (single-hop or multi-hop)
• Quote/price display before executing a trade
• Liquidity position management (add/remove/collect)
• Pool state reads (price, tick, liquidity)

Packages

npm i @uniswap/v4-sdk @uniswap/sdk-core @uniswap/universal-router-sdk

---

v4 vs v3 Decision Table

| Aspect | v3 | v4 | | ------------------ | -------------------------- | --------------------------------------------- | | Swap execution | SwapRouter directly | Universal Router required (V4Planner) | | Pool architecture | One contract per pool | Singleton PoolManager | | Pool state reads | Direct pool contract | StateView contract | | Native ETH | Wrap to WETH | Native support (`Ether.onChain(chainId)`) | | Position NFTs | NonfungiblePositionManager | PositionManager + multicall | | Fee collection | Explicit `collect()` | Automatic on position modification | | Position discovery | Onchain enumeration | Offchain event indexing | | Token approvals | Direct approve | Permit2 required | | Contract addresses | Same across chains | Different per chain — verify from deployments |

---

Core Contracts (Per Chain)

Look up addresses at <https://docs.uniswap.org/contracts/v4/deployments> — they differ per chain.

| Contract | Purpose | | ---------------- | --------------------------------------------------------------------------------------- | | PoolManager | Singleton pool state | | Universal Router | Swap execution entry point | | Quoter | Offchain quote simulation (`eth_call`, never a transaction) | | StateView | Pool state reads (getSlot0, getLiquidity) | | PositionManager | LP position lifecycle | | Permit2 | Token approval layer (same across chains: `0x000000000022D473030F116dDEE9F6B43aC78BA3`) |

---

Swap Pattern (Universal Router)

All swaps use: V4Planner -> RoutePlanner -> Universal Router `execute()`.

**Single-hop (exact input):**

import { Actions, V4Planner } from '@uniswap/v4-sdk';
import { CommandType, RoutePlanner } from '@uniswap/universal-router-sdk';

const v4Planner = new V4Planner();
v4Planner.addAction(Actions.SWAP_EXACT_IN_SINGLE, [swapConfig]);
v4Planner.addAction(Actions.SETTLE_ALL, [inputCurrency, amountIn]);
v4Planner.addAction(Actions.TAKE_ALL, [outputCurrency, amountOutMinimum]);

const routePlanner = new RoutePlanner();
routePlanner.addCommand(CommandType.V4_SWAP, [v4Planner.actions, v4Planner.params]);

const deadline = Math.floor(Date.now() / 1000) + 3600;
// Note: universalRouter.execute() is pseudocode for the viem call pattern.
// With viem, use: walletClient.writeContract({ address: UNIVERSAL_ROUTER_ADDRESS, abi: universalRouterAbi, functionName: 'execute', args: [routePlanner.commands, [v4Planner.finalize()], deadline], ...txOptions })
await universalRouter.execute(routePlanner.commands, [v4Planner.finalize()], deadline, txOptions);

**Multi-hop (exact input):**

import { Actions, V4Planner, encodeMultihopExactInPath } from '@uniswap/v4-sdk';
import { CommandType, RoutePlanner } from '@uniswap/universal-router-sdk';

const v4Planner = new V4Planner();
// Build multi-hop path: tokenA -> tokenB -> tokenC
const path = encodeMultihopExactInPath([poolKeyAB, poolKeyBC], tokenA);
v4Planner.addAction(Actions.SWAP_EXACT_IN, [{ path, amountIn, amountOutMinimum }]);
// SETTLE_ALL uses first pool's input currency; TAKE_ALL uses last pool's output currency
v4Planner.addAction(Actions.SETTLE_ALL, [tokenA, amountIn]);
v4Planner.addAction(Actions.TAKE_ALL, [tokenC, amountOutMinimum]);

const routePlanner = new RoutePlanner();
routePlanner.addCommand(CommandType.V4_SWAP, [v4Planner.actions, v4Planner.params]);

const deadline = Math.floor(Date.now() / 1000) + 3600;
// Note: universalRouter.execute() is pseudocode for the viem call pattern.
// With viem, use: walletClient.writeContract({ address: UNIVERSAL_ROUTER_ADDRESS, abi: universalRouterAbi, functionName: 'execute', args: [routePlanner.commands, [v4Planner.finalize()], deadline], ...txOptions })
await universalRouter.execute(routePlanner.commands, [v4Planner.finalize()], deadline, txOptions);

**SwapConfig** (`SwapExactInSingle`):

const swapConfig = {
  poolKey: { currency0, currency1, fee, tickSpacing, hooks },
  zeroForOne,
  amountIn,
  amountOutMinimum,
  hookData: '0x00',
};

---

Quoting Pattern

The Quoter is **not** a `view` function. Uniswap's own guide explains why: the v4 Quoter contracts "rely on state-changing calls designed to