Intent

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:

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

Parameters

When using /instructions/intent in your composeFlows array:

Parameter	Type	Required	Description
`slippage`	number	Yes	Slippage tolerance (0-1, e.g., 0.01 = 1%)
`inputPositions`	array	Yes	Source tokens with amounts (≥1)
`targetPositions`	array	Yes	Target 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

Combine multiple tokens into one

const quoteRequest = {
  mode: 'smart-account',
  ownerAddress: account.address,
  composeFlows: [
    {
      type: '/instructions/intent',
      data: {
        slippage: 0.01,
        inputPositions: [
          {
            chainToken: {
              chainId: 8453,
              tokenAddress: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913' // USDC
            },
            amount: parseUnits('500', 6).toString()
          },
          {
            chainToken: {
              chainId: 10,
              tokenAddress: '0x94b008aa00579c1307b0ef2c499ad98a8ce58e58' // USDT
            },
            amount: parseUnits('500', 6).toString()
          }
        ],
        targetPositions: [{
          chainToken: {
            chainId: 8453,
            tokenAddress: '0x4200000000000000000000000000000000000006' // WETH
          },
          weight: 1.0 // 100% to WETH
        }]
      }
    }
  ]
};

// Then quote → sign → execute

Rebalance across multiple chains

const quoteRequest = {
  mode: 'smart-account',
  ownerAddress: account.address,
  composeFlows: [
    {
      type: '/instructions/intent',
      data: {
        slippage: 0.01,
        inputPositions: [{
          chainToken: {
            chainId: 8453,
            tokenAddress: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'
          },
          amount: parseUnits('2000', 6).toString()
        }],
        targetPositions: [
          {
            chainToken: {
              chainId: 8453,
              tokenAddress: '0x4200000000000000000000000000000000000006'
            },
            weight: 0.4 // 40% WETH on Base
          },
          {
            chainToken: {
              chainId: 10,
              tokenAddress: '0x94b008aa00579c1307b0ef2c499ad98a8ce58e58'
            },
            weight: 0.3 // 30% USDT on Optimism
          },
          {
            chainToken: {
              chainId: 42161,
              tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831'
            },
            weight: 0.3 // 30% USDC on Arbitrum
          }
        ]
      }
    }
  ]
};

// Then quote → sign → 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:

Approach	Use Case	Control Level
Intent-based (this endpoint)	Express desired outcome, system determines execution	High-level abstraction
Direct instructions (`/instructions/build`)	Explicitly specify each step	Full 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

Ensure Weights Sum to 1.0

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

Consider Slippage for Multi-Position Operations

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

Validate Output Amounts

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}`);
});

Use for Portfolio Management

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

Weights don't sum to 1.0

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`);
}

No route found for some positions

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

Output amounts lower than expected

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

Migration Guides

API Endpoints

How It Works

Parameters

Input Position Structure

Target Position Structure

Complete Workflow Examples

Returned Data Structure

Intent vs Direct Instructions

Best Practices

Troubleshooting

​How It Works

​Parameters

​Input Position Structure

​Target Position Structure

​Complete Workflow Examples

​Returned Data Structure

​Intent vs Direct Instructions

​Best Practices

​Troubleshooting

How It Works

Parameters

Input Position Structure

Target Position Structure

Complete Workflow Examples

Returned Data Structure

Intent vs Direct Instructions

Best Practices

Troubleshooting