> ## Documentation Index
> Fetch the complete documentation index at: https://docs.biconomy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 2. Get Execution Quote

> Generate execution quotes for supertransactions

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

| 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](#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

<Tabs>
  <Tab title="EOA Mode">
    **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)

    ```json theme={null}
    {
      "mode": "eoa",
      "ownerAddress": "0x742d35cc6639cb8d4b5d1c5d7b8b5e2e7c0c7a8a",
      "fundingTokens": [{
        "tokenAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
        "chainId": 8453,
        "amount": "100000000"
      }],
      "feeToken": {
        "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
        "chainId": 8453
      },
      "composeFlows": [...]
    }
    ```
  </Tab>

  <Tab title="Smart Account">
    **Not allowed:**

    * `fundingTokens`
    * `authorizations`

    **API returns:**

    * `quoteType`: `simple` (always)

    ```json theme={null}
    {
      "mode": "smart-account",
      "ownerAddress": "0x742d35cc6639cb8d4b5d1c5d7b8b5e2e7c0c7a8a",
      "feeToken": {
        "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
        "chainId": 8453
      },
      "composeFlows": [...]
    }
    ```
  </Tab>

  <Tab title="EIP-7702">
    **Not allowed:**

    * `fundingTokens`

    **Conditional:**

    * `authorizations` (if 412 error received)

    **API returns:**

    * `quoteType`: `simple` (always)
    * `412` error if authorization needed

    ```json theme={null}
    {
      "mode": "eoa-7702",
      "ownerAddress": "0x742d35cc6639cb8d4b5d1c5d7b8b5e2e7c0c7a8a",
      "authorizations": [...],  // If 412 was received
      "composeFlows": [...]
    }
    ```
  </Tab>
</Tabs>

### 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):

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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):

```json theme={null}
"feeToken": {
  "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
  "chainId": 8453
}
```

<Warning>
  Your API key must have **sponsorship enabled** for gasless transactions. Contact [support@biconomy.io](mailto:support@biconomy.io) if needed.
</Warning>

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

<Info>
  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.
</Info>

#### When to Use

Use `accountAddress` when:

* User has a v2.1.0 Nexus deployment
* The account has been [upgraded](/supertransaction-api/endpoints/upgrade) to v2.2.1 implementation
* You want to use the original v2.1.0-derived address (preserving funds and history)

#### Structure

```json theme={null}
"accountAddress": {
  "8453": "0xLegacyAddr...",   // chainId -> Nexus address
  "10": "0xLegacyAddr..."
}
```

#### Example with Account Address

```typescript theme={null}
// 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());
```

<Warning>
  Before using `accountAddress`, ensure the account has been upgraded via the [/v1/mee/upgrade](/supertransaction-api/endpoints/upgrade) endpoint. Use [/v1/mee/orchestrator](/supertransaction-api/endpoints/orchestrator) to check account status and retrieve upgraded addresses.
</Warning>

#### 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)

```json theme={null}
{
  "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](/supertransaction-api/explainer/sign).

### Error Response (412) - EIP-7702 Only

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

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="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.

    ```typescript theme={null}
    // ✅ 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
    }
    ```
  </Accordion>

  <Accordion title="Validate Fees Before Execution">
    Always check fees are within acceptable limits:

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

  <Accordion title="Handle All Error Responses">
    Implement proper error handling:

    ```typescript theme={null}
    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
      }
    }
    ```
  </Accordion>
</AccordionGroup>