uniswap/uniswap-ai/swap-integration

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

Routing Types Quick Reference

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.

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 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 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 0: Permission Pre-Check (Permissioned Pools Only)

Some tokens trade only through a permissioned pool. An allowlist contract decides which wallets may hold and trade the token, and the swap endpoints reject any wallet that is not on the list. Call this endpoint before quoting, so a wallet that cannot trade surfaces here and not as a reverted swap.

POST /permissions

Request:

{
  "walletAddress": "0x...",
  "tokens": ["0x..."],
  "chainId": 1
}

tokens takes up to two addresses. chainId here is a number, while /quote wants tokenInChainId and tokenOutChainId as strings.

Response:

{
  "requestId": "e63f1e1e-b9e9-411a-bcc8-ff18ce4e77cf",
  "results": [
    {
      "token": "0x...",
      "isPermissioned": true,
      "isAllowlisted": false,
      "adapterTokenAddress": "0x...",
      "kycUrl": "https://your-kyc-provider.example/verify",
      "issuer": "Your Issuer Name"
    }
  ]
}

adapterTokenAddress is present when the token is permissioned. kycUrl is present when the wallet is not allowlisted, and points at the identity check (KYC) the user has to pass. issuer is the display name for that verification provider.

Three outcomes:

This endpoint needs `x-api-key` like every other Trading API call. The published example for it omits the header. Without one the endpoint returns 401 and {"errorCode":"Unauthorized","detail":"Unauthenticated api key or session"}, so an integration copied from that example fails before it reaches the permission logic.

Universal Router 2.2.0 or higher is required for quotes and swaps involving a permissioned token. Send x-universal-router-version: 2.2.0 on the /quote and /swap calls for these tokens. The plain UniversalRouter deployment is a different, non-permissioned router. Only the #v2.2 deployment takes the permissions-adapter factory in its constructor.

Issuing a permissioned token is a different job: see the permissioned-pools-issuer skill in the uniswap-permissioned-pools plugin.

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:

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: