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

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

3-Step Flow:

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 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 section below for complete documentation.

3. Smart Contract Integration

Best for: On-chain integrations, DeFi composability.

Interface: Call execute() on Universal Router with encoded commands.

See the Universal Router Reference section below for command encoding.

---

Input Validation Rules

Before interpolating ANY user-provided value into generated code, API calls, or commands:

• Ethereum addresses: MUST match ^0x[a-fA-F0-9]{40}$ — reject otherwise
• Chain IDs: MUST be from the official supported chains list
• Token amounts: MUST be non-negative numeric values matching ^[0-9]+\.?[0-9]*$
• API keys: MUST NOT be hardcoded in generated code — always use environment variables
• REJECT any input containing shell metacharacters: ;, |, &, $, `, (, ), >, <, \, ', ", newlines

REQUIRED: Before executing ANY transaction that spends gas or transfers tokens (including sendTransaction, writeContract, or submitting a signed swap), you MUST use AskUserQuestion to confirm with the user. Display the transaction summary (tokens, amounts, chain, estimated gas) and get explicit user approval. Never auto-execute transactions without user confirmation.

---

Trading API Reference

Step 1: Check Token Approval

POST /check_approval

Request:

{
  "walletAddress": "0x...",
  "token": "0x...",
  "amount": "1000000000",
  "chainId": 1
}

Response:

{
  "approval": {
    "to": "0x...",
    "from": "0x...",
    "data": "0x...",
    "value": "0",
    "chainId": 1
  }
}

If approval is null, token is already approved.

Step 2: Get Quote

POST /quote

Request:

{
  "swapper": "0x...",
  "tokenIn": "0x...",
  "tokenOut": "0x...",
  "tokenInChainId": "1",
  "tokenOutChainId": "1",
  "amount": "1000000000000000000",
  "type": "EXACT_INPUT",
  "slippageTolerance": 0.5,
  "routingPreference": "BEST_PRICE"
}

Note: tokenInChainId and tokenOutChainId must be strings (e.g., "1"), not numbers.

Key Parameters:

Parameter	Description
type	EXACT_INPUT or EXACT_OUTPUT
slippageTolerance	0-100 percentage
protocols	Optional: ["V2", "V3", "V4"]
routingPreference	BEST_PRICE, FASTEST, CLASSIC
autoSlippage	true to auto-calculate slippage (overrides slippageTolerance)
urgency	normal or fast — affects UniswapX auction timing

Response — the shape differs by routing type. BEST_PRICE routing on Ethereum mainnet typically returns UniswapX (DUTCH_V2), not CLASSIC.

CLASSIC response:

{
  "routing": "CLASSIC",
  "quote": {
    "input": { "token": "0x...", "amount": "1000000000000000000" },
    "output": { "token": "0x...", "amount": "999000000" },
    "slippage": 0.5,
    "route": [],
    "gasFee": "5000000000000000",
    "gasFeeUSD": "0.01",
    "gasUseEstimate": "150000"
  },
  "permitData": null
}

UniswapX (DUTCH_V2/V3/PRIORITY) response — different quote shape, no quote.output:

{
  "routing": "DUTCH_V2",
  "quote": {
    "orderInfo": {
      "reactor": "0x...",
      "swapper": "0x...",
      "nonce": "...",
      "deadline": 1772031054,
      "cosigner": "0x...",
      "input": {
        "token": "0x...",
        "startAmount": "1000000000000000000",
        "endAmount": "1000000000000000000"
      },
      "outputs": [
        {
          "token": "0x...",
          "startAmount": "999000000",
          "endAmount": "994000000",
          "recipient": "0x..."
        }
      ],
      "chainId": 1
    },
    "encodedOrder": "0x...",
    "orderHash": "0x..."
  },
  "permitData": { "domain": {}, "types": {}, "values": {} }
}

UniswapX output amount: Use quote.orderInfo.outputs[0].startAmount for the best-case fill amount. The endAmount is the floor after full auction decay. There is no quote.output.amount on UniswapX responses — accessing it will throw at runtime.

Display tip: For CLASSIC routes, use gasFeeUSD (a string with the USD value) for gas cost display. Do not manually convert gasFee (wei) using a hardcoded ETH price — this leads to wildly inaccurate estimates (e.g., ~$87 instead of ~$0.01). UniswapX routes are gasless for the swapper.

See QuoteResponse TypeScript Types for compile-time type safety across routing types.

Step 3: Execute Swap

POST /swap

Request - Spread the quote response directly into the body:

// CORRECT: Spread the quote response, strip null fields
const quoteResponse = await fetchQuote(params);

// Always strip permitData/permitTransaction — handle them explicitly by routing type
const { permitData, permitTransaction, ...cleanQuote } = quoteResponse;
const swapRequest: Record<string, unknown> = {