v4-sdk-integration

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

Core Contracts (Per Chain)

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

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

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

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

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)