Name: v4-sdk-integration
Author: uniswap

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/

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 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): Multi hop (exact input): SwapConfig ( SwapExactInSingle ): 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 be reverted to return the desired data" (<https://developers.uniswap.org/docs/sdks/v4/guides/swapping/quoting ). Sending it as a real transaction both wastes gas and cannot hand the value back to your code. The rule, independent of library: simulate the quote through eth call . Never send it as a transaction. Each library spells that simulation differently — pick the one matching your stack, not the one you saw in a guide. quoteExactInputSingle returns two values — (uint256 amountOut, uint256 gasEstimate) — so destructure it. Only amountOut feeds amountOutMinimum ; passing the whole tuple is a bug. Four available methods: quoteExactInputSingle — single hop, exact input amount quoteExactInput — multi hop, exact input amount quoteExactOutputSingle — single hop, exact output amount quoteExactOutput — multi hop, exact output amount Pool State Reads (StateView) ERC20 Approval Flow (Permit2) ERC20 swaps require two approvals — token Permit2, then Permit2 Universal Router: Native ETH swaps bypass both approvals — pass value in the transaction options instead. Position Management (PositionManager) All operations use PositionManager.multicall() : Operation SDK Method Add liquidity V4PositionManager.addCallParameters(position, options) Remove liquidity V4PositionManager.removeCallParameters(position, options) Collect fees V4PositionManager.collectCallParameters(options) Create position V4PositionManager.createCallParameters(position, options) Strict Rules NEVER call PoolManager directly for swaps — ALWAYS route through Universal Router. NEVER assume contract addresses are the same across chains — look up from the deployments page. NEVER send the Quoter as a transaction (gas expensive, and it cannot return the value) — ALWAYS simulate it through eth call : viem simulateContract , ethers v6 .staticCall , ethers v5 callStatic . NEVER skip Permit2 for ERC20 swaps — direct approve to Universal Router will not work. ALWAYS set a deadline on swaps and LP operations. ALWAYS handle native ETH with Ether.onChain(chainId) , not WETH, in v4 pool contexts. ALWAYS use Pool.getPoolId() to compute pool identifiers — do not construct manually. Links SDK overview: <https://docs.uniswap.org/sdk/v4/overview Swap guides: <https://docs.uniswap.org/sdk/v4/guides/swaps/quoting Liquidity guide: <https://docs.uniswap.org/sdk/v4/guides/liquidity/add remove liquidity Pool data: <https://docs.uniswap.org/sdk/v4/guides/advanced/pool data Deployments: <https://docs.uniswap.org/contracts/v4/deployments npm: <https://www.npmjs.com/package/@uniswap/v4 sdk Related Skills swap integration — Trading API and v3 centric swap integration (not direct v4 SDK) uniswap hooks — Solidity hook contract generation (not app layer SDK)