DeFi Workflow Examples

Build complex DeFi strategies using the Supertransaction API’s intent-based infrastructure for multi-chain execution. The Supertransaction system provides powerful REST APIs for orchestrating DeFi workflows across multiple chains with a single signature:

Intent-Based Swaps: Token transformations with automatic route optimization
Portfolio Rebalancing: Multi-asset allocation management
Composable Actions: Chain multiple operations in sequence
Custom Operations: Direct contract calls when needed

Intent-First Approach
Express DeFi operations as token transformations (input → output) and let the solver network find optimal execution paths. Only use custom calls for operations that can’t be expressed as intents.

Workflow Process

Create instructions using intent APIs (/intent, /intent-simple, or /compose)
Generate a quote with /v1/mee/quote
Sign the returned payloads
Execute with /v1/mee/execute

1. Token Operations with Intents

Use intent-based APIs for all token transformations, including DeFi deposits and withdrawals.

Simple Token Swap

Example: Swap 1 ETH to USDC

const ETH = '0x0000000000000000000000000000000000000000'; // Native Ethereum
const USDC = '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'; // USDC on Ethereum

// Step 1: Create swap intent
const swapIntent = await fetch('https://api.biconomy.io/v1/instructions/intent-simple', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.API_KEY
  },
  body: JSON.stringify({
    srcToken: ETH,
    dstToken: USDC,
    srcChainId: 1,
    dstChainId: 1,
    fromAddress: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
    amount: '1000000000000000000', // 1 ETH in wei
    mode: 'smart-account',
    slippage: 0.005 // 0.5%
  })
});

const { instructions } = await swapIntent.json();

// Step 2: Generate quote
const quote = await fetch('https://api.biconomy.io/v1/mee/quote', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.API_KEY
  },
  body: JSON.stringify({
    type: 'smart-account',
    fromAddress: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
    instructions: instructions,
    fundingTokens: [{
      tokenAddress: ETH,
      chainId: 1,
      amount: '1000000000000000000'
    }]
  })
});

const quoteData = await quote.json();

// Step 3: Sign and execute (see Execution Flow section)

Aave Deposit via Intent

Example: Deposit WETH to get aWETH (expressed as token transformation)

const WETH = '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2'; // Wrapped ETH
const aWETH = '0x4d5F47FA6A74757f35C14fD3a6Ef8E3C9BC514E8'; // Aave V3 WETH

const depositIntent = await fetch('https://api.biconomy.io/v1/instructions/intent-simple', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.API_KEY
  },
  body: JSON.stringify({
    srcToken: WETH,
    dstToken: aWETH,
    srcChainId: 1,
    dstChainId: 1,
    fromAddress: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
    amount: '1000000000000000000', // 1 WETH
    mode: 'smart-account',
    slippage: 0.001 // 0.1% slippage for deposits
  })
});

2. Portfolio Management with Intents

Use the /intent endpoint for complex multi-asset rebalancing.

Multi-Token LP Entry

Example: Deposit multiple stablecoins into Curve 3pool

const DAI = '0x6B175474E89094C44Da98b954EedeAC495271d0F';
const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
const USDT = '0xdAC17F958D2ee523a2206206994597C13D831ec7';
const curve3poolLP = '0x6c3F90f043a72FA612cbac8115EE7e52BDe6E490';

const lpIntent = await fetch('https://api.biconomy.io/v1/instructions/intent', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.API_KEY
  },
  body: JSON.stringify({
    slippage: 0.005,
    receiver: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
    inputPositions: [
      {
        chainToken: { chainId: 1, tokenAddress: DAI },
        amount: '10000000000000000000' // 10 DAI
      },
      {
        chainToken: { chainId: 1, tokenAddress: USDC },
        amount: '10000000' // 10 USDC
      },
      {
        chainToken: { chainId: 1, tokenAddress: USDT },
        amount: '10000000' // 10 USDT
      }
    ],
    targetPositions: [
      {
        chainToken: { chainId: 1, tokenAddress: curve3poolLP },
        weight: 1.0 // 100% to LP token
      }
    ]
  })
});

3. Composed Strategies

Combine multiple operations using the /compose endpoint for complex DeFi strategies.

Leveraged Staking Position

Example: Create 2x leveraged ETH position using Aave with dynamic amounts

const WETH = '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2';
const aWETH = '0x4d5F47FA6A74757f35C14fD3a6Ef8E3C9BC514E8';
const USDC = '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48';
const aaveV3Pool = '0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2';

const leveragedPosition = await fetch('https://api.biconomy.io/v1/instructions/compose', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.API_KEY
  },
  body: JSON.stringify([
    {
      type: '/instructions/intent-simple',
      data: {
        srcToken: WETH,
        dstToken: aWETH,
        srcChainId: 1,
        dstChainId: 1,
        fromAddress: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
        amount: '1000000000000000000', // 1 WETH
        mode: 'smart-account',
        slippage: 0.001
      }
    },
    {
      type: '/instructions/build',
      data: {
        functionSignature: 'function borrow(address asset, uint256 amount, uint256 interestRateMode, uint16 referralCode, address onBehalfOf)',
        args: [
          USDC,
          '1000000000', // 1000 USDC
          2, // Variable rate
          0, // No referral
          '0xd8da6bf26964af9d7eed9e03e53415d37aa96045'
        ],
        to: aaveV3Pool,
        chainId: 1
      }
    },
    {
      type: '/instructions/intent-simple',
      data: {
        srcToken: USDC,
        dstToken: WETH,
        srcChainId: 1,
        dstChainId: 1,
        fromAddress: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
        amount: '1000000000', // 1000 USDC
        mode: 'smart-account',
        slippage: 0.01
      }
    },
    {
      type: '/instructions/intent-simple',
      data: {
        srcToken: WETH,
        dstToken: aWETH,
        srcChainId: 1,
        dstChainId: 1,
        fromAddress: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
        amount: {
          type: 'runtimeErc20Balance', // Use all WETH from swap
          targetAddress: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
          tokenAddress: WETH
        },
        mode: 'smart-account',
        slippage: 0.001
      }
    }
  ])
});

Multi-Step Yield Optimization

Example: Swap, split, and deploy across multiple protocols using dynamic amounts

const USDC = '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48';
const DAI = '0x6B175474E89094C44Da98b954EedeAC495271d0F';
const aUSDC = '0x98C23E9d8f34FEFb1B7BD6a91B7FF122F4e16F5c';
const cDAI = '0x5d3a536E4D6DbD6114cc1Ead35777bAB948E3643';

const yieldOptimization = await fetch('https://api.biconomy.io/v1/instructions/compose', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.API_KEY
  },
  body: JSON.stringify([
    {
      type: '/instructions/intent-simple',
      data: {
        srcToken: USDC,
        dstToken: DAI,
        srcChainId: 1,
        dstChainId: 1,
        fromAddress: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
        amount: '500000000', // 500 USDC
        mode: 'smart-account',
        slippage: 0.005
      }
    },
    {
      type: '/instructions/intent-simple',
      data: {
        srcToken: USDC,
        dstToken: aUSDC,
        srcChainId: 1,
        dstChainId: 1,
        fromAddress: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
        amount: {
          type: 'runtimeErc20Balance', // Use remaining USDC
          targetAddress: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
          tokenAddress: USDC
        },
        mode: 'smart-account',
        slippage: 0.001
      }
    },
    {
      type: '/instructions/intent-simple',
      data: {
        srcToken: DAI,
        dstToken: cDAI,
        srcChainId: 1,
        dstChainId: 1,
        fromAddress: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
        amount: {
          type: 'runtimeErc20Balance', // Use all DAI from swap
          targetAddress: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
          tokenAddress: DAI
        },
        mode: 'smart-account',
        slippage: 0.001
      }
    }
  ])
});

Position Migration

Example: Move from Compound to Aave

const cETH = '0x4ddc2d193948926d02f9b1fe9e1daa0718270ed5';
const ETH = '0x0000000000000000000000000000000000000000';
const aWETH = '0x4d5F47FA6A74757f35C14fD3a6Ef8E3C9BC514E8';

const migrationIntent = await fetch('https://api.biconomy.io/v1/instructions/compose', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.API_KEY
  },
  body: JSON.stringify([
    {
      type: '/instructions/intent-simple',
      data: {
        srcToken: cETH,
        dstToken: ETH,
        srcChainId: 1,
        dstChainId: 1,
        fromAddress: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
        amount: '5000000000', // cETH amount
        mode: 'smart-account',
        slippage: 0.001
      }
    },
    {
      type: '/instructions/intent-simple',
      data: {
        srcToken: ETH,
        dstToken: aWETH,
        srcChainId: 1,
        dstChainId: 1,
        fromAddress: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
        amount: '1000000000000000000', // 1 ETH
        mode: 'smart-account',
        slippage: 0.001
      }
    }
  ])
});

4. Custom Operations (When Intents Won’t Work)

Use custom function calls only for operations that can’t be expressed as token transformations.

Borrowing Operations

Example: Borrow against collateral (requires custom call)

const USDC = '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48';
const aaveV3Pool = '0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2';

const borrowInstruction = await fetch('https://api.biconomy.io/v1/instructions/build', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.API_KEY
  },
  body: JSON.stringify({
    functionSignature: 'function borrow(address asset, uint256 amount, uint256 interestRateMode, uint16 referralCode, address onBehalfOf)',
    args: [
      USDC,
      '1000000000', // 1000 USDC
      2, // Variable interest rate
      0, // No referral code
      '0xd8da6bf26964af9d7eed9e03e53415d37aa96045'
    ],
    to: aaveV3Pool,
    chainId: 1,
    value: '0'
  })
});

Claiming Rewards

Example: Harvest staking rewards (requires custom call)

const curveGauge = '0xbFcF63294aD7105dEa65aA58F8AE5BE2D9d0952A';

const harvestInstruction = await fetch('https://api.biconomy.io/v1/instructions/build', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.API_KEY
  },
  body: JSON.stringify({
    functionSignature: 'function getReward()',
    args: [],
    to: curveGauge,
    chainId: 1,
    value: '0'
  })
});

Execution Flow

After creating instructions, generate and execute the supertransaction:

// Step 1: Generate quote with instructions
const quoteResponse = await fetch('https://api.biconomy.io/v1/mee/quote', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.API_KEY
  },
  body: JSON.stringify({
    type: 'smart-account', // or 'eoa' or 'eoa-7702'
    fromAddress: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
    instructions: instructionData.instructions,
    fundingTokens: [{
      tokenAddress: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
      chainId: 1,
      amount: '1000000000'
    }],
    feeToken: { // Optional - omit for sponsored transactions
      address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
      chainId: 1
    }
  })
});

const quote = await quoteResponse.json();

// Step 2: Sign the payloads
const signatures = await Promise.all(
  quote.payloadToSign.map(async (payload) => {
    if (quote.quoteType === 'permit') {
      return await wallet.signTypedData(payload.signablePayload);
    } else if (quote.quoteType === 'simple') {
      return await wallet.signMessage(payload.message.raw);
    }
    // Handle 'onchain' type for EOA mode if needed
  })
);

// Step 3: Execute the supertransaction
const executionResponse = await fetch('https://api.biconomy.io/v1/mee/execute', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.API_KEY
  },
  body: JSON.stringify({
    ...quote,
    payloadToSign: quote.payloadToSign.map((payload, index) => ({
      ...payload,
      signature: signatures[index]
    }))
  })
});

const result = await executionResponse.json();
console.log('Supertransaction hash:', result.supertxHash);

Quote and Execute Details

The quote/execute flow works as follows:

Quote Generation (/v1/mee/quote): Returns payloads requiring signatures based on execution mode
- Smart Account: Typically returns permit or simple payloads
- EOA: Returns permit (gasless) or onchain (approval tx) payloads
- EIP-7702: Requires authorization first if not provided
Signing: Sign returned payloads with appropriate method
- permit: EIP-712 typed data signature
- simple: Plain message signature
- onchain: Send approval transaction
Execution (/v1/mee/execute): Submit signed quote to execute across chains

Best Practices

Use Intents First

Express operations as token transformations when possible
Let the solver network optimize execution paths
Only use custom calls for non-transferable operations

Slippage Guidelines

Stablecoins: 0.001-0.005 (0.1-0.5%)
Major tokens: 0.005-0.01 (0.5-1%)
Volatile tokens: 0.01-0.03 (1-3%)
LP tokens: 0.005-0.02 (0.5-2%)

Fee Payment Flexibility

Pay with any ERC-20 from any chain
Use native tokens with address 0x0000...0000
Omit feeToken for sponsored transactions

Execution Modes

Smart Account: Best for apps with deployed smart accounts
EOA: One-click flow for MetaMask users
EIP-7702: For embedded wallets and backend automation

About Supertransaction API

Workflow Examples

Building Workflow Instructions

Executing Workflows

API Reference

Workflow Process

1. Token Operations with Intents

Simple Token Swap

Aave Deposit via Intent

2. Portfolio Management with Intents

Multi-Token LP Entry

3. Composed Strategies

Leveraged Staking Position

Multi-Step Yield Optimization

Position Migration

4. Custom Operations (When Intents Won’t Work)

Borrowing Operations

Claiming Rewards

Execution Flow

Quote and Execute Details

Best Practices

Use Intents First

Slippage Guidelines

Fee Payment Flexibility

Execution Modes

About Supertransaction API

Workflow Examples

Building Workflow Instructions

Executing Workflows

API Reference

​Workflow Process

​1. Token Operations with Intents

​Simple Token Swap

​Aave Deposit via Intent

​2. Portfolio Management with Intents

​Multi-Token LP Entry

​3. Composed Strategies

​Leveraged Staking Position

​Multi-Step Yield Optimization

​Position Migration

​4. Custom Operations (When Intents Won’t Work)

​Borrowing Operations

​Claiming Rewards

​Execution Flow

​Quote and Execute Details

​Best Practices

​Use Intents First

​Slippage Guidelines

​Fee Payment Flexibility

​Execution Modes

Workflow Process

1. Token Operations with Intents

Simple Token Swap

Aave Deposit via Intent

2. Portfolio Management with Intents

Multi-Token LP Entry

3. Composed Strategies

Leveraged Staking Position

Multi-Step Yield Optimization

Position Migration

4. Custom Operations (When Intents Won’t Work)

Borrowing Operations

Claiming Rewards

Execution Flow

Quote and Execute Details

Best Practices

Use Intents First

Slippage Guidelines

Fee Payment Flexibility

Execution Modes