Cross-Chain Swaps

Move tokens between any supported chains in one transaction. Biconomy automatically finds the best route through bridges and DEXs—your users just sign once.

The Problem It Solves

Without Biconomy, a cross-chain swap requires:

Approve token on source chain (signature 1)
Swap to bridge-compatible token (signature 2)
Bridge to destination chain (wait, signature 3)
Swap to desired token (signature 4)
Hope nothing fails in between

With Biconomy: One signature. Biconomy orchestrates everything.

How It Works

The /instructions/intent-simple endpoint handles cross-chain swaps automatically:

{
  type: '/instructions/intent-simple',
  data: {
    srcChainId: 8453,        // Source: Base
    dstChainId: 42161,       // Destination: Arbitrum
    srcToken: USDC_BASE,     // What user has
    dstToken: ETH_ARBITRUM,  // What user wants
    amount: '100000000',     // 100 USDC
    slippage: 0.01           // 1% slippage tolerance
  }
}

Biconomy figures out the optimal path:

Same-chain? Routes through DEXs (Uniswap, Curve, etc.)
Cross-chain? Combines bridges (Across, LiFi) with DEX swaps
Complex routes? Handles multi-hop paths automatically

Complete Example

Swap 500 USDC on Base → ETH on Arbitrum:

import { parseUnits, formatUnits } from 'viem';

const USDC_BASE = '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913';
const ETH_ARBITRUM = '0x0000000000000000000000000000000000000000'; // Native ETH

// Step 1: Get quote
const quote = await fetch('https://api.biconomy.io/v1/quote', {
  method: 'POST',
  headers: { 
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    mode: 'smart-account',
    ownerAddress: userAddress,
    feeToken: {
      address: USDC_BASE,
      chainId: 8453
    },
    composeFlows: [{
      type: '/instructions/intent-simple',
      data: {
        srcChainId: 8453,
        dstChainId: 42161,
        srcToken: USDC_BASE,
        dstToken: ETH_ARBITRUM,
        amount: parseUnits('500', 6).toString(),
        slippage: 0.01
      }
    }]
  })
}).then(r => r.json());

// Step 2: Review the route
const swap = quote.returnedData[0];
console.log('Route:', swap.route.summary);
console.log('Expected ETH:', formatUnits(swap.outputAmount, 18));
console.log('Min ETH:', formatUnits(swap.minOutputAmount, 18));
console.log('Est. time:', swap.route.estimatedTime, 'seconds');
console.log('Fee:', formatUnits(quote.fee.amount, 6), 'USDC');

// Step 3: Sign and execute
const signature = await signPayload(quote);

const result = await fetch('https://api.biconomy.io/v1/execute', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    ...quote,
    payloadToSign: [{ ...quote.payloadToSign[0], signature }]
  })
}).then(r => r.json());

console.log('Supertransaction:', result.supertxHash);

Understanding Route Data

The API returns detailed routing information:

{
  "returnedData": [{
    "outputAmount": "250000000000000000",
    "minOutputAmount": "247500000000000000",
    "route": {
      "summary": "lifi[uniswap] => across[SpokePoolV3]",
      "type": "DIRECT",
      "steps": [
        {
          "type": "swap",
          "protocol": "lifi",
          "sources": ["uniswap"],
          "srcChainId": 8453,
          "dstChainId": 8453
        },
        {
          "type": "bridge",
          "protocol": "across",
          "srcChainId": 8453,
          "dstChainId": 42161
        }
      ],
      "totalGasFeesUsd": 0.05,
      "totalBridgeFeesUsd": 0.12,
      "estimatedTime": 120
    }
  }]
}

Field	Description
`outputAmount`	Expected tokens to receive (in wei)
`minOutputAmount`	Guaranteed minimum after slippage
`route.summary`	Human-readable path description
`route.steps`	Each hop in the route
`estimatedTime`	Expected completion time (seconds)

Supported Chains

Chain	Chain ID	Status
Ethereum	1	✅
Base	8453	✅
Arbitrum	42161	✅
Optimism	10	✅
Polygon	137	✅
BSC	56	✅
Avalanche	43114	✅

See the full supported chains list for all 35+ networks.

Provider Control

Control which bridges and DEXs are used:

{
  type: '/instructions/intent-simple',
  data: {
    srcChainId: 8453,
    dstChainId: 42161,
    srcToken: USDC,
    dstToken: ETH,
    amount: '100000000',
    slippage: 0.01,
    
    // Only use specific providers
    allowBridgeProviders: 'across',
    allowSwapProviders: 'lifi,uniswap',
    
    // Or exclude specific providers
    denyBridgeProviders: 'some-bridge',
    denySwapProviders: 'gluex'
  }
}

Handling Slippage

Cross-chain swaps have more price uncertainty. Set slippage appropriately:

// Stablecoin to stablecoin (low volatility)
slippage: 0.005  // 0.5%

// Stable to volatile token
slippage: 0.01   // 1%

// Volatile to volatile, long bridge time
slippage: 0.03   // 3%

Always check minOutputAmount before executing. If it’s below your user’s acceptable minimum, show a warning or reject the trade.

Error Handling

const quote = await fetch('https://api.biconomy.io/v1/quote', {...})
  .then(r => r.json());

// Check for routing errors
if (quote.error) {
  if (quote.error.includes('No route found')) {
    // Token pair not supported or liquidity too low
    console.log('Try different tokens or reduce amount');
  }
  return;
}

// Validate output is acceptable
const minOutput = BigInt(quote.returnedData[0].minOutputAmount);
const userMinimum = parseUnits('0.24', 18); // User's minimum acceptable

if (minOutput < userMinimum) {
  console.log('Output too low after slippage');
  return;
}

Getting Started

Tutorials

The Problem It Solves

How It Works

Complete Example

Understanding Route Data

Supported Chains

Provider Control

Handling Slippage

Error Handling

Next Steps

Gasless Swaps

Supertransaction API

​The Problem It Solves

​How It Works

​Complete Example

​Understanding Route Data

​Supported Chains

​Provider Control

​Handling Slippage

​Error Handling

​Next Steps

Gasless Swaps

Supertransaction API

The Problem It Solves

How It Works

Complete Example

Understanding Route Data

Supported Chains

Provider Control

Handling Slippage

Error Handling

Next Steps