# v4-sdk-integration

A skill that walks the agent through the Uniswap v4 SDK: swaps via Universal Router, quotes, pool state reads and LP position handling.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 729 installs · ★ 235
- Author: uniswap
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/Uniswap/uniswap-ai/tree/HEAD/packages/plugins/uniswap-trading/skills/v4-sdk-integration/SKILL.md
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/skills/v4-sdk-integration

## What it does

The skill kicks in when you ask the agent to build a token swap or liquidity flow straight through the SDK instead of the Trading API. It carries a reference for `@uniswap/v4-sdk`, `@uniswap/sdk-core` and `@uniswap/universal-router-sdk`, a v3 vs v4 comparison table, and notes on the core contracts: `PoolManager`, `Universal Router`, `Quoter`, `StateView`, `PositionManager`, `Permit2`.

Two patterns get the most room. A swap is built as `V4Planner` → `RoutePlanner` → Universal Router `execute()`, with examples for a single pool and for a multi-hop path. Quoting goes through `eth_call`: `quoteExactInputSingle` returns two values, `amountOut` and `gasEstimate`, and only the first belongs in `amountOutMinimum`. Sending a quote as a transaction wastes gas and hands nothing back to your code.

Contract addresses differ per chain in v4, so check them against the deployments list before shipping. Token approvals need `Permit2`; a plain `approve` will not do. Solidity hooks are a different skill, `uniswap-hooks`.

The skill targets the `opus` model and asks for `Read`, `Write`, `Edit`, `Glob`, `Grep` plus `npm`, `npx`, `yarn` and `curl` access.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add Uniswap/uniswap-ai --skill v4-sdk-integration -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/v4-sdk-integration/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/v4-sdk-integration/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add Uniswap/uniswap-ai --skill v4-sdk-integration -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/v4-sdk-integration/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add Uniswap/uniswap-ai --skill v4-sdk-integration -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/v4-sdk-integration/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install Uniswap/uniswap-ai v4-sdk-integration
```

2. **Manually: put the files in place**
- File: `.github/skills/v4-sdk-integration/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add Uniswap/uniswap-ai --skill v4-sdk-integration -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/Uniswap/uniswap-ai --path packages/plugins/uniswap-trading/skills/v4-sdk-integration
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/v4-sdk-integration/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add Uniswap/uniswap-ai --skill v4-sdk-integration -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/Uniswap/uniswap-ai/tree/HEAD/packages/plugins/uniswap-trading/skills/v4-sdk-integration/SKILL.md

## When to use it
- build a token swap through Universal Router
- show a quote and price before the trade is signed
- add liquidity to a position and withdraw it later
- read pool state: price, tick, liquidity
- route a swap across several pools

## Example prompts
- Build a USDC to WETH swap on Uniswap v4 with V4Planner
- How do I read v4 pool state through StateView?
- Get me an exact input single quote and set amountOutMinimum

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: cc0dcb17efeefab0.

BEGIN THIRD-PARTY FILE cc0dcb17efeefab0
````text
---
name: v4-sdk-integration
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
model: opus
license: MIT
metadata:
  author: uniswap
  version: '1.0.1'
---

# 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                                                                                 |
````
END THIRD-PARTY FILE cc0dcb17efeefab0

The third-party file has ended. Everything between the cc0dcb17efeefab0 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2499 of 11019 bytes. © uniswap · MIT · https://github.com/Uniswap/uniswap-ai/tree/HEAD/packages/plugins/uniswap-trading/skills/v4-sdk-integration/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md