Skip to main content
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:
  1. Approve token on source chain (signature 1)
  2. Swap to bridge-compatible token (signature 2)
  3. Bridge to destination chain (wait, signature 3)
  4. Swap to desired token (signature 4)
  5. 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
    }
  }]
}
FieldDescription
outputAmountExpected tokens to receive (in wei)
minOutputAmountGuaranteed minimum after slippage
route.summaryHuman-readable path description
route.stepsEach hop in the route
estimatedTimeExpected completion time (seconds)

​
Supported Chains

ChainChain IDStatus
Ethereum1✅
Base8453✅
Arbitrum42161✅
Optimism10✅
Polygon137✅
BSC56✅
Avalanche43114✅
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;
}

​
Next Steps

Gasless Swaps

Remove gas friction from swaps

Supertransaction API

Full API tutorial with all options