API Integration Guide

curl -X POST https://trade-api.gateway.uniswap.org/v1/quote \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "accept: application/json" \
  -d '{"tokenIn":"0x...","tokenOut":"0x...","amount":"1000000",...}'

const response = await fetch('https://trade-api.gateway.uniswap.org/v1/quote', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    tokenIn: '0x0000000000000000000000000000000000000000', // ETH
    tokenOut: '0xdAC17F958D2ee523a2206206994597C13D831ec7', // USDT
    tokenInChainId: 1,
    tokenOutChainId: 1,
    type: 'EXACT_INPUT',
    amount: '1000000000000000000', // 1 ETH in wei
    swapper: '0x...', // User's wallet address
    slippageTolerance: 0.5 // 0.5%
  })
});

const quote = await response.json();

User Request
    |
Your Application
    |-- (Optionally) Check balances (via your RPC)
    |-- Checks wallet approval for Permit2 (Trading API)
    |-- Get user signature for Permit2 approval (Wallet)
    |-- Request quote (Trading API)
    |-- Approve Permit2 spending (Wallet)
    |-- Build transaction (Trading API)
    |-- Get user signature for swap (Wallet)
    |-- Manage nonce (your tracking)
    +-- Broadcast transaction (via your RPC)
         |
    Blockchain

interface TransactionRequest {
  to: string;           // Contract address to call
  from: string;         // User's wallet address
  data: string;         // Encoded function call (hex string)
  value: string;        // Native token amount (wei)
  chainId: number;
  gasLimit?: string;
  maxFeePerGas?: string;
  maxPriorityFeePerGas?: string;
  gasPrice?: string;    // Legacy gas price
}

interface PermitSingleData {
  domain: TypedDataDomain;
  values: PermitSingle;
  types: Record<string, TypedDataField[]>;
}

interface PermitSingle {
  details: {
    token: string;
    amount: string;
    expiration: string;
    nonce: string;
  };
  spender: string;
  sigDeadline: string;
}

const quoteResponse = await fetch('/quote', {
  method: 'POST',
  headers: {
    'x-api-key': API_KEY,
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    tokenIn: '0x...',
    tokenOut: '0x...',
    amount: '1000000',
    type: 'EXACT_INPUT',
    swapper: '0x...',
    tokenInChainId: 1,
    tokenOutChainId: 1,
    permitAmount: 'FULL',  // or 'EXACT'
    slippageTolerance: 0.5
  })
});

const {quote, permitData, routing} = await quoteResponse.json();

let signature: string | undefined;

if (permitData) {
  signature = await wallet._signTypedData(
    permitData.domain,
    permitData.types,
    permitData.values
  );
}

// CORRECT - Both fields provided
const swapRequest = {
  quote: quote,
  signature: signature,
  permitData: permitData
};

// CORRECT - No permit (both fields omitted), ONLY when no permitData is returned in the /quote response
const swapRequest = {
  quote: quote
  // signature and permitData omitted entirely
};

// WRONG - Missing permitData
const swapRequest = {
  quote: quote,
  signature: signature      // Will fail validation
};

// WRONG - Missing signature
const swapRequest = {
  quote: quote,
  permitData: permitData    // Will fail validation
};

const {swap} = await swapResponse.json();

validateTransaction(swap);

const signedTx = await wallet.signTransaction(swap);
const txReceipt = await provider.sendTransaction(signedTx);

interface ErrorResponse {
  error: string;
  message: string;
  details?: Record<string, any>;
}

async function validateBeforeBroadcast(
  tx: TransactionRequest,
  provider: Provider,
  token: string,
  amount: string
): Promise<void> {
  // 1. Validate transaction structure
  if (!tx.data || tx.data === '' || tx.data === '0x') {
    throw new Error('Invalid transaction: empty data field');
  }

  // 2. Check native balance
  const balance = await provider.getBalance(tx.from);
  if (balance.lt(tx.value)) {
    throw new Error('Insufficient native token balance');
  }

  // 3. Check ERC-20 balance (if applicable)
  if (token !== NATIVE_TOKEN_ADDRESS) {
    const tokenContract = new Contract(token, ERC20_ABI, provider);
    const tokenBalance = await tokenContract.balanceOf(tx.from);
    if (tokenBalance.lt(amount)) {
      throw new Error('Insufficient token balance');
    }
  }

  // 4. Simulate transaction (optional but recommended)
  try {
    await provider.call(tx);
  } catch (error) {
    throw new Error(`Transaction simulation failed: ${error.message}`);
  }
}

const QUOTE_EXPIRY_MS = 30000; // 30 seconds

const quoteTimestamp = Date.now();
// ... user reviews and signs ...
if (Date.now() - quoteTimestamp > QUOTE_EXPIRY_MS) {
  quote = await fetchQuote(params);  // Fetch fresh quote
}

function validateSwapTransaction(tx: TransactionRequest): void {
  if (!tx.data || tx.data === '' || tx.data === '0x') {
    throw new Error('Transaction data is empty');
  }

  if (!tx.to || !isAddress(tx.to)) {
    throw new Error('Invalid recipient address');
  }

  if (!tx.from || !isAddress(tx.from)) {
    throw new Error('Invalid sender address');
  }

  if (tx.maxFeePerGas && tx.gasPrice) {
    throw new Error('Cannot set both maxFeePerGas and gasPrice');
  }

  if (tx.value && BigNumber.from(tx.value).lt(0)) {
    throw new Error('Invalid transaction value');
  }
}

async function fetchQuoteWithRetry(
  params: QuoteRequest,
  maxRetries = 3
): Promise<QuoteResponse> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch('/quote', {
        method: 'POST',
        headers: {
          'x-api-key': API_KEY,
          'Content-Type': 'application/json',
          'Accept': 'application/json'
        },
        body: JSON.stringify(params)
      });

      if (!response.ok) {
        if (response.status === 429) {
          await sleep(Math.pow(2, attempt) * 1000);
          continue;
        }
        throw new Error(`API error: ${response.status}`);
      }

      return await response.json();
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      await sleep(Math.pow(2, attempt) * 1000);
    }
  }
  throw new Error('Max retries exceeded');
}

// Example metrics to track
interface SwapMetrics {
  quoteLatency: number;
  swapLatency: number;
  revertRate: number;
}

function logSwapAttempt(
  params: QuoteRequest,
  quoteResponse: QuoteResponse,
  txHash?: string,
  error?: Error
): void {
  const metrics = {
    timestamp: Date.now(),
    chainId: params.tokenInChainId,
    tokenIn: params.tokenIn,
    tokenOut: params.tokenOut,
    amount: params.amount,
    routing: quoteResponse.routing,
    txHash,
    success: !!txHash && !error,
    error: error?.message
  };

  analytics.track('swap_attempt', metrics);
}

const cache = new Map<string, {data: any, timestamp: number}>();

async function fetchWithCache(
  url: string,
  params: any,
  cacheDuration = 30000
): Promise<any> {
  const cacheKey = `${url}:${JSON.stringify(params)}`;
  const cached = cache.get(cacheKey);

  if (cached && Date.now() - cached.timestamp < cacheDuration) {
    return cached.data;
  }

  const data = await fetchWithRetry(url, params);
  cache.set(cacheKey, {data, timestamp: Date.now()});
  return data;
}

let signature
if (permitData) {
  signature = await signer._signTypedData(permitData.domain, permitData.types, permitData.values)
}