Skip to main content
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:
  1. Accepts composeFlows - Takes array of operations to execute
  2. Builds instructions - Processes flows into executable MEE instructions
  3. Calculates fees - Determines gas costs and execution fees
  4. Auto-detects signature type - Returns appropriate quoteType based on mode and tokens
  5. Returns signable payloads - Provides data that needs to be signed for execution

​
Request Structure

​
Request Body

ParameterTypeRequiredDescription
modestringYesExecution mode: eoa, smart-account, or eoa-7702
ownerAddressstringYesOwner wallet address
composeFlowsarrayYesArray of operations to execute (min 1)
fundingTokensarrayConditionalRequired for eoa mode only
feeTokenobjectNoToken for gas payment. If not specified, uses sponsorship (gasless). Requires API key with sponsorship enabled.
authorizationsarrayConditionalRequired for eoa-7702 mode if EOA not delegated (obtained from 412 response)
gasLimitstringNoOverride gas limit for gas payment UserOp
lowerBoundTimestampnumberNoExecution time lower bound (Unix timestamp)
upperBoundTimestampnumberNoExecution 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": [...]
}

​
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.

​
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

FieldTypeDescription
ownerAddressstringOwner wallet address
feeobjectExecution fee details
quoteTypestringAuto-detected signature type: permit, onchain, or simple
quoteobjectQuote details for execution
payloadToSignarrayPayloads requiring signatures
returnedDataarrayResults 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:
  1. Sign authorizations using walletClient.signAuthorization()
  2. Retry quote with signed authorizations in request

​
Best Practices

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