> ## Documentation Index
> Fetch the complete documentation index at: https://docs.biconomy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Cross-Chain Swaps

> Swap tokens across different blockchains with a single signature

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:

```typescript theme={null}
{
  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:

```typescript theme={null}
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:

```json theme={null}
{
  "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    | ✅      |

<Info>
  See the [full supported chains list](/contracts-and-audits/supported-chains) for all 35+ networks.
</Info>

## Provider Control

Control which bridges and DEXs are used:

```typescript theme={null}
{
  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:

```typescript theme={null}
// 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%
```

<Warning>
  Always check `minOutputAmount` before executing. If it's below your user's acceptable minimum, show a warning or reject the trade.
</Warning>

## Error Handling

```typescript theme={null}
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

<CardGroup cols={2}>
  <Card title="Gasless Swaps" icon="gas-pump" href="/swaps-trading/gasless-swap">
    Remove gas friction from swaps
  </Card>

  <Card title="Supertransaction API" icon="book" href="/overview/supertransaction-api">
    Full API tutorial with all options
  </Card>
</CardGroup>