swap-integration

= { ... cleanQuote } ; // CRITICAL: permitData handling differs by routing type const isUniswapX = quoteResponse . routing === 'DUTCH_V2' || quoteResponse . routing === 'DUTCH_V3' || quoteResponse . routing === 'PRIORITY' ; if ( isUniswapX ) { // UniswapX: signature only — permitData must NOT be sent to /swap // (permitData is used locally to sign the order, not submitted to the API) if ( permit2Signature ) swapRequest . signature = permit2Signature ; } else { // CLASSIC: both signature and permitData required together, or both omitted if ( permit2Signature && permitData && typeof permitData === 'object' ) { swapRequest . signature = permit2Signature ; swapRequest . permitData = permitData ; } } const swapResponse = await fetch ( ${ API_URL } /swap , { method : 'POST' , headers : { 'Content-Type' : 'application/json' , 'x-api-key' : API_KEY , 'x-universal-router-version' : '2.0' , } , body : JSON . stringify ( swapRequest ) , } ) ; const data = await swapResponse . json ( ) ; if ( ! swapResponse . ok ) throw new Error ( data . detail || 'Swap failed' ) ; // CRITICAL: Validate response before broadcasting if ( ! data . swap ?. data || data . swap . data === '' || data . swap . data === '0x' ) { throw new Error ( 'Empty swap data - quote may have expired. Please refresh.' ) ; } // Send transaction via wallet (walletClient from useWalletClient()) if ( ! walletClient ) throw new Error ( 'Wallet not connected' ) ; const tx = await walletClient . sendTransaction ( data . swap ) ; return tx ; } ; return { quote : quoteResponse ?. quote , loading , error , getQuote , executeSwap } ; } wagmi v2 Integration Pitfalls The useWalletClient() hook from wagmi v2 can return undefined even when the wallet is connected — it resolves asynchronously. This causes "wallet not connected" errors at swap time. Additionally, the returned client needs a chain for sendTransaction() to work. Recommended pattern — use @wagmi/core action functions at swap time instead of hooks: import { getWalletClient , getPublicClient , switchChain } from '@wagmi/core' ; import type { Config } from 'wagmi' ; async function executeSwapTransaction ( config : Config , chainId : number , swapTx : { to : string ; data : string ; value : string } ) { // 1. Ensure the wallet is on the correct chain await switchChain ( config , { chainId } ) ; // 2. Get wallet client with explicit chainId — avoids undefined and missing chain const walletClient = await getWalletClient ( config , { chainId } ) ; // 3. Execute the swap const hash = await walletClient . sendTransaction ( { to : swapTx . to as 0x ${ string } , data : swapTx . data as 0x ${ string } , value : BigInt ( swapTx . value || '0' ) , } ) ; // 4. Wait for confirmation const publicClient = getPublicClient ( config , { chainId } ) ; if ( ! publicClient ) throw new Error ( No public client configured for chainId ${ chainId } ) ; return publicClient . waitForTransactionReceipt ( { hash } ) ; } Why this matters : useWalletClient() hook returns { data: undefined } during async resolution, even after useAccount() shows connected getWalletClient(config, { chainId }) is a promise that resolves only when the client is ready, and includes the chain switchChain() prevents "chain mismatch" errors when the wallet is on a different network than the swap Backend Swap Script (Node.js) import { createWalletClient , createPublicClient , http , isAddress , isHex , type Address } from 'viem' ; import { privateKeyToAccount } from 'viem/accounts' ; import { mainnet } from 'viem/chains' ; const API_URL = 'https://trade-api.gateway.uniswap.org/v1' ; const API_KEY = process . env . UNISWAP_API_KEY ! ; const account = privateKeyToAccount ( process . env . PRIVATE_KEY as 0x ${ string } ) ; const publicClient = createPublicClient ( { chain : mainnet , transport : http ( ) } ) ; const walletClient = createWalletClient ( { account , chain : mainnet , transport : http ( ) } ) ; // Helper to prepare /swap request body — routing-aware permitData handling function prepareSwapRequest ( quoteResponse : Record < string , unknown

, signature ? : string ) : object { const { permitData , permitTransaction , ... cleanQuote } = quoteResponse ; const request : Record < string , unknown

= { ... cleanQuote } ; // UniswapX (DUTCH_V2, DUTCH_V3, PRIORITY): permitData is for LOCAL signing only. // The /swap body must NOT include permitData — the order is already encoded // in quote.encodedOrder. Only the signature is needed. const isUniswapX = quoteResponse . routing === 'DUTCH_V2' || quoteResponse . routing === 'DUTCH_V3' || quoteResponse . routing === 'PRIORITY' ; if ( isUniswapX ) { if ( signature ) request . signature = signature ; } else { // CLASSIC: both signature and permitData required together, or both omitted if ( signature && permitData && typeof permitData === 'object' ) { request . signature = signature ; request . permitData = permitData ; } } return request ; } // Validate swap response before broadcasting function validateSwap ( swap : { data ? : string ; to ? : string ; from ? : string } ) : void { if ( ! swap ?. data || swap . data === '' || swap . data === '0x' ) { throw new Error ( 'swap.data is empty - quote may have expired' ) ; } if ( ! isHex ( swap . data ) ) { throw new Error ( 'swap.data is not valid hex' ) ; } if ( ! swap . to || ! isAddress ( swap . to ) || ! swap . from || ! isAddress ( swap . from ) ) { throw new Error ( 'Invalid address in swap response' ) ; } } async function executeSwap ( tokenIn : Address , tokenOut : Address , amount : string , chainId : number ) { const ETH_ADDRESS = '0x0000000000000000000000000000000000000000' ; // 1. Check approval (for ERC20 tokens, not native ETH) if ( tokenIn !== ETH_ADDRESS ) { const approvalRes = await fetch ( ${ API_URL } /check_approval , { method : 'POST' , headers : { 'x-api-key' : API_KEY , 'Content-Type' : 'application/json' , 'x-universal-router-version' : '2.0' , } , body : JSON . stringify ( { walletAddress : account . address , token : tokenIn , amount , chainId , } ) , } ) ; const approvalData = await approvalRes . json ( ) ; if ( approvalData . approval ) { const hash = await walletClient . sendTransaction ( { to : approvalData . approval . to , data : approvalData . approval . data , value : BigInt ( approvalData . approval . value || '0' ) , } ) ; await publicClient . waitForTransactionReceipt ( { hash } ) ; } } // 2. Get quote const quoteRes = await fetch ( ${ API_URL } /quote , { method : 'POST' , headers : { 'x-api-key' : API_KEY , 'Content-Type' : 'application/json' , 'x-universal-router-version' : '2.0' , } , body : JSON . stringify ( { swapper : account . address , tokenIn , tokenOut , tokenInChainId : String ( chainId ) , tokenOutChainId : String ( chainId ) , amount , type : 'EXACT_INPUT' , slippageTolerance : 0.5 , } ) , } ) ; const quoteResponse = await quoteRes . json ( ) ; // Store FULL response if ( ! quoteRes . ok ) { throw new Error ( quoteResponse . detail || 'Quote failed' ) ; } // 3. Execute swap - CRITICAL: spread quote response, strip null fields const swapRequest = prepareSwapRequest ( quoteResponse ) ; const swapRes = await fetch ( ${ API_URL } /swap , { method : 'POST' , headers : { 'x-api-key' : API_KEY , 'Content-Type' : 'application/json' , 'x-universal-router-version' : '2.0' , } , body : JSON . stringify ( swapRequest ) , } ) ; const swapData = await swapRes . json ( ) ; if ( ! swapRes . ok ) { throw new Error ( swapData . detail || 'Swap request failed' ) ; } // 4. Validate before broadcasting validateSwap ( swapData . swap ) ; const hash = await walletClient . sendTransaction ( { to : swapData . swap . to , data : swapData . swap . data , value : BigInt ( swapData . swap . value || '0' ) , } ) ; return publicClient . waitForTransactionReceipt ( { hash } ) ; } Smart Contract Integration (Solidity) // SPDX-License-Identifier: MIT pragma solidity ^ 0.8.0 ; interface IUniversalRouter { function execute ( bytes calldata commands , bytes [ ] calldata inputs , uint256 deadline ) external payable ; } interface IERC20 { function approve ( address spender , uint256 amount ) external returns ( bool ) ; } contract SwapIntegration { IUniversalRouter public immutable router ; address public constant PERMIT2 = 0x000000000022D473030F116dDEE9F6B43aC78BA3 ; constructor ( address _router ) { router = IUniversalRouter ( _router ) ; } function swap ( bytes calldata commands , bytes [ ] calldata inputs , uint256 deadline ) external payable { router . execute { value : msg . value } ( commands , inputs , deadline ) ; } // Approve token for Permit2 (one-time setup) function approveToken ( address token ) external { IERC20 ( token ) . approve ( PERMIT2 , type ( uint256 ) . max ) ; } } Advanced Patterns Smart Account Integration (ERC-4337) Execute Trading API swaps through ERC-4337 smart accounts with delegation. The pattern: Get swap calldata from Trading API (standard 3-step flow) Wrap the calldata in a delegation redemption execution Submit via bundler as a UserOperation // After getting swap calldata from Trading API: const { to , data , value } = swapResponse . swap ; // Wrap in delegation execution const execution = { target : to , // Universal Router callData : data , value : BigInt ( value ) , } ; // Submit via bundler const userOpHash = await bundlerClient . sendUserOperation ( { account : delegateSmartAccount , calls : [ { to : delegationManagerAddress , data : encodeFunctionData ( { abi : delegationManagerAbi , functionName : 'redeemDelegations' , args : [ [ [ signedDelegation ] ] , [ 0 ] , [ [ execution ] ] ] , } ) , value : execution . value , } , ] , } ) ; Key considerations : Use legacy approvals (direct to Universal Router) instead of Permit2 for smart accounts — see Approval Target Add 20-30% gas buffer for bundler gas estimation Handle bundler-specific error codes separately from standard transaction errors See Advanced Patterns Reference for the complete implementation with types and error handling. WETH Handling on L2s On L2 chains (Base, Optimism, Arbitrum), swaps outputting ETH may deliver WETH instead of native ETH. Always check and unwrap after swaps: import { parseAbi , type Address } from 'viem' ; const WETH_ABI = parseAbi ( [ 'function balanceOf(address) view returns (uint256)' , 'function withdraw(uint256)' , ] ) ; const WETH_ADDRESSES : Record < number , Address

= { 1 : '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2' , 10 : '0x4200000000000000000000000000000000000006' , 8453 : '0x4200000000000000000000000000000000000006' , 42161 : '0x82aF49447D8a07e3bd95BD0d56f35241523fBab1' , } ; // After swap completes on an L2: const wethAddress = WETH_ADDRESSES [ chainId ] ; if ( wethAddress ) { const wethBalance = await publicClient . readContract ( { address : wethAddress , abi : WETH_ABI , functionName : 'balanceOf' , args : [ accountAddress ] , } ) ; if ( wethBalance

0n ) { const hash = await walletClient . writeContract ( { address : wethAddress , abi : WETH_ABI , functionName : 'withdraw' , args : [ wethBalance ] , } ) ; await publicClient . waitForTransactionReceipt ( { hash } ) ; } } See Advanced Patterns Reference for chain-specific WETH addresses and integration details. Rate Limiting The Trading API enforces rate limits (~10 requests/second per endpoint). For batch operations: Add 100-200ms delays between sequential API calls Implement exponential backoff with jitter on 429 responses Cache approval results — approvals rarely change between calls // Exponential backoff for 429 responses async function fetchWithRetry ( url : string , init : RequestInit , maxRetries = 5 ) : Promise < Response

{ for ( let attempt = 0 ; attempt <= maxRetries ; attempt ++ ) { const response = await fetch ( url , init ) ; if ( response . status !== 429 && response . status < 500 ) return response ; if ( attempt === maxRetries ) throw new Error ( Failed after ${ maxRetries } retries ) ; const delay = Math . min ( 200 * Math . pow ( 2 , attempt ) + Math . random ( ) * 100 , 10000 ) ; await new Promise ( ( resolve ) => setTimeout ( resolve , delay ) ) ; } throw new Error ( 'Unreachable' ) ; } See Advanced Patterns Reference for batch operation patterns and full retry implementation. Key Contract Addresses Universal Router (v4) Addresses are per-chain. The legacy v1 address 0x3fC91A3afd70395Cd496C647d5a6CC9D4B2b7FAD is deprecated. Chain ID Address Ethereum 1 0x66a9893cc07d91d95644aedd05d03f95e1dba8af Unichain 130 0xef740bf23acae26f6492b10de645d6b98dc8eaf3 Optimism 10 0x851116d9223fabed8e56c0e6b8ad0c31d98b3507 Base 8453 0x6ff5693b99212da76ad316178a184ab56d299b43 Arbitrum 42161 0xa51afafe0263b40edaef0df8781ea9aa03e381a3 Polygon 137 0x1095692a6237d83c6a72f3f5efedb9a670c49223 Blast 81457 0xeabbcb3e8e415306207ef514f660a3f820025be3 BNB 56 0x1906c1d672b88cd1b9ac7593301ca990f94eae07 Zora 7777777 0x3315ef7ca28db74abadc6c44570efdf06b04b020 World Chain 480 0x8ac7bee993bb44dab564ea4bc9ea67bf9eb5e743 Avalanche 43114 0x94b75331ae8d42c1b61065089b7d48fe14aa73b7 Celo 42220 0xcb695bc5d3aa22cad1e6df07801b061a05a0233a Soneium 1868 0x4cded7edf52c8aa5259a54ec6a3ce7c6d2a455df Ink 57073 0x112908dac86e20e7241b0927479ea3bf935d1fa0 Monad 143 0x0d97dc33264bfc1c226207428a79b26757fb9dc3 For testnet addresses, see Uniswap v4 Deployments . Permit2 Chain Address All chains 0x000000000022D473030F116dDEE9F6B43aC78BA3 Troubleshooting Common Issues Issue Solution "Insufficient allowance" Call /check_approval first and submit approval tx "Quote expired" Increase deadline or re-fetch quote "Slippage exceeded" Increase slippageTolerance or retry "Insufficient liquidity" Try smaller amount or different route "Buffer is not defined" Add Buffer polyfill (see Critical Implementation Notes) On-chain revert with empty data Validate swap.data is non-empty hex before broadcasting "permitData must be of type object" Strip permitData: null from request - omit field entirely "quote does not match any of the allowed types" Don't wrap quote in {quote: ...} — spread into request body. Also check: for UniswapX routes, permitData must be omitted from the /swap body (see API Validation Errors ) Received WETH instead of ETH on L2 Check and unwrap WETH after swap (see WETH Handling on L2s ) 429 Too Many Requests Implement exponential backoff and add delays between batch requests (see Rate Limiting ) 415 on OPTIONS preflight / CORS error Set up a CORS proxy (see CORS Proxy Configuration in Browser Environment Setup) walletClient is undefined when wallet is connected Use getWalletClient() from @wagmi/core instead of the useWalletClient() hook (see wagmi v2 Integration Pitfalls ) "Please provide a chain with the chain argument" Pass chainId to getWalletClient(config, { chainId }) Chain mismatch error on swap Call switchChain() before getWalletClient() (see wagmi v2 Integration Pitfalls ) API Validation Errors (400) Error Message Cause Fix "permitData" must be of type object Sending permitData: null Omit the field entirely when null "quote" does not match any of the allowed types Wrapping quote in {quote: quoteResponse} Spread quote response: {...quoteResponse} "quote" does not match any of the allowed types Including permitData in a UniswapX (DUTCH_V2/V3/PRIORITY) /swap body Omit permitData for UniswapX routes — see Signing vs. Submission signature and permitData must both be present Including only one Permit2 field (CLASSIC routes only) Include both or neither for CLASSIC; omit permitData for UniswapX API Error Codes Code Meaning 400 Invalid request parameters (see validation errors above) 401 Invalid or missing API key 404 No route found for pair 429 Rate limit exceeded 500 API error - implement exponential backoff retry Pre-Broadcast Checklist Before sending a swap transaction to the blockchain: Verify swap.data is non-empty hex (not '' , not '0x' ) Verify addresses - swap.to and swap.from are valid Check quote freshness - Re-fetch if older than 30 seconds Validate gas - Apply 10-20% buffer to estimates Confirm balance - User has sufficient token balance Additional Resources Universal Router GitHub Uniswap Docs SDK Monorepo Permit2 Patterns