v4-sdk-integration

使用方法

复制安装命令，在自己的智能体环境安装前先检查源码包。
从原始文档核对所需工具、凭据和支持的宿主。
说明输入材料与期望交付物，并对照来源检查输出。

npx skills add https://github.com/uniswap/uniswap-ai --skill v4-sdk-integration

开始前需了解

安装不包含模型订阅、API 额度或访问文件的权限。
仓库星数和安装量反映活跃情况，不等于独立质量或安全测试。

仓库原始内容

按源仓库内容呈现，保留标题、案例、代码、表格、链接以及原文引用的演示图片。

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

bash

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):

typescript

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):

typescript

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):

typescript

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

typescript

// viem — the stack the rest of this skill assumes.
// simulateContract, not readContract: the quote method is nonpayable, not view.
const {
  result: [amountOut, gasEstimate],
} = await publicClient.simulateContract({
  address: QUOTER_ADDRESS,
  abi: quoterAbi,
  functionName: 'quoteExactInputSingle',
  args: [{ poolKey, zeroForOne, exactAmount: amountIn, hookData: '0x00' }],
});

// ethers v6 — `.staticCall` hangs off the method itself
const [amountOut, gasEstimate] = await quoterContract.quoteExactInputSingle.staticCall({
  poolKey,
  zeroForOne,
  exactAmount: amountIn,
  hookData: '0x00',
});

// ethers v5 only — `callStatic` was removed in v6
const [amountOut, gasEstimate] = 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)

typescript

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:

typescript

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

typescript

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

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)

使用方法

开始前需了解

Uniswap v4 SDK Integration

When to Use

Packages

v4 vs v3 Decision Table

Core Contracts (Per Chain)

Swap Pattern (Universal Router)

Quoting Pattern

Pool State Reads (StateView)

ERC20 Approval Flow (Permit2)

Position Management (PositionManager)

Strict Rules

Links

Related Skills

按任务相关推荐

更多 Skills

viem-integration

configurator

copy-trade

dca-bot

v4-sdk-integration

使用方法

开始前需了解

Uniswap v4 SDK Integration

When to Use

Packages

v4 vs v3 Decision Table

Core Contracts (Per Chain)

Swap Pattern (Universal Router)

Quoting Pattern

Pool State Reads (StateView)

ERC20 Approval Flow (Permit2)

Position Management (PositionManager)

Strict Rules

Links

Related Skills

按任务相关推荐

ecc-guide

setup-matt-pocock-skills

backend-patterns

context-budget

更多 Skills

viem-integration

configurator

copy-trade

dca-bot