Swap Integration

Swap Integration

Integrate PancakeSwap swaps into frontends, backends, and smart contracts.

Quick Decision Guide

Protocol Types

Supported Chains

For testing: Use BSC Testnet (chain ID 97). Get free testnet BNB from <https://testnet.bnbchain.org/faucet-smart>.

The Smart Router SDK does not index testnet pools — use Method 3 (Direct V2 Router) on testnet.

Key Token Addresses

BSC Mainnet (Chain ID: 56)

BSC Testnet (Chain ID: 97)

Universal Router Addresses

---

Method 1: PancakeSwap Routing API (Simplest)

Best for: Quick quotes, prototypes, and situations where you don't want to manage on-chain pool data yourself. No SDK installation required.

Base URL: https://router.pancakeswap.finance/v0/quote

Get a Quote

# Exact input: 1 BNB → CAKE on BSC
curl -s "https://router.pancakeswap.finance/v0/quote?\
tokenInAddress=BNB\
&tokenInChainId=56\
&tokenOutAddress=0x0E09FaBB73Bd3Ade0a17ECC321fD13a19e81cE82\
&tokenOutChainId=56\
&amount=1000000000000000000\
&type=exactIn\
&maxHops=3\
&maxSplits=4" | jq '{
  amountOut: .trade.outputAmount,
  priceImpact: .trade.priceImpact,
  route: [.trade.routes[].type]
}'

API Parameters

Infinity (v4) support: The Routing API automatically considers Infinity CL and Infinity Bin pools on BSC and Base alongside V2/V3/StableSwap. No extra parameters are needed — the router selects the best route across all pool types.

TypeScript Fetch Example

interface PancakeRouteQuote {
  trade: {
    inputAmount: string
    outputAmount: string
    priceImpact: string
    routes: Array<{ type: 'V2' | 'V3' | 'STABLE' | 'MIXED'; pools: unknown[] }>
    blockNumber: number
  }
}

async function getQuote(params: {
  tokenIn: string
  tokenOut: string
  chainId: number
  amount: bigint
  type: 'exactIn' | 'exactOut'
}): Promise<PancakeRouteQuote> {
  const url = new URL('https://router.pancakeswap.finance/v0/quote')
  url.searchParams.set('tokenInAddress', params.tokenIn)
  url.searchParams.set('tokenInChainId', String(params.chainId))
  url.searchParams.set('tokenOutAddress', params.tokenOut)
  url.searchParams.set('tokenOutChainId', String(params.chainId))
  url.searchParams.set('amount', String(params.amount))
  url.searchParams.set('type', params.type)
  url.searchParams.set('maxHops', '3')
  url.searchParams.set('maxSplits', '4')

  const res = await fetch(url.toString())
  if (!res.ok) throw new Error(`Routing API error: ${res.status} ${await res.text()}`)
  return res.json()
}

// Usage
const quote = await getQuote({
  tokenIn: 'BNB',
  tokenOut: '0x0E09FaBB73Bd3Ade0a17ECC321fD13a19e81cE82', // CAKE
  chainId: 56,
  amount: BigInt('1000000000000000000'), // 1 BNB
  type: 'exactIn',
})

console.log('Output:', quote.trade.outputAmount, 'CAKE (raw)')
console.log('Price impact:', quote.trade.priceImpact, '%')

Quote freshness: Re-fetch if the quote is more than ~15 seconds old before broadcasting. Stale quotes frequently fail with INSUFFICIENT_OUTPUT_AMOUNT.

---

Method 2: Smart Router SDK + Universal Router SDK

Best for: Frontends and backends that need full programmatic control over routing and transaction encoding. Operates entirely on-chain — no external API dependency.

Installation

npm install @pancakeswap/smart-router @pancakeswap/sdk @pancakeswap/v3-sdk @pancakeswap/universal-router-sdk viem@2.37.13

Package Roles

Step 1: Set Up Viem Clients

import { createPublicClient, createWalletClient, http } from 'viem'
import { bsc } from 'viem/chains'
import { privateKeyToAccount } from 'viem/accounts'

const publicClient = createPublicClient({
  chain: bsc,
  transport: http('https://bsc-dataseed1.binance.org'),
})

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`)
const walletClient = createWalletClient({
  account,
  chain: bsc,
  transport: http('https://bsc-dataseed1.binance.org'),
})

Step 2: Define Tokens

import { ChainId, Token } from '@pancakeswap/sdk'
import { Native } from '@pancakeswap/swap-sdk-evm'

const chainId = ChainId.BSC // 56

// Native BNB (no address)
const BNB = Native.onChain(chainId)

// ERC-20 tokens
const CAKE = new Token(
  chainId,
  '0x0E09FaBB73Bd3Ade0a17ECC321fD13a19e81cE82',
  18,
  'CAKE',
  'PancakeSwap Token',
)

const USDT = new Token(
  chainId,
  '0x55d398326f99059fF775485246999027B3197955',
  18,
  'USDT',
  'Tether USD',
)

Step 3: Fetch Candidate Pools

import { SmartRouter, PoolType } from '@pancakeswap/smart-router'
import { TradeType } from '@pancakeswap/sdk'
import { CurrencyAmount } from '@pancakeswap/swap-sdk-core'

const amountIn = CurrencyAmount.fromRawAmount(
  BNB,
  BigInt('1000000000000000000'), // 1 BNB
)

// Fetch all relevant pool types in parallel
const [v2Pools, v3Pools, stablePools] = await Promise.all([
  SmartRouter.getV2CandidatePools({
    onChainProvider: () => publicClient,
    currencyA: BNB,
    currencyB: CAKE,
  }),
  SmartRouter.getV3CandidatePools({
    onChainProvider: () => publicClient,
    subgraphProvider: undefined, // optional — speeds up pool discovery
    currencyA: BNB,
    currencyB: CAKE,
  }),
  SmartRouter.getStableCandidatePools({
    onChainProvider: () => publicClient,
    currencyA: BNB,
    currencyB: CAKE,
  }),
])

const pools = [...v2Pools, ...v3Pools, ...stablePools]

Performance tip: If you're building a UI, consider caching pools for 30–60 seconds and only re-fetching when the user changes tokens or chain.

Infinity (v4) pool access: The Smart Router SDK's Infinity pool integration is still evolving. For reliable Infinity CL and Infinity Bin pool access today, use Method 1 (Routing API) — it automatically considers all pool types including Infinity on BSC and Base with no extra setup required.

Step 4: Find Best Trade

const trade = await SmartRouter.getBestTrade(amountIn, CAKE, TradeType.EXACT_INPUT, {
  gasPriceWei: () => publicClient.getGasPrice(),
  maxHops: 3,
  maxSplits: 4,
  poolProvider: SmartRouter.createStaticPoolProvider(pools),
  quoteProvider: SmartRouter.createQuoteProvider({
    onChainProvider: () => publicClient,
  }),
  allowedPoolTypes: [PoolType.V2, PoolType.V3, PoolType.STABLE],
})

// Always check price impact before proceeding
if (parseFloat(trade.priceImpact.toSignificant(4)) > 2) {
  console.warn(`⚠️  High price impact: ${trade.priceImpact.toSignificant(4)}%`)
}

console.log('Output:', trade.outputAmount.toSignificant(6), CAKE.symbol)
console.log('Route:', trade.routes.map((r) => r.type).join(' + '))

Step 5: Approve Tokens

Skip this step if the input currency is native BNB/ETH — native currency does not need approval.

import { erc20Abi } from 'viem'
import {
  PancakeSwapUniversalRouter,
  getUniversalRouterAddress,
} from '@pancakeswap/universal-router-sdk'

const PERMIT2_ADDRESS = '0x000000000022D473030F116dDEE9F6B43aC78BA3' as const

async function ensureTokenApproved(
  tokenAddress: `0x${string}`,
  owner: `0x${string}`,
  chainId: number,
) {
  // Step 1: Approve Permit2 contract (one-time per token, per wallet)
  const permit2Allowance = await publicClient.readContract({
    address: tokenAddress,
    abi: erc20Abi,
    functionName: 'allowance',
    args: [owner, PERMIT2_ADDRESS],
  })

  const MAX_UINT256 = BigInt('0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff')
  if (permit2Allowance < MAX_UINT256 / 2n) {
    const hash = await walletClient.writeContract({
      address: tokenAddress,
      abi: erc20Abi,
      functionName: 'approve',
      args: [PERMIT2_ADDRESS, MAX_UINT256],
    })
    await publicClient.waitForTransactionReceipt({ hash })
    console.log('✅ Permit2 approved')
  }

  // Step 2: Approve the Universal Router via Permit2 (per-swap, via signature OR transaction)
  // The Universal Router SDK handles this via inputTokenPermit in options.
  // For simplicity, approve the Universal Router directly instead:
  const routerAddress = getUniversalRouterAddress(chainId) as `0x${string}`
  const routerAllowance = await publicClient.readContract({
    address: tokenAddress,
    abi: erc20Abi,
    functionName: 'allowance',
    args: [owner, routerAddress],
  })

  if (routerAllowance < MAX_UINT256 / 2n) {
    const hash = await walletClient.writeContract({
      address: tokenAddress,
      abi: erc20Abi,
      functionName: 'approve',
      args: [routerAddress, MAX_UINT256],
    })
    await publicClient.waitForTransactionReceipt({ hash })
    console.log('✅ Universal Router approved')
  }
}

Step 6: Encode and Send the Transaction

import {
  PancakeSwapUniversalRouter,
  getUniversalRouterAddress,
} from '@pancakeswap/universal-router-sdk'
import { Percent } from '@pancakeswap/sdk'

const slippage = new Percent(50, 10000) // 0.5%
const deadline = BigInt(Math.floor(Date.now() / 1000) + 60 * 20) // 20 min

// Encode the swap calldata
const { calldata, value } = PancakeSwapUniversalRouter.swapERC20CallParameters(trade, {
  slippageTolerance: slippage,
  recipient: account.address,
  deadlineOrPreviousBlockhash: deadline,
})

// Send the transaction
const hash = await walletClient.sendTransaction({
  to: getUniversalRouterAddress(chainId) as `0x${string}`,
  data: calldata as `0x${string}`,
  value: BigInt(value), // Non-zero only when input is native BNB/ETH
  gas: 400000n, // Overestimate — unspent gas is refunded
})

const receipt = await publicClient.waitForTransactionReceipt({ hash })
if (receipt.status === 'reverted') {
  throw new Error(`Swap reverted: ${receipt.transactionHash}`)
}
console.log('✅ Swap confirmed:', receipt.transactionHash)

Exact Output Swaps

To swap for a precise output amount (e.g., "I want exactly 100 USDT"):

const amountOut = CurrencyAmount.fromRawAmount(
  USDT,
  BigInt('100000000000000000000'), // 100 USDT (18 decimals)
)

const trade = await SmartRouter.getBestTrade(
  amountOut,
  BNB, // currencyIn — note: swapped argument order for EXACT_OUTPUT
  TradeType.EXACT_OUTPUT,
  {
    gasPriceWei: () => publicClient.getGasPrice(),
    maxHops: 3,
    maxSplits: 4,
    poolProvider: SmartRouter.createStaticPoolProvider(pools),
    quoteProvider: SmartRouter.createQuoteProvider({ onChainProvider: () => publicClient }),
  },
)

console.log('Max BNB to spend:', trade.inputAmount.toSignificant(6))

// Encode with maximumAmountIn applied automatically via slippageTolerance
const { calldata, value } = PancakeSwapUniversalRouter.swapERC20CallParameters(trade, {
  slippageTolerance: new Percent(50, 10000),
  recipient: account.address,
  deadlineOrPreviousBlockhash: deadline,
})

---

Method 3: Direct V2 Router Contract

Best for: Simple BSC swaps, Solidity integrations, or when you want zero SDK dependencies. Only supports V2 pools — no V3 or StableSwap.

V2 Router Address (BSC Mainnet)

0x10ED43C718714eb63d5aA57B78B54704E256024E

V2 Router ABI (subset)

const PANCAKE_V2_ROUTER_ABI = [
  {
    name: 'swapExactETHForTokens',
    type: 'function',
    stateMutability: 'payable',
    inputs: [
      { name: 'amountOutMin', type: 'uint256' },
      { name: 'path', type: 'address[]' },
      { name: 'to', type: 'address' },
      { name: 'deadline', type: 'uint256' },
    ],
    outputs: [{ name: 'amounts', type: 'uint256[]' }],
  },
  {
    name: 'swapExactTokensForETH',
    type: 'function',
    stateMutability: 'nonpayable',
    inputs: [
      { name: 'amountIn', type: 'uint256' },
      { name: 'amountOutMin', type: 'uint256' },
      { name: 'path', type: 'address[]' },
      { name: 'to', type: 'address' },
      { name: 'deadline', type: 'uint256' },
    ],
    outputs: [{ name: 'amounts', type: 'uint256[]' }],
  },
  {
    name: 'swapExactTokensForTokens',
    type: 'function',
    stateMutability: 'nonpayable',
    inputs: [
      { name: 'amountIn', type: 'uint256' },
      { name: 'amountOutMin', type: 'uint256' },
      { name: 'path', type: 'address[]' },
      { name: 'to', type: 'address' },
      { name: 'deadline', type: 'uint256' },
    ],
    outputs: [{ name: 'amounts', type: 'uint256[]' }],
  },
  // Fee-on-transfer variant (SafeMoon-style tokens)
  {
    name: 'swapExactTokensForTokensSupportingFeeOnTransferTokens',
    type: 'function',
    stateMutability: 'nonpayable',
    inputs: [
      { name: 'amountIn', type: 'uint256' },
      { name: 'amountOutMin', type: 'uint256' },
      { name: 'path', type: 'address[]' },
      { name: 'to', type: 'address' },
      { name: 'deadline', type: 'uint256' },
    ],
    outputs: [],
  },
  {
    name: 'getAmountsOut',
    type: 'function',
    stateMutability: 'view',
    inputs: [
      { name: 'amountIn', type: 'uint256' },
      { name: 'path', type: 'address[]' },
    ],
    outputs: [{ name: 'amounts', type: 'uint256[]' }],
  },
] as const

const V2_ROUTER = '0x10ED43C718714eb63d5aA57B78B54704E256024E' as const
const WBNB = '0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c' as const
const CAKE = '0x0E09FaBB73Bd3Ade0a17ECC321fD13a19e81cE82' as const

V2 Swap Example (BNB → CAKE)

import { parseEther } from 'viem'

const slippageBps = 50n // 0.5%
const deadline = BigInt(Math.floor(Date.now() / 1000) + 60 * 20)

// 1. Get quote
const amounts = await publicClient.readContract({
  address: V2_ROUTER,
  abi: PANCAKE_V2_ROUTER_ABI,
  functionName: 'getAmountsOut',
  args: [parseEther('0.1'), [WBNB, CAKE]],
})
const expectedOut = amounts[1]
const minOut = (expectedOut * (10000n - slippageBps)) / 10000n

// 2. Approve router for the input token (skip for BNB input)

// 3. Execute
const hash = await walletClient.writeContract({
  address: V2_ROUTER,
  abi: PANCAKE_V2_ROUTER_ABI,
  functionName: 'swapExactETHForTokens',
  args: [minOut, [WBNB, CAKE], account.address, deadline],
  value: parseEther('0.1'),
})

Multi-hop V2 (BNB → USDT → CAKE)

// Simply extend the path array
const amounts = await publicClient.readContract({
  address: V2_ROUTER,
  abi: PANCAKE_V2_ROUTER_ABI,
  functionName: 'getAmountsOut',
  args: [parseEther('0.1'), [WBNB, USDT_BSC, CAKE]],
})

---

Token Approval Reference

---

V3 Fee Tiers

import { FeeAmount } from '@pancakeswap/v3-sdk'

FeeAmount.LOWEST // 100   bps = 0.01%  — stablecoin pairs (USDT/USDC)
FeeAmount.LOW // 500   bps = 0.05%  — stable-ish pairs
FeeAmount.MEDIUM // 2500  bps = 0.25%  — most standard pairs (default)
FeeAmount.HIGH // 10000 bps = 1%     — exotic or highly volatile pairs

---

Critical Implementation Notes

TypeScript Import Conventions

Use import type (or inline type modifier) for any import that is only used as a TypeScript type — never at runtime. This keeps bundles clean and avoids circular-dependency issues.

// ✅ Correct — Currency is only used in a type annotation
import { type Currency, TradeType, Percent } from '@pancakeswap/sdk'
import type { SmartRouterTrade } from '@pancakeswap/smart-router'

// ❌ Wrong — Currency is only a type, don't import it as a value
import { Currency, TradeType, Percent } from '@pancakeswap/sdk'

Slippage Guidelines

Never set 0% slippage in production. Every block's price movement will cause the transaction to revert.

Native BNB/ETH Handling

• Pass Native.onChain(chainId) as the currency — the Smart Router and Universal Router handle WRAP_ETH / UNWRAP_WETH commands automatically.
• For direct V2 calls: use swapExactETHForTokens with value: amountIn.
• value in the encoded calldata will be non-zero only when the input is native. Always pass it when sending the transaction.

Fee-on-Transfer Tokens (Reflection Tokens)

• These tokens deduct a fee on every transfer, so the router receives less than amountIn.
• On V2: use swapExactTokensForTokensSupportingFeeOnTransferTokens or swapExactETHForTokensSupportingFeeOnTransferTokens.
• The Smart Router detects these automatically and routes accordingly.
• Always set slippage ≥ the token's transfer fee (e.g., 5% token fee → use ≥5% slippage).

Quote Staleness

• Re-fetch the trade quote if it is more than 15–30 seconds old before sending.
• Stale quotes frequently revert with INSUFFICIENT_OUTPUT_AMOUNT.

Gas Estimates

Always use publicClient.estimateGas() in production; hard-coded values can under-estimate on complex routes.

---

Error Handling

Common Revert Reasons

Debugging a Revert

// Simulate the transaction to get the revert reason
try {
  await publicClient.call({
    to: getUniversalRouterAddress(chainId) as `0x${string}`,
    data: calldata as `0x${string}`,
    value: BigInt(value),
    account: account.address,
  })
} catch (err: unknown) {
  // viem throws with the decoded revert reason
  console.error('Revert reason:', (err as Error).message)
}

---

Frontend Integration (React + wagmi)

For React frontends, use wagmi hooks alongside the Smart Router SDK:

npm install wagmi@2.17.5 viem@2.37.13 @tanstack/react-query

import { useWalletClient, usePublicClient, useChainId } from 'wagmi'
import { useMutation } from '@tanstack/react-query'
import { type Currency, TradeType, Percent } from '@pancakeswap/sdk'
import { CurrencyAmount } from '@pancakeswap/swap-sdk-core'
import { SmartRouter } from '@pancakeswap/smart-router'
import {
  PancakeSwapUniversalRouter,
  getUniversalRouterAddress,
} from '@pancakeswap/universal-router-sdk'

type SwapVariables = { amountIn: bigint; tokenIn: Currency; tokenOut: Currency }

function useSwap() {
  const chainId = useChainId()
  const { data: walletClient } = useWalletClient()
  const publicClient = usePublicClient()

  return useMutation<`0x${string}`, Error, SwapVariables>({
    mutationFn: async ({ amountIn, tokenIn, tokenOut }) => {
      if (!walletClient || !publicClient) throw new Error('Wallet not connected')

      // 1. Fetch pools
      const pools = await fetchPancakePools(publicClient, tokenIn, tokenOut, chainId)

      // 2. Get best trade
      const trade = await SmartRouter.getBestTrade(
        CurrencyAmount.fromRawAmount(tokenIn, amountIn),
        tokenOut,
        TradeType.EXACT_INPUT,
        {
          gasPriceWei: () => publicClient.getGasPrice(),
          maxHops: 3,
          maxSplits: 4,
          poolProvider: SmartRouter.createStaticPoolProvider(pools),
          quoteProvider: SmartRouter.createQuoteProvider({ onChainProvider: () => publicClient }),
        },
      )
      if (!trade) throw new Error('No route found for this token pair')

      // 3. Encode
      const { calldata, value } = PancakeSwapUniversalRouter.swapERC20CallParameters(trade, {
        slippageTolerance: new Percent(50, 10000),
        recipient: walletClient.account.address,
        deadlineOrPreviousBlockhash: BigInt(Math.floor(Date.now() / 1000) + 1200),
      })

      // 4. Send
      return walletClient.sendTransaction({
        to: getUniversalRouterAddress(chainId) as `0x${string}`,
        data: calldata as `0x${string}`,
        value: BigInt(value),
      })
    },
  })
}

---

Complete Working Example: BNB → CAKE

import { createPublicClient, createWalletClient, http } from 'viem'
import { bsc } from 'viem/chains'
import { privateKeyToAccount } from 'viem/accounts'
import { ChainId, Token, TradeType, Percent } from '@pancakeswap/sdk'
import { Native } from '@pancakeswap/swap-sdk-evm'
import { CurrencyAmount } from '@pancakeswap/swap-sdk-core'
import { SmartRouter, PoolType } from '@pancakeswap/smart-router'
import {
  PancakeSwapUniversalRouter,
  getUniversalRouterAddress,
} from '@pancakeswap/universal-router-sdk'

const chainId = ChainId.BSC
const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`)

const publicClient = createPublicClient({
  chain: bsc,
  transport: http('https://bsc-dataseed1.binance.org'),
})
const walletClient = createWalletClient({
  account,
  chain: bsc,
  transport: http('https://bsc-dataseed1.binance.org'),
})

const BNB = Native.onChain(chainId)
const CAKE = new Token(chainId, '0x0E09FaBB73Bd3Ade0a17ECC321fD13a19e81cE82', 18, 'CAKE')

async function swapBNBforCAKE(bnbAmountWei: bigint) {
  const amountIn = CurrencyAmount.fromRawAmount(BNB, bnbAmountWei)

  // 1. Fetch candidate pools (V2 + V3; stable not relevant for BNB/CAKE)
  const [v2Pools, v3Pools] = await Promise.all([
    SmartRouter.getV2CandidatePools({
      onChainProvider: () => publicClient,
      currencyA: BNB,
      currencyB: CAKE,
    }),
    SmartRouter.getV3CandidatePools({
      onChainProvider: () => publicClient,
      subgraphProvider: undefined,
      currencyA: BNB,
      currencyB: CAKE,
    }),
  ])

  // 2. Find best route
  const trade = await SmartRouter.getBestTrade(amountIn, CAKE, TradeType.EXACT_INPUT, {
    gasPriceWei: () => publicClient.getGasPrice(),
    maxHops: 3,
    maxSplits: 4,
    poolProvider: SmartRouter.createStaticPoolProvider([...v2Pools, ...v3Pools]),
    quoteProvider: SmartRouter.createQuoteProvider({ onChainProvider: () => publicClient }),
    allowedPoolTypes: [PoolType.V2, PoolType.V3],
  })

  const impact = parseFloat(trade.priceImpact.toSignificant(4))
  if (impact > 2) console.warn(`⚠️  High price impact: ${impact}%`)

  console.log(
    `Swapping ${amountIn.toSignificant(4)} BNB → ~${trade.outputAmount.toSignificant(4)} CAKE`,
  )

  // 3. Encode calldata
  const { calldata, value } = PancakeSwapUniversalRouter.swapERC20CallParameters(trade, {
    slippageTolerance: new Percent(50, 10000), // 0.5%
    recipient: account.address,
    deadlineOrPreviousBlockhash: BigInt(Math.floor(Date.now() / 1000) + 1200),
  })

  // 4. Send (no token approval needed — input is native BNB)
  const hash = await walletClient.sendTransaction({
    to: getUniversalRouterAddress(chainId) as `0x${string}`,
    data: calldata as `0x${string}`,
    value: BigInt(value),
    gas: 400000n,
  })

  const receipt = await publicClient.waitForTransactionReceipt({ hash })
  if (receipt.status === 'reverted') throw new Error(`Swap reverted: ${hash}`)

  console.log('✅ Confirmed:', receipt.transactionHash)
  return receipt
}

await swapBNBforCAKE(BigInt('100000000000000000')) // 0.1 BNB