Skip to main content
This guide walks through a simple cross-chain swap workflow: Swap 10 USDC from Arbitrum → USDT on Optimism This workflow demonstrates how to execute a cross-chain token swap with a single user signature, even though it involves operations across multiple blockchains.

​
Choose Your Execution Mode

Select the mode that matches your application architecture:
  • EOA
  • EIP-7702
  • Smart Account
When to Use: External wallets (MetaMask, WalletConnect)Key Benefit: One-click flow without smart account depositsPerfect for applications where users already have their assets in external wallets and want a simple transaction flow.

​
Integration Flexibility

The Supertransaction API only requires payload signing, making it compatible with:
  • Frontend applications - Direct wallet integration
  • Backend services - Programmatic execution
  • Mobile apps - Native or React Native
  • Any platform that can make API calls and sign messages

​
Complete Flow: Cross-Chain Swap

​
Step 1: Create Quote with ComposeFlows

Use the /v1/quote endpoint with embedded composeFlows to create the swap:
  • EOA Mode
  • EIP-7702 Mode
  • Smart Account Mode
import { parseUnits } from 'viem';

const USDC_ARB = '0xaf88d065e77c8cC2239327C5EDb3A432268e5831';
const USDT_OP = '0x94b008aA00579c1307B0EF2c499aD98a8ce58e58';

const quoteResponse = 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: "eoa",
    ownerAddress: userAddress,
    fundingTokens: [{
      tokenAddress: USDC_ARB,
      chainId: 42161, // Arbitrum
      amount: parseUnits('10', 6).toString()
    }],
    feeToken: {
      address: USDC_ARB,
      chainId: 42161
    },
    composeFlows: [
      // Cross-chain swap
      {
        type: '/instructions/intent-simple',
        data: {
          srcChainId: 42161, // Arbitrum
          dstChainId: 10, // Optimism
          srcToken: USDC_ARB,
          dstToken: USDT_OP,
          amount: parseUnits('10', 6).toString(),
          slippage: 0.01 // 1%
        }
      },
      // Withdraw to EOA
      {
        type: '/instructions/build',
        data: {
          functionSignature: 'function transfer(address to, uint256 value)',
          args: [
            userAddress,
            {
              type: 'runtimeErc20Balance',
              tokenAddress: USDT_OP,
              constraints: { gte: '1' }
            }
          ],
          to: USDT_OP,
          chainId: 10
        }
      }
    ]
  })
});

const quote = await quoteResponse.json();
console.log('Quote type:', quote.quoteType); // 'permit' for USDC
console.log('Expected output:', quote.returnedData[0].outputAmount);

​
Step 2: Sign Payloads

Sign the required payloads based on your quote type: 
# Signing happens client-side - cannot be done via cURL
# You'll need to sign the payloads using your wallet
# and include signatures in the execute request

​
Step 3: Execute Transaction

Submit the signed quote for execution: 
curl -X POST https://api.biconomy.io/v1/execute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "ownerAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "fee": {
      "amount": "10000000000000000",
      "token": "0x0000000000000000000000000000000000000000",
      "chainId": 42161
    },
    "quoteType": "permit",
    "quote": {...},
    "payloadToSign": [
      {
        ...originalPayload,
        "signature": "0x1234567890abcdef..."
      }
    ]
  }'

​
Expected Results

After execution completes, you’ll see: EOA Mode:
  • 10 USDC deducted from Arbitrum (plus ~$0.1 for fees, depending on gas price)
  • ~10 USDT received on Optimism
EIP-7702 Mode:
  • Same balance changes as EOA
  • EOA is now delegated (persistent for future transactions)
Smart Account Mode:
  • Nexus balance on Arbitrum: 10 USDC deducted (plus fees)
  • Nexus balance on Optimism: ~10 USDT received
  • USDT remains in Nexus until withdrawn

​
Decision Tree

​
Quick Tips

Frontend Integration: Use EOA mode for the simplest user experience with MetaMask
Backend Automation: Use EIP-7702 mode when you control the private keys
Mobile Apps: Any mode works - choose based on your wallet infrastructure