uniswap/uniswap-ai/v4-sdk-integration

Claude Code and agent skill by uniswap/uniswap-ai

Trust tier 3
  • community
Source check pending

Checking that the SKILL.md file is still in the repository.

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.

Install

npx vskill@latest install uniswap/uniswap-ai/v4-sdk-integration

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

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

v4 vs v3 Decision Table

Aspectv3v4
Swap executionSwapRouter directlyUniversal Router required (V4Planner)
Pool architectureOne contract per poolSingleton PoolManager
Pool state readsDirect pool contractStateView contract
Native ETHWrap to WETHNative support (Ether.onChain(chainId))
Position NFTsNonfungiblePositionManagerPositionManager + multicall
Fee collectionExplicit collect()Automatic on position modification
Position discoveryOnchain enumerationOffchain event indexing
Token approvalsDirect approvePermit2 required
Contract addressesSame across chainsDifferent per chain — verify from deployments

Core Contracts (Per Chain)

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

ContractPurpose
PoolManagerSingleton pool state
Universal RouterSwap execution entry point
QuoterOffchain quote simulation (eth_call, never a transaction)
StateViewPool state reads (getSlot0, getLiquidity)
PositionManagerLP position lifecycle
Permit2Token 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():

OperationSDK Method
Add liquidityV4PositionManager.addCallParameters(position, options)
Remove liquidityV4PositionManager.removeCallParameters(position, options)
Collect feesV4PositionManager.collectCallParameters(options)
Create positionV4PositionManager.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.

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)

Security

  • Security scanPassed, 100 of 100Pattern checks on the skill's files.
  • Model reviewPassed

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

Source

Popularity

Repository stars
230
Repository forks
37
7-day trend score
27

Stars and forks are for the whole GitHub repository, not this skill alone. Refreshed 12 Sep 2026, a month ago.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/uniswap/uniswap-ai/v4-sdk-integration/badge)](https://verified-skill.com/skills/uniswap/uniswap-ai/v4-sdk-integration)

Something wrong with this skill or its page? Tell us.