Skip to main content
This instruction type enables advanced portfolio operations with multiple input and output positions. Define what you want (target tokens with weights), and the system automatically handles routing, bridging, and conversions.

​
How It Works

The intent flow:
  1. Accepts input positions - Multiple source tokens with amounts
  2. Defines target positions - Desired output tokens with weights (must sum to 1.0)
  3. Automatic routing - Finds optimal paths for rebalancing
  4. Handles everything - Swaps, bridges, and multi-step conversions

​
Parameters

When using /instructions/intent in your composeFlows array:
ParameterTypeRequiredDescription
slippagenumberYesSlippage tolerance (0-1, e.g., 0.01 = 1%)
inputPositionsarrayYesSource tokens with amounts (≥1)
targetPositionsarrayYesTarget tokens with weights (≥1, weights sum to 1.0)

​
Input Position Structure

{
  chainToken: {
    chainId: number,
    tokenAddress: string
  },
  amount: string // in wei
}

​
Target Position Structure

{
  chainToken: {
    chainId: number,
    tokenAddress: string
  },
  weight: number // 0-1, all weights must sum to 1.0
}

​
Complete Workflow Examples

  • Portfolio Rebalancing
  • Multi-Input Rebalancing
  • Complex Multi-Chain
Split USDC into multiple tokens
import { createWalletClient, http, parseUnits } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { base } from 'viem/chains';

const account = privateKeyToAccount('0x...');
const walletClient = createWalletClient({
  account,
  chain: base,
  transport: http()
});

// Step 1: Build quote request
const quoteRequest = {
  mode: 'smart-account',
  ownerAddress: account.address,
  composeFlows: [
    {
      type: '/instructions/intent',
      data: {
        slippage: 0.01,
        inputPositions: [{
          chainToken: {
            chainId: 8453, // Base
            tokenAddress: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913' // USDC
          },
          amount: parseUnits('1000', 6).toString() // 1000 USDC
        }],
        targetPositions: [
          {
            chainToken: {
              chainId: 8453, // Base
              tokenAddress: '0x4200000000000000000000000000000000000006' // WETH
            },
            weight: 0.6 // 60% to WETH
          },
          {
            chainToken: {
              chainId: 10, // Optimism
              tokenAddress: '0x94b008aa00579c1307b0ef2c499ad98a8ce58e58' // USDT
            },
            weight: 0.4 // 40% to USDT
          }
        ]
      }
    }
  ]
};

// Step 2: Get quote
const quote = await fetch('https://api.biconomy.io/v1/quote', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(quoteRequest)
}).then(r => r.json());

console.log('Quote type:', quote.quoteType); // 'simple' for smart-account
console.log('Returned data:', quote.returnedData); // Details for each position

// Then sign and POST to /v1/execute

​
Returned Data Structure

The quote response includes details for each target position: 
{
  "ownerAddress": "0x...",
  "mode": "smart-account",
  "fee": {...},
  "quoteType": "simple",
  "quote": {...},
  "payloadToSign": [...],
  "returnedData": [
    {
      "outputAmount": "599850000",
      "minOutputAmount": "593850000",
      "targetPosition": {
        "chainToken": {
          "chainId": 8453,
          "tokenAddress": "0x4200000000000000000000000000000000000006"
        },
        "weight": 0.6
      },
      "route": {
        "summary": "lifi[uniswapv3]",
        "steps": [...]
      }
    },
    {
      "outputAmount": "399900000",
      "minOutputAmount": "395900000",
      "targetPosition": {
        "chainToken": {
          "chainId": 10,
          "tokenAddress": "0x94b008aa00579c1307b0ef2c499ad98a8ce58e58"
        },
        "weight": 0.4
      },
      "route": {
        "summary": "lifi[uniswapv3] => across[SpokePoolV3]",
        "steps": [...]
      }
    }
  ]
}

​
Intent vs Direct Instructions

The Supertransaction API offers two approaches:
ApproachUse CaseControl Level
Intent-based (this endpoint)Express desired outcome, system determines executionHigh-level abstraction
Direct instructions (/instructions/build)Explicitly specify each stepFull control over execution
The intent approach simplifies complex multi-chain operations by automatically:
  • Finding optimal routes
  • Handling protocol interactions
  • Managing cross-chain complexity
  • Optimizing for gas efficiency

​
Best Practices

All target position weights must sum to exactly 1.0:
// ✅ Valid
targetPositions: [
  { chainToken: {...}, weight: 0.6 },
  { chainToken: {...}, weight: 0.4 }
] // Sum = 1.0

// ❌ Invalid
targetPositions: [
  { chainToken: {...}, weight: 0.5 },
  { chainToken: {...}, weight: 0.6 }
] // Sum = 1.1
Use higher slippage for complex rebalancing:
// Simple rebalancing: 1%
slippage: 0.01

// Complex multi-chain rebalancing: 2%
slippage: 0.02

// Many positions with cross-chain: 3%
slippage: 0.03
Check each position’s output in returnedData:
quote.returnedData.forEach((positionResult, index) => {
  const outputUi = formatUnits(BigInt(positionResult.outputAmount), 6);
  const minOutputUi = formatUnits(BigInt(positionResult.minOutputAmount), 6);

  console.log(`Position ${index + 1}:`);
  console.log(`  Expected: ${outputUi}`);
  console.log(`  Minimum: ${minOutputUi}`);
  console.log(`  Route: ${positionResult.route.summary}`);
});
Intent is perfect for:
  • Rebalancing portfolios to target allocations
  • Converting multiple small positions into fewer tokens
  • Distributing one token across multiple chains
  • DCA (dollar-cost averaging) strategies

​
Troubleshooting

Ensure all weights add up to exactly 1.0:
const weights = targetPositions.map(p => p.weight);
const sum = weights.reduce((a, b) => a + b, 0);

if (Math.abs(sum - 1.0) > 0.0001) {
  throw new Error(`Weights sum to ${sum}, must be 1.0`);
}
If routing fails:
  • Check token liquidity on source and target chains
  • Verify token addresses are correct
  • Try adjusting weights to reduce complexity
  • Increase slippage tolerance
If outputs are too low:
  • Review each position’s route in returnedData
  • Check if bridge fees are higher than expected
  • Consider splitting into separate operations
  • Verify market prices are as expected