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
}
}
- 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 | ✅ |
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
