2. Get Execution Quote

The /v1/quote endpoint is the central endpoint for getting execution quotes. It accepts composeFlows that define your operations and returns execution costs, gas estimates, and payloads to sign.

Endpoint

POST https://api.biconomy.io/v1/quote

How It Works

The quote endpoint:

Accepts composeFlows - Takes array of operations to execute
Builds instructions - Processes flows into executable MEE instructions
Calculates fees - Determines gas costs and execution fees
Auto-detects signature type - Returns appropriate quoteType based on mode and tokens
Returns signable payloads - Provides data that needs to be signed for execution

Request Structure

Request Body

Parameter	Type	Required	Description
`mode`	string	Yes	Execution mode: `eoa`, `smart-account`, or `eoa-7702`
`ownerAddress`	string	Yes	Owner wallet address
`composeFlows`	array	Yes	Array of operations to execute (min 1)
`fundingTokens`	array	Conditional	Required for `eoa` mode only
`feeToken`	object	No	Token for gas payment. If not specified, uses sponsorship (gasless). Requires API key with sponsorship enabled.
`authorizations`	array	Conditional	Required for `eoa-7702` mode if EOA not delegated (obtained from 412 response)
`accountAddress`	object	No	Chain ID to Nexus address mapping for upgraded legacy accounts. See Account Address Override.
`gasLimit`	string	No	Override gas limit for gas payment UserOp
`lowerBoundTimestamp`	number	No	Execution time lower bound (Unix timestamp)
`upperBoundTimestamp`	number	No	Execution time upper bound (Unix timestamp)

Mode-Specific Requirements

EOA Mode
Smart Account
EIP-7702

Required fields:

fundingTokens

Important:

If feeToken is provided, it must match one of the tokens in fundingTokens (same address and chainId)

Not allowed:

authorizations

API returns:

quoteType: permit or onchain (auto-detected)

{
  "mode": "eoa",
  "ownerAddress": "0x742d35cc6639cb8d4b5d1c5d7b8b5e2e7c0c7a8a",
  "fundingTokens": [{
    "tokenAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "chainId": 8453,
    "amount": "100000000"
  }],
  "feeToken": {
    "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "chainId": 8453
  },
  "composeFlows": [...]
}

Not allowed:

fundingTokens
authorizations

API returns:

quoteType: simple (always)

{
  "mode": "smart-account",
  "ownerAddress": "0x742d35cc6639cb8d4b5d1c5d7b8b5e2e7c0c7a8a",
  "feeToken": {
    "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "chainId": 8453
  },
  "composeFlows": [...]
}

Not allowed:

fundingTokens

Conditional:

authorizations (if 412 error received)

API returns:

quoteType: simple (always)
412 error if authorization needed

{
  "mode": "eoa-7702",
  "ownerAddress": "0x742d35cc6639cb8d4b5d1c5d7b8b5e2e7c0c7a8a",
  "authorizations": [...],  // If 412 was received
  "composeFlows": [...]
}

Compose Flows

The composeFlows array defines operations to execute. Three flow types are supported:

1. `/instructions/intent-simple`

Simple token swaps (same-chain or cross-chain):

{
  "type": "/instructions/intent-simple",
  "data": {
    "srcChainId": 8453,
    "dstChainId": 10,
    "srcToken": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "dstToken": "0x94b008aa00579c1307b0ef2c499ad98a8ce58e58",
    "amount": "100000000",
    "slippage": 0.01,
    "denySwapProviders": "gluex"  // Optional
  },
  "batch": true  // Optional, default is true
}

2. `/instructions/intent`

Advanced multi-position operations:

{
  "type": "/instructions/intent",
  "data": {
    "slippage": 0.01,
    "inputPositions": [{
      "chainToken": {
        "chainId": 8453,
        "tokenAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"
      },
      "amount": "100000000"
    }],
    "targetPositions": [{
      "chainToken": {
        "chainId": 10,
        "tokenAddress": "0x94b008aa00579c1307b0ef2c499ad98a8ce58e58"
      },
      "weight": 1.0
    }]
  }
}

3. `/instructions/build`

Custom contract calls:

{
  "type": "/instructions/build",
  "data": {
    "functionSignature": "function transfer(address to, uint256 value)",
    "args": [
      "0x742d35cc6639cb8d4b5d1c5d7b8b5e2e7c0c7a8a",
      {
        "type": "runtimeErc20Balance",
        "tokenAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
        "constraints": { "gte": "1" }
      }
    ],
    "to": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "chainId": 8453,
    "gasLimit": "100000"  // Optional
  }
}

Fee Token Configuration

Optional. If not specified, defaults to sponsorship (gasless):

"feeToken": {
  "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
  "chainId": 8453
}

Your API key must have sponsorship enabled for gasless transactions. Contact support@biconomy.io if needed.

Account Address Override

The accountAddress parameter allows you to use upgraded legacy v2.1.0 addresses instead of the default v2.2.1 addresses. This is useful for users who have existing v2.1.0 deployments that have been upgraded to v2.2.1 implementation.

This parameter is only needed if you have users with legacy v2.1.0 deployments that you’ve upgraded. New applications can skip this entirely.

When to Use

Use accountAddress when:

User has a v2.1.0 Nexus deployment
The account has been upgraded to v2.2.1 implementation
You want to use the original v2.1.0-derived address (preserving funds and history)

Structure

"accountAddress": {
  "8453": "0xLegacyAddr...",   // chainId -> Nexus address
  "10": "0xLegacyAddr..."
}

Example with Account Address

// After upgrading a legacy account, use accountAddress to transact with the legacy address
const quote = await fetch('https://api.biconomy.io/v1/quote', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    ownerAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f7bD2B',
    mode: 'smart-account',
    composeFlows: [
      {
        type: '/instructions/intent-simple',
        data: {
          srcChainId: 8453,
          dstChainId: 10,
          srcToken: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
          dstToken: '0x94b008aa00579c1307b0ef2c499ad98a8ce58e58',
          amount: '100000000',
          slippage: 0.01
        }
      }
    ],
    feeToken: {
      address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
      chainId: 8453
    },
    accountAddress: {
      '8453': '0xLegacyAddr...'  // Use upgraded legacy address on Base
    }
  })
}).then(r => r.json());

Before using accountAddress, ensure the account has been upgraded via the /v1/mee/upgrade endpoint. Use /v1/mee/orchestrator to check account status and retrieve upgraded addresses.

Mode Support

Mode	`accountAddress` Support
`smart-account`	Full support
`eoa` (Fusion)	Full support
`eoa-7702`	Not applicable (EOA is the account)

Response Structure

Success Response (200)

{
  "ownerAddress": "0x742d35cc6639cb8d4b5d1c5d7b8b5e2e7c0c7a8a",
  "fee": {
    "amount": "500000",
    "token": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "chainId": 8453
  },
  "quoteType": "permit",
  "quote": {
    "hash": "0x...",
    "node": "0x...",
    "commitment": "0x...",
    "paymentInfo": {...},
    "userOps": [...],
    "fundingTokens": [...]
  },
  "payloadToSign": [
    {
      "signablePayload": {
        "domain": {...},
        "types": {...},
        "message": {...},
        "primaryType": "Permit"
      },
      "metadata": {...}
    }
  ],
  "returnedData": [
    {
      "outputAmount": "99500000",
      "minOutputAmount": "98505000",
      "route": {...}
    }
  ]
}

Response Fields

Field	Type	Description
`ownerAddress`	string	Owner wallet address
`fee`	object	Execution fee details
`quoteType`	string	Auto-detected signature type: `permit`, `onchain`, or `simple`
`quote`	object	Quote details for execution
`payloadToSign`	array	Payloads requiring signatures
`returnedData`	array	Results from compose flows (e.g., swap details)

Quote Types (Auto-Detected)

The API automatically detects and returns the appropriate signature type based on your mode and token capabilities:

permit: Token supports EIP-2612 (EOA mode) - gasless approval via EIP-712 signature
onchain: Token doesn’t support EIP-2612 (EOA mode) - requires on-chain approval transaction
simple: Smart Account or EIP-7702 mode - simple message signature

For detailed payload structures and signing instructions, see Signing Payloads.

Error Response (412) - EIP-7702 Only

When using eoa-7702 mode without authorizations and EOA is not delegated:

{
  "error": "MISSING_AUTHORIZATION",
  "message": "EIP-7702 authorization required",
  "authorizations": [
    {
      "chainId": 8453,
      "address": "0x00000069E0Fb590E092Dd0E36FF93ac28ff11a3a",
      "nonce": 38
    }
  ]
}

How to handle:

Sign authorizations using walletClient.signAuthorization()
Retry quote with signed authorizations in request

Best Practices

Let API Detect Signature Type

Don’t try to determine signature type yourself - the API automatically returns the appropriate quoteType based on token capabilities and mode.

// ✅ GOOD - Handle what API returns
if (quote.quoteType === 'permit') {
  // Sign EIP-712
} else if (quote.quoteType === 'onchain') {
  // Send approval transaction, use txHash as signature
  const txHash = await walletClient.sendTransaction({...});
  await publicClient.waitForTransactionReceipt({ hash: txHash });
} else {
  // Sign message
}

// ❌ BAD - Don't check token support yourself
if (await supportsPermit(token)) {
  // Manual logic
}

Validate Fees Before Execution

Always check fees are within acceptable limits:

const feeInUSDC = Number(quote.fee.amount) / 1e6;
if (feeInUSDC > MAX_ACCEPTABLE_FEE) {
  throw new Error('Fee too high');
}

Handle All Error Responses

Implement proper error handling:

try {
  const quote = await getQuote(request);
} catch (error) {
  if (error.status === 412) {
    // Handle 412 for EIP-7702
  } else if (error.status === 400) {
    // Handle invalid request
  } else {
    // Handle other errors
  }
}

Migration Guides

API Endpoints

Endpoint

How It Works

Request Structure

Request Body

Mode-Specific Requirements

Compose Flows

1. `/instructions/intent-simple`

2. `/instructions/intent`

3. `/instructions/build`

Fee Token Configuration

Account Address Override

When to Use

Structure

Example with Account Address

Mode Support

Response Structure

Success Response (200)

Response Fields

Quote Types (Auto-Detected)

Error Response (412) - EIP-7702 Only

Best Practices

​Endpoint

​How It Works

​Request Structure

​Request Body

​Mode-Specific Requirements

​Compose Flows

​1. /instructions/intent-simple

​2. /instructions/intent

​3. /instructions/build

​Fee Token Configuration

​Account Address Override

​When to Use

​Structure

​Example with Account Address

​Mode Support

​Response Structure

​Success Response (200)

​Response Fields

​Quote Types (Auto-Detected)

​Error Response (412) - EIP-7702 Only

​Best Practices

Endpoint

How It Works

Request Structure

Request Body

Mode-Specific Requirements

Compose Flows

1. `/instructions/intent-simple`

2. `/instructions/intent`

3. `/instructions/build`

Fee Token Configuration

Account Address Override

When to Use

Structure

Example with Account Address

Mode Support

Response Structure

Success Response (200)

Response Fields

Quote Types (Auto-Detected)

Error Response (412) - EIP-7702 Only

Best Practices