AGENT SKILL

v4-sdk-integration

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.

License 许可
MIT
所属仓库
themusebook/skills
最近更新
2026-11-02
Stars
★ 0
Forks
1

01 前言 Front Matter

name
v4-sdk-integration
model
opus
license
MIT
metadata
{ "author": "uniswap", "version": "1.0.0" }
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

03 SKILL.md 正文

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 (callStatic)
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

Use the Quoter contract with callStatic — this simulates the swap offchain without executing it or spending gas.

const quote = await quoterContract.callStatic.quoteExactInputSingle({
  poolKey,
  zeroForOne,
  exactAmount: amountIn,
  hookData: '0x00',
});

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)

import { Pool } from '@uniswap/v4-sdk';

const poolId = Pool.getPoolId(currency0, currency1, fee, tickSpacing, hooks);

const [slot0, liquidity] = await Promise.all([
  stateViewContract.getSlot0(poolId),
  stateViewContract.getLiquidity(poolId),
]);
// slot0 → { sqrtPriceX96, tick, protocolFee, lpFee }

ERC20 Approval Flow (Permit2)

ERC20 swaps require two approvals — token -> Permit2, then Permit2 -> Universal Router:

// Step 1: Approve Permit2 on the token contract
await erc20Contract.approve(PERMIT2_ADDRESS, MaxUint256);

// Step 2: Approve Universal Router on Permit2
await permit2Contract.approve(tokenAddress, UNIVERSAL_ROUTER_ADDRESS, MAX_UINT160, deadline);

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)
const { calldata, value } = V4PositionManager.addCallParameters(position, {
  slippageTolerance: new Percent(50, 10_000),
  deadline: deadline.toString(),
  tokenId: tokenId.toString(),
  useNative: token0.isNative ? Ether.onChain(chainId) : undefined,
  batchPermit,
  hookData: '0x',
});

await walletClient.writeContract({
  address: POSITION_MANAGER_ADDRESS,
  functionName: 'multicall',
  args: [[calldata]],
  value: BigInt(value),
});

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 call Quoter onchain (gas expensive) — ALWAYS use callStatic for offchain simulation.
  • 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


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)

04 同仓库更多 Skills

themusebook
themusebook/skills

youtube-clipper

YouTube 视频智能剪辑工具。下载视频和字幕,AI 分析生成精细章节(几分钟级别), 用户选择片段后自动剪辑、翻译字幕为中英双语、烧录字幕到视频,并生成总结文案。 使用场景:当用户需要剪辑 YouTube 视频、生成短视频片段、制作双语字幕版本时。 关键词:视频剪辑、YouTube、字幕翻译、双语字幕、视频下载、clip video

★ 0
themusebook
themusebook/skills

viem-integration

Integrate EVM blockchains using viem. Use when user says "read blockchain data", "send transaction", "interact with smart contract", "connect to Ethereum", "use viem", "use wagmi", "wallet integration", "viem setup", or mentions blockchain/EVM development with TypeScript.

★ 0
themusebook
themusebook/skills

v4-security-foundations

Security-first Uniswap v4 hook development. Use when user mentions "v4 hooks", "hook security", "PoolManager", "beforeSwap", "afterSwap", or asks about V4 hook best practices, vulnerabilities, or audit requirements.

★ 0
themusebook
themusebook/skills

v4-hook-generator

Generate Uniswap v4 hook contracts via OpenZeppelin MCP. Use when building custom swap logic, async swaps, hook-owned liquidity, custom curves, dynamic fees, MEV protection, limit orders, or oracle hooks.

★ 0
themusebook
themusebook/skills

testing

For testing with Light Protocol programs and clients on localnet, devnet, and mainnet validation.

★ 0
themusebook
themusebook/skills

swap-planner

This skill should be used when the user asks to "swap tokens", "trade ETH for USDC", "exchange tokens on Uniswap", "buy tokens", "sell tokens", "convert ETH to stablecoins", "find memecoins", "discover tokens", "research tokens", "tokens to buy", "find tokens to swap", "what should I buy", or mentions swapping, trading, researching, discovering, buying, or exchanging tokens on any Uniswap-supported chain. Supports both known token swaps and token discovery workflows (discovery uses keyword search and web search — there is no live "trending" feed). Generates deep links to execute swaps in the Uniswap interface.

★ 0