Compose multiple instructions and intents for your supertransaction

​
Overview

The /v1/instructions/compose endpoint enables developers to combine multiple operations (intent, intent-simple, and build) into a single composable supertransaction. This allows for complex multi-step workflows across different chains and protocols.

​
How It Works

The compose endpoint enables complex workflows by:
  1. Accepting multiple operations - Combine up to 10 operations in a single request
  2. Supporting all operation types - Mix intent, intent-simple, and build calls
  3. Batching control - Optional batching of instructions for efficiency
  4. Cross-chain execution - Seamlessly coordinate operations across different chains

​
Request Structure

POST /v1/instructions/compose

​
Request Body

ParameterTypeRequiredDescription
ownerAddressstringYesEOA wallet address (owner of orchestrator accounts)
modestringYesExecution mode: smart-account, eoa, or eoa-7702
composeFlowsarrayYesArray of operations (1-10 items)

​
ComposeFlow Structure

Each item in composeFlows contains:
ParameterTypeRequiredDescription
typestringYesOperation type: /instructions/build, /instructions/intent-simple, or /instructions/intent
dataobjectYesOperation-specific data matching the respective endpoint
batchbooleanNoEnable/disable instruction batching (default: true)

​
Example Request - Swap and Supply

curl -X POST https://api.biconomy.io/v1/instructions/compose \
  -H "Content-Type: application/json" \
  -H "X-API-Key: mee_2w3mXCuyt4xVXDRCZ5k5Lhgs" \
  -d '{
    "ownerAddress": "0x742d35cc6639cb8d4b5d1c5d7b8b5e2e7c0c7a8a",
    "mode": "smart-account",
    "composeFlows": [
      {
        "type": "/instructions/intent-simple",
        "data": {
          "srcToken": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
          "dstToken": "0x94b008aa00579c1307b0ef2c499ad98a8ce58e58",
          "srcChainId": 8453,
          "dstChainId": 10,
          "amount": "1000000",
          "slippage": 0.01
        },
        "batch": true
      },
      {
        "type": "/instructions/build",
        "data": {
          "functionSignature": "function transfer(address to, uint256 amount)",
          "args": [
            "0x742d35cc6639cb8d4b5d1c5d7b8b5e2e7c0c7a8a",
            "1000000"
          ],
          "to": "0x94b008aa00579c1307b0ef2c499ad98a8ce58e58",
          "chainId": 10,
          "value": "0"
        },
        "batch": true
      }
    ]
  }'

​
Response

Returns composed MEE instructions ready for execution: 
{
  "instructions": [
    {
      "calls": [
        {
          "to": "0x1111111254EEB25477B68fb85Ed929f73A960582",
          "value": "0",
          "functionSig": "swap(address,address,uint256)",
          "inputParams": [...],
          "outputParams": [...]
        }
      ],
      "chainId": 8453,
      "isComposable": true
    },
    {
      "calls": [
        {
          "to": "0x94b008aa00579c1307b0ef2c499ad98a8ce58e58",
          "value": "0",
          "functionSig": "transfer(address,uint256)",
          "inputParams": [...],
          "outputParams": [...]
        }
      ],
      "chainId": 10,
      "isComposable": true
    }
  ],
  "returnedData": []
}

​
Response Fields

FieldTypeDescription
instructionsarrayArray of composed MEE instructions
returnedDataarrayAdditional data returned from composition

​
Supported Operation Types

​
1. Build Operation (/instructions/build)

Direct contract calls with custom function signatures: 
{
  "type": "/instructions/build",
  "data": {
    "functionSignature": "function approve(address spender, uint256 amount)",
    "args": ["0xSpender", "1000000000000000000"],
    "to": "0xTokenContract",
    "chainId": 1,
    "value": "0",
    "gasLimit": "50000"
  }
}

​
2. Intent-Simple Operation (/instructions/intent-simple)

Cross-chain token swaps: 
{
  "type": "/instructions/intent-simple",
  "data": {
    "srcToken": "0xSourceToken",
    "dstToken": "0xDestToken",
    "srcChainId": 1,
    "dstChainId": 10,
    "amount": "1000000",
    "slippage": 0.01,
    "allowSwapProviders": "lifi,gluex",
    "allowBridgeProviders": "across"
  }
}

​
3. Intent Operation (/instructions/intent)

Complex multi-asset rebalancing: 
{
  "type": "/instructions/intent",
  "data": {
    "slippage": 0.003,
    "inputPositions": [
      {
        "chainToken": {
          "chainId": 8453,
          "tokenAddress": "0xToken1"
        },
        "amount": "1000000"
      }
    ],
    "targetPositions": [
      {
        "chainToken": {
          "chainId": 10,
          "tokenAddress": "0xToken2"
        },
        "weight": 0.5
      },
      {
        "chainToken": {
          "chainId": 1,
          "tokenAddress": "0xToken3"
        },
        "weight": 0.5
      }
    ]
  }
}

​
Complex Workflow Examples

​
DeFi Strategy: Swap → Approve → Supply

{
  "ownerAddress": "0xUser",
  "mode": "smart-account",
  "composeFlows": [
    {
      "type": "/instructions/intent-simple",
      "data": {
        "srcToken": "0xUSDC",
        "dstToken": "0xWETH",
        "srcChainId": 1,
        "dstChainId": 1,
        "amount": "1000000000",
        "slippage": 0.01
      }
    },
    {
      "type": "/instructions/build",
      "data": {
        "functionSignature": "function approve(address spender, uint256 amount)",
        "args": ["0xAavePool", "115792089237316195423570985008687907853269984665640564039457584007913129639935"],
        "to": "0xWETH",
        "chainId": 1
      }
    },
    {
      "type": "/instructions/build",
      "data": {
        "functionSignature": "function supply(address asset, uint256 amount, address onBehalfOf, uint16 referralCode)",
        "args": ["0xWETH", "1000000000000000000", "0xUser", 0],
        "to": "0xAavePool",
        "chainId": 1
      }
    }
  ]
}

​
Cross-Chain Portfolio Rebalancing

{
  "ownerAddress": "0xUser",
  "mode": "smart-account",
  "composeFlows": [
    {
      "type": "/instructions/intent",
      "data": {
        "slippage": 0.01,
        "inputPositions": [
          {
            "chainToken": {
              "chainId": 1,
              "tokenAddress": "0xUSDC"
            },
            "amount": "10000000000"
          },
          {
            "chainToken": {
              "chainId": 10,
              "tokenAddress": "0xDAI"
            },
            "amount": "5000000000000000000000"
          }
        ],
        "targetPositions": [
          {
            "chainToken": {
              "chainId": 8453,
              "tokenAddress": "0xWETH"
            },
            "weight": 0.6
          },
          {
            "chainToken": {
              "chainId": 42161,
              "tokenAddress": "0xWBTC"
            },
            "weight": 0.4
          }
        ]
      }
    }
  ]
}

​
Authentication

All requests require an API key to be passed in the header: 
X-API-Key: your_api_key_here

​
Error Responses

​
400 Bad Request

{
  "code": "VALIDATION_ERROR",
  "message": "Invalid request parameters",
  "errors": [
    {
      "code": "INVALID_COMPOSE_FLOW",
      "path": ["composeFlows", "0", "type"],
      "message": "Invalid operation type"
    }
  ]
}

​
500 Internal Server Error

{
  "code": "INTERNAL_ERROR",
  "message": "An unexpected error occurred",
  "errors": [
    {
      "code": "SERVER_ERROR",
      "path": [],
      "message": "Internal server error"
    }
  ]
}

​
Best Practices

  1. Order matters: Operations are executed in the order specified
  2. Chain coordination: Ensure operations on dependent chains are properly sequenced
  3. Gas optimization: Use batching where appropriate to reduce gas costs
  4. Error handling: Implement proper error handling for each operation type
  5. Testing: Test complex compositions on testnets first
  6. Limits: Keep within the 10-operation limit per request