Build simple cross-chain swap intents for your supertransaction

​
Overview

The /v1/instructions/intent-simple endpoint enables straightforward cross-chain token swaps. Users specify source and destination tokens across different chains, and the system handles routing through bridge aggregators and swap providers.

​
How It Works

The intent-simple endpoint manages cross-chain swaps by:
  1. Accepting swap parameters - Source token, destination token, and chains
  2. Leveraging aggregators - Uses bridge aggregators and router providers (LiFi, GlueX, Across, etc.) in the background
  3. Automatic routing - Finds the optimal path for cross-chain swaps

​
Request Structure

POST /v1/instructions/intent-simple

​
Request Body

ParameterTypeRequiredDescription
srcTokenstringYesSource token EVM address (checksummed)
dstTokenstringYesDestination token EVM address (checksummed)
srcChainIdnumberYesSource chain ID
dstChainIdnumberYesDestination chain ID
ownerAddressstringYesEOA wallet address (owner of orchestrator account)
amountstringYesAmount to swap (in wei/smallest unit)
modestringYesExecution mode: smart-account, eoa, or eoa-7702
slippagenumberYesSlippage tolerance (0-1, default 0.01 = 1%)
allowSwapProvidersstringNoComma-separated allowed swap providers
denySwapProvidersstringNoComma-separated denied swap providers
allowBridgeProvidersstringNoComma-separated allowed bridge providers
denyBridgeProvidersstringNoComma-separated denied bridge providers

​
Example Request

curl -X POST https://api.biconomy.io/v1/instructions/intent-simple \
  -H "Content-Type: application/json" \
  -H "X-API-Key: mee_2w3mXCuyt4xVXDRCZ5k5Lhgs" \
  -d '{
    "srcToken": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "dstToken": "0x94b008aa00579c1307b0ef2c499ad98a8ce58e58",
    "srcChainId": 8453,
    "dstChainId": 10,
    "ownerAddress": "0x742d35cc6639cb8d4b5d1c5d7b8b5e2e7c0c7a8a",
    "amount": "1000000",
    "mode": "smart-account",
    "slippage": 0.01,
    "allowSwapProviders": "lifi,gluex",
    "allowBridgeProviders": "across"
  }'

​
Response

Returns MEE instructions with detailed route information: 
{
  "instructions": [
    {
      "calls": [...],
      "chainId": 8453,
      "isComposable": true
    }
  ],
  "outputAmount": "999960",
  "minOutputAmount": "989960",
  "route": {
    "summary": "lifi[sushiswap] => across[SpokePoolV3]",
    "steps": [
      {
        "type": "swap",
        "protocol": "lifi",
        "sources": ["sushiswap"],
        "srcToken": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
        "dstToken": "0x94b008aa00579c1307b0ef2c499ad98a8ce58e58",
        "srcChainId": 8453,
        "dstChainId": 10,
        "inputAmount": "1000000",
        "outputAmount": "999960",
        "minOutputAmount": "989960",
        "toContract": "0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE",
        "callData": "0x...",
        "isFirstStep": true
      }
    ],
    "totalGasFeesUsd": 0,
    "totalBridgeFeesUsd": 0,
    "estimatedTime": 0,
    "outputAmount": "999960",
    "minOutputAmount": "989960",
    "type": "PIVOT_USDT"
  }
}

​
Response Fields

FieldTypeDescription
instructionsarrayArray of MEE instruction objects for execution
outputAmountstringExpected output token amount (in wei)
minOutputAmountstringMinimum guaranteed output amount after slippage (in wei)
routeobjectDetailed routing information
route.summarystringHuman-readable route summary
route.stepsarrayDetailed steps in the route
route.totalGasFeesUsdnumberEstimated total gas fees in USD
route.totalBridgeFeesUsdnumberEstimated total bridge fees in USD
route.estimatedTimenumberEstimated execution time in seconds
route.typestringRoute type (e.g., “PIVOT_USDT”)

​
Route Step Structure

Each step in the route contains:
FieldTypeDescription
typestringStep type: “swap” or “bridge”
protocolstringProtocol used (e.g., “lifi”)
sourcesarrayDEXes or sources used
srcTokenstringSource token address
dstTokenstringDestination token address
srcChainIdnumberSource chain ID
dstChainIdnumberDestination chain ID
inputAmountstringInput amount for this step
outputAmountstringOutput amount from this step
minOutputAmountstringMinimum output after slippage
toContractstringTarget contract for this step
callDatastringEncoded call data
isFirstStepbooleanWhether this is the first step
pivotBalancestringOptional pivot balance for route

​
Supported Providers

The system automatically selects from available bridge aggregators and swap providers. You can control provider selection using the allow/deny parameters:
  • Swap Providers: LiFi, GlueX, and others
  • Bridge Providers: Across, and others
Use allowSwapProviders/denySwapProviders and allowBridgeProviders/denyBridgeProviders to control provider selection.

​
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

Returned when the request is malformed or contains invalid parameters: 
{
  "code": "VALIDATION_ERROR",
  "message": "Invalid request parameters",
  "errors": [
    {
      "code": "INVALID_FIELD",
      "path": ["srcToken"],
      "message": "Invalid token address format"
    }
  ]
}

​
500 Internal Server Error

Returned when the server encounters an unexpected error: 
{
  "code": "INTERNAL_ERROR",
  "message": "An unexpected error occurred",
  "errors": [
    {
      "code": "SERVER_ERROR",
      "path": [],
      "message": "Internal server error"
    }
  ]
}

​
Mode Options

The mode parameter determines how the transaction will be executed:
  • smart-account: Execute through a smart account wallet
  • eoa: Execute through an Externally Owned Account
  • eoa-7702: Execute through an EOA with EIP-7702 delegation

​
Slippage Configuration

The slippage parameter accepts values between 0 and 1:
  • 0.01 = 1% slippage
  • 0.05 = 5% slippage
  • 1 = 100% slippage (not recommended)
Default value is 0.01 (1%) if not specified.