Build complex multi-chain intents for your supertransaction

​
Overview

The /v1/instructions/intent endpoint enables users to express their desired outcome without specifying implementation details. Users define input tokens and target output tokens with weights, and the system automatically determines the optimal execution path.

​
How It Works

The intent endpoint abstracts away complexity by:
  1. Accepting input positions - Specify source tokens with amounts (e.g., USDC on Base)
  2. Defining target positions - Specify desired output tokens with weights that must sum to 1
  3. Automatic routing - The system finds the best path between tokens, handling:
    • Withdrawals from source protocols
    • Cross-chain bridging
    • Swaps and conversions
    • Deposits into destination protocols

​
Request Structure

POST /v1/instructions/intent

​
Request Body

ParameterTypeRequiredDescription
slippagenumberYesSlippage tolerance between 0 and 1 (e.g., 0.003 for 0.3%)
ownerAddressstringYesThe EVM address that will receive the output of the intent request
inputPositionsarrayYesArray of source tokens with amounts (minimum 1 item)
targetPositionsarrayYesArray of target tokens with weights (minimum 1 item, weights must sum to 1)

​
Input Position Structure

{
  "chainToken": {
    "chainId": number,        // Supported chain ID
    "tokenAddress": string    // Valid EVM token address
  },
  "amount": string           // Amount in wei/smallest unit
}

​
Target Position Structure

{
  "chainToken": {
    "chainId": number,        // Supported chain ID  
    "tokenAddress": string    // Valid EVM token address
  },
  "weight": number           // Weight between 0 and 1
}

​
Example Request

​
Single Asset Swap

Convert USDC on Base to a vault token on Base: 
curl -X POST https://api.biconomy.io/v1/instructions/intent \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "slippage": 0.003,
    "ownerAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "inputPositions": [
      {
        "chainToken": {
          "chainId": 8453,
          "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
        },
        "amount": "1000000"
      }
    ],
    "targetPositions": [
      {
        "chainToken": {
          "chainId": 8453,
          "tokenAddress": "0x4e65fE4DbA92790696d040ac24Aa414708F5c0AB"
        },
        "weight": 1
      }
    ]
  }'

​
Multi-Asset Portfolio Rebalance

Convert multiple input tokens to a diversified portfolio: 
const response = await fetch('https://api.biconomy.io/v1/instructions/intent', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your-api-key'
  },
  body: JSON.stringify({
    slippage: 0.005,
    ownerAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
    inputPositions: [
      {
        chainToken: {
          chainId: 1,
          tokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' // USDC on Ethereum
        },
        amount: '5000000000' // 5000 USDC
      },
      {
        chainToken: {
          chainId: 10,
          tokenAddress: '0x7F5c764cBc14f9669B88837ca1490cCa17c31607' // USDC on Optimism
        },
        amount: '3000000000' // 3000 USDC
      }
    ],
    targetPositions: [
      {
        chainToken: {
          chainId: 8453,
          tokenAddress: '0x4200000000000000000000000000000000000006' // WETH on Base
        },
        weight: 0.6 // 60% allocation
      },
      {
        chainToken: {
          chainId: 8453,
          tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' // USDC on Base
        },
        weight: 0.4 // 40% allocation
      }
    ]
  })
});

​
Response Structure

The endpoint returns MEE instructions that will be executed to fulfill the intent: 
{
  "instructions": [
    {
      "calls": [
        {
          "to": "0x1111111254EEB25477B68fb85Ed929f73A960582",
          "value": "0",
          "functionSig": "transfer(address,uint256)",
          "inputParams": [...],
          "outputParams": [...]
        }
      ],
      "chainId": 8453,
      "isComposable": true
    }
  ]
}

​
Response Fields

FieldTypeDescription
instructionsarrayArray of MEE instructions to execute
instructions[].callsarrayContract calls within the instruction
instructions[].chainIdnumberChain ID where instruction executes
instructions[].isComposablebooleanWhether instruction can be composed with others

​
Error Responses

​
400 Bad Request

Invalid request parameters: 
{
  "code": "INVALID_REQUEST",
  "message": "Invalid input parameters",
  "errors": [
    {
      "code": "INVALID_WEIGHT_SUM",
      "path": ["targetPositions"],
      "message": "Target position weights must sum to 1"
    }
  ]
}

​
500 Internal Server Error

Server processing error: 
{
  "code": "INTERNAL_ERROR",
  "message": "Failed to process intent",
  "errors": [...]
}

​
Key Considerations

​
Weight Distribution

Target position weights must sum to exactly 1.0. For example:
  • Single target: weight = 1.0
  • Two targets with equal split: weight = 0.5 each
  • Three targets: e.g., 0.5, 0.3, 0.2

​
Slippage Settings

  • Minimum: 0 (no slippage tolerance)
  • Maximum: 1 (100% slippage)
  • Recommended: 0.003 - 0.01 (0.3% - 1%)
  • Higher slippage may be needed for:
    • Low liquidity tokens
    • Large trade sizes
    • Cross-chain operations

​
Cross-Chain Intents

The system automatically handles:
  • Bridge selection and routing
  • Gas optimization across chains
  • Atomic execution guarantees
  • Failure recovery mechanisms

​
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 (/v1/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

​
Security Requirements

All requests must include:
  • Valid API key in the X-API-Key header
  • Proper content type: application/json
  • Valid EVM addresses (checksummed)
  • Supported chain IDs