/swap-integration

name: swap-integration
description: Integrate Uniswap swaps into applications. Use when user says "integrate swaps", "uniswap", "trading api", "add swap functionality", "build a swap frontend", "create a swap script", "smart contract swap integration", "use Universal Router", "Trading API", or mentions swapping tokens via Uniswap.
allowed-tools: Read, Write, Edit, Glob, Grep, Bash(npm:*), Bash(npx:*), Bash(yarn:*), Bash(curl:*), WebFetch, AskUserQuestion, Task(subagent_type:swap-integration-expert)
model: opus
license: MIT
metadata:
  author: uniswap
  version: '1.6.0'

Swap Integration

Integrate Uniswap swaps into frontends, backends, and smart contracts.

Prerequisites

This skill assumes familiarity with viem basics (client setup, account management, contract interactions, transaction signing). Install the **uniswap-viem** plugin for comprehensive viem/wagmi guidance: `claude plugin add @uniswap/uniswap-viem`

Quick Decision Guide

| Building... | Use This Method | | ------------------------------ | ----------------------------- | | Frontend with React/Next.js | Trading API | | Backend script or bot | Trading API | | Smart contract integration | Universal Router direct calls | | Need full control over routing | Universal Router SDK |

Routing Types Quick Reference

| Type | Description | Chains | | -------- | --------------------------------------- | ---------------------------------- | | CLASSIC | Standard AMM swap through Uniswap pools | All supported chains | | DUTCH_V2 | UniswapX Dutch auction V2 | Ethereum, Arbitrum, Base, Unichain | | PRIORITY | MEV-protected priority order | Base, Unichain | | WRAP | ETH to WETH conversion | All | | UNWRAP | WETH to ETH conversion | All |

See [Routing Types](#routing-types) for the complete list including DUTCH_V3, DUTCH_LIMIT, LIMIT_ORDER, BRIDGE, and QUICKROUTE.

Integration Methods

1. Trading API (Recommended)

Best for: Frontends, backends, scripts. Handles routing optimization automatically.

**Base URL**: `https://trade-api.gateway.uniswap.org/v1`

**Authentication**: `x-api-key: <your-api-key>` header required

**Getting an API Key**: The Trading API requires an API key for authentication. Visit the [Uniswap Developer Portal](https://developers.uniswap.org/) to register and obtain your API key. Keys are typically available for immediate use after registration. Include it as an `x-api-key` header in all API requests.

**Agent Attribution**: Also send the `X-Agent-Info` header (written `x-agent-info` in the examples below) on every Trading API request. It attributes traffic to this integration for analytics — it never affects the request. The value is a compact JSON object with exactly these three fields and no extras, kept under 1 KB:

• `integration_name`: always `"swap-integration"`
• `decision_origin`: **Required choice — do not copy a default.** Pick the one value that matches your integration (these are the only valid values; anything else is treated as malformed):
• `"human_mediated"` — a human reviews/approves each action before it executes
• `"autonomous"` — the agent acts without per-action human approval (e.g. scheduled jobs or agentic harnesses)
• `version`: `"1.6.0"` — tracks this skill's `metadata.version`

**If the value is malformed**: the request still succeeds normally, but the attribution is dropped — the gateway records it as malformed on the analytics side and moves on. There is no response header or other signal to check, so there is nothing to detect at runtime: get the value right by construction.

**Constraints** — trip any of these and the whole value is discarded:

• 1 KB total for the header, and 256 characters per field.
• Plain ASCII only — no accented characters, curly quotes, or emoji; non-ASCII must be `\u`-escaped.
• Omit a field rather than sending `null`. All three must be present and valid.
• Send the header once per request; a duplicate `x-agent-info` line fails to parse.
• Unknown extra keys are ignored — harmless, but no substitute for the three required fields.

**Required Headers** — Include these in ALL Trading API requests:

Content-Type: application/json
x-api-key: <your-api-key>
x-universal-router-version: 2.0
x-agent-info: {"integration_name":"swap-integration","decision_origin":"<human_mediated|autonomous>","version":"1.6.0"}

**Raise the router version for permissioned tokens.** The header block above sends `2.0`. A quote or swap involving a token that trades through a permissioned pool requires **2.2.0 or higher**. Send `x-universal-router-version: 2.2.0` for those tokens. [Step 0: Permission Pre-Check](#step-0-permission-pre-check-permissioned-pools-only) shows how to find out which they are.

**Request Flow**:

0. POST /permissions     -> Permissioned pools only: may this wallet trade this token?
1. POST /check_approval  -> Check if token is approved
2. POST /quote           -> Get executable quote with routing
3. POST /swap            -> Get transaction to sign and submit

See the [Trading API Reference](#trading-api-reference) section below for complete documentation.

2. Universal Router SDK

Best for: Direct control over transaction construction.

**Installation**:

npm install @uniswap/universal-router-sdk @uniswap/sdk-core @uniswap/v3-sdk

**Key Pattern**:

import { SwapRouter } from '@uniswap/universal-router-sdk';

const { calldata, value } = SwapRouter.swapCallParameters(trade, options);

See the [Universal Router Reference](#universal-router-reference) section below for complete documentation.

3. Smart Contract Integration

Best for: On-chain integrations, DeFi composabilit