LP API Integration Guide

curl -X POST https://api.uniswap.org/lp/create \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"protocol":"V4","walletAddress":"0x...","chainId":1,...}'

const response = await fetch('https://api.uniswap.org/lp/create', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    walletAddress: '0x...',
    protocol: 'V3',
    chainId: 1,
    existingPool: {
      token0Address: '0x1f9840a85d5af5bf1d1762f925bdaddc4201f984',
      token1Address: '0xdAC17F958D2ee523a2206206994597C13D831ec7',
      poolReference: '0x3470447f3cecffac709d3e783a307790b0208d60'
    },
    independentToken: {
      tokenAddress: '0x1f9840a85d5af5bf1d1762f925bdaddc4201f984',
      amount: '198251669183062942'
    },
    priceBounds: {
      minPrice: '0.000000000003248988534520805528430529',
      maxPrice: '0.000000000003936665827581813550758959'
    },
    simulateTransaction: false
  })
});

const result = await response.json();

User Request (Create / Increase / Decrease / Claim)
    |
Your Application
    |-- Check & request token approvals (/lp/approve)
    |-- Get permit signature (if permitData returned) (Wallet)
    |-- Request LP transaction (/lp/create, /lp/increase, etc.)
    |-- Validate returned transaction payload
    |-- Get user signature for transaction (Wallet)
    +-- Broadcast transaction (via your RPC)
         |
    Blockchain

const approvalResponse = await fetch('https://api.uniswap.org/lp/approve', {
  method: 'POST',
  headers: {
    'x-api-key': API_KEY,
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    walletAddress: '0x...',
    protocol: 'V4',
    chainId: 1,
    lpTokens: [
      { tokenAddress: '0x...', amount: '1000000000000000000' },
      { tokenAddress: '0x...', amount: '500000000' }
    ],
    action: 'CREATE'
  })
});

const { approvals } = await approvalResponse.json();

// approvals is a list of ApprovalTransactionRequest objects.
// If empty, all approvals are already in place — proceed to the LP action.
for (const approval of approvals) {
  validateTransaction(approval);
  const signedTx = await wallet.signTransaction(approval);
  await provider.sendTransaction(signedTx);
}

let permitSignature: string | undefined;

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

// Pass the signature into the subsequent /lp/create or /lp/increase call:
const createBody = {
  ...positionParams,
  batchPermitData: permitData,
  signature: permitSignature
};

curl --location 'https://api.uniswap.org/lp/create' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'x-api-key: XXXXX' \
--data '{
    "walletAddress": "XXXX",
    "existingPool": {
        "token0Address": "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984",
        "token1Address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
        "poolReference": "0x3470447f3cecffac709d3e783a307790b0208d60"
    },
    "chainId": 1,
    "protocol": "V3",
    "independentToken": {
        "tokenAddress": "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984",
        "amount": "198251669183062942"
    },
    "priceBounds": {
        "minPrice": "0.000000000003248988534520805528430529",
        "maxPrice": "0.000000000003936665827581813550758959"
    },
    "simulateTransaction": false
}'

interface CreatePositionResponse {
  token0: TokenAmount;
  token1: TokenAmount;
  tickLower: number;
  tickUpper: number;
  minPrice: string;
  maxPrice: string;
  create: TransactionRequest;
  gasFeeEstimates?: GasFeeEstimates; // present when simulateTransaction: true
}

curl --location 'https://api.uniswap.org/lp/create_classic' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'x-api-key: XXXXX' \
--data '{
    "walletAddress": "XXXX",
    "poolParameters": {
        "token0Address": "0xc02fe7317d4eb8753a02c35fe019786854a92001",
        "token1Address": "0x0000000000000000000000000000000000000000",
        "chainId": 130
    },
    "independentToken": {
        "tokenAddress": "0xc02fe7317d4eb8753a02c35fe019786854a92001",
        "amount": "1000000000000000"
    },
    "dependentToken": {
        "tokenAddress": "0x0000000000000000000000000000000000000000",
        "amount": "1227700073369630"
    },
    "simulateTransaction": false
}'

curl --location 'https://api.uniswap.org/lp/increase' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'x-api-key: XXXXX' \
--data '{
    "walletAddress": "XXXX",
    "chainId": 130,
    "protocol": "V4",
    "token0Address": "0x0000000000000000000000000000000000000000",
    "token1Address": "0x078D782b760474a361dDA0AF3839290b0EF57AD6",
    "nftTokenId": "1833079",
    "independentToken": {
        "tokenAddress": "0x078D782b760474a361dDA0AF3839290b0EF57AD6",
        "amount": "8223"
    },
    "simulateTransaction": false
}'

curl --location 'https://api.uniswap.org/lp/decrease' \
--header 'Content-Type: application/json' \
--header 'x-api-key: XXXXX' \
--data '{
    "walletAddress": "XXXX",
    "chainId": 130,
    "protocol": "V4",
    "token0Address": "0x0000000000000000000000000000000000000000",
    "token1Address": "0x078D782b760474a361dDA0AF3839290b0EF57AD6",
    "nftTokenId": "1833079",
    "liquidityPercentageToDecrease": 25,
    "simulateTransaction": false
}'

curl --location 'https://api.uniswap.org/lp/claim' \
--header 'Content-Type: application/json' \
--header 'x-api-key: XXXXX' \
--data '{
    "protocol": "V4",
    "walletAddress": "XXXX",
    "chainId": 130,
    "tokenId": "1833079",
    "simulateTransaction": false
}'

interface ClaimFeesResponse {
  token0: TokenAmount;
  token1: TokenAmount;
  claim: TransactionRequest;
  gasFeeEstimates?: GasFeeEstimates; // present when simulateTransaction: true
}

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

interface TokenAmount {
  tokenAddress: string;
  amount: string; // in wei / smallest token unit
}

interface ApprovalTransactionRequest extends TransactionRequest {
  token: string;      // Token address being approved
  spender: string;    // Spender contract address
}

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

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 (recommended)
  try {
    await provider.call(tx);
  } catch (error) {
    throw new Error(`Transaction simulation failed: ${error.message}`);
  }
}

async function approveAndExecute(
  approvalParams: ApprovalRequest,
  lpAction: () => Promise<TransactionRequest>
): Promise<string> {
  const { approvals, permitData } = await fetchApprovals(approvalParams);

  // Execute any onchain approval transactions
  for (const approval of approvals) {
    const signedApproval = await wallet.signTransaction(approval);
    await provider.sendTransaction(signedApproval);
  }

  // Sign permit offchain if returned
  let permitSignature: string | undefined;
  if (permitData) {
    permitSignature = await wallet._signTypedData(
      permitData.domain, permitData.types, permitData.values
    );
  }

  const lpTx = await lpAction(); // e.g. /lp/create with permitSignature included
  validateTransaction(lpTx);
  const signedTx = await wallet.signTransaction(lpTx);
  return provider.sendTransaction(signedTx);
}

const { minPrice, maxPrice, tickLower, tickUpper } = createResponse;
// Show minPrice / maxPrice to the user, not the original priceBounds input

const TX_EXPIRY_MS = 30_000; // 30 seconds

const txTimestamp = Date.now();
// ... user reviews amounts ...
if (Date.now() - txTimestamp > TX_EXPIRY_MS) {
  lpTx = await refetchLpTransaction(params); // Fetch a fresh transaction
}

function validateLpTransaction(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');
  }
}

async function fetchLpTxWithRetry(
  endpoint: string,
  params: object,
  maxRetries = 3
): Promise<any> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(`https://api.uniswap.org${endpoint}`, {
        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');
}

function logLpAttempt(
  endpoint: string,
  params: object,
  response: object,
  txHash?: string,
  error?: Error
): void {
  analytics.track('lp_attempt', {
    timestamp: Date.now(),
    endpoint,
    protocol: (params as any).protocol,
    chainId: (params as any).chainId,
    txHash,
    success: !!txHash && !error,
    error: error?.message
  });
}

const typesWithDomain = {
  EIP712Domain: [
    { name: 'name', type: 'string' },
    { name: 'version', type: 'string' },
    { name: 'chainId', type: 'uint256' },
    { name: 'verifyingContract', type: 'address' }
  ],
  ...permitData.types
};

signature = await wallet._signTypedData(
  permitData.domain,
  typesWithDomain,
  permitData.values
);

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

async function fetchWithCache(
  endpoint: string,
  params: object,
  cacheDuration = 15_000
): Promise<any> {
  const key = `${endpoint}:${JSON.stringify(params)}`;
  const cached = cache.get(key);
  if (cached && Date.now() - cached.timestamp < cacheDuration) {
    return cached.data;
  }
  const data = await fetchLpTxWithRetry(endpoint, params);
  cache.set(key, { data, timestamp: Date.now() });
  return data;
}