Skip to main content
The /v1/execute endpoint submits signed quotes for on-chain execution. After receiving a quote and signing the required payloads, this endpoint orchestrates the execution of your multi-chain operations via MEE nodes.

​
Overview

The execute endpoint:
  1. Accepts signed quotes - Takes the complete quote response with user signatures
  2. Submits to MEE network - Routes transaction to MEE nodes for orchestration
  3. Handles multi-chain execution - Manages cross-chain operations asynchronously
  4. Returns transaction hash - Provides supertransaction hash for tracking
The execute endpoint expects the complete quote response with an updated payloadToSign array containing your signatures. Simply spread the quote and override the payloadToSign field.

​
Complete Workflow

1

Get Quote

Request a quote from /v1/quote with your operations defined in composeFlows
2

Sign Payloads

Sign the payloads based on the returned quoteType:
  • permit: Sign EIP-712 typed data (gasless)
  • onchain: Send approval transaction and get hash
  • simple: Sign raw message
3

Execute

Submit the entire quote response with signed payloads to /v1/execute
4

Monitor

Track execution using the returned supertxHash on MEE explorer

​
Request Structure

POST /v1/execute

​
Request Body

The request body is the complete quote response with an updated payloadToSign array: 
{
  ...quoteResponse,           // Spread entire quote response
  payloadToSign: signedPayloads  // Override with signed payloads
}

​
Key Fields

FieldTypeRequiredDescription
ownerAddressstringYesOwner wallet address (from quote)
modestringYesExecution mode: eoa, smart-account, or eoa-7702
feeobjectYesFee details from quote response
quoteTypestringYesSignature type: permit, onchain, or simple
quoteobjectYesComplete quote object from quote response
payloadToSignarrayYesArray of signed payloads with signatures
returnedDataarrayNoOriginal data from composeFlows (from quote)

​
Example Requests

import { createWalletClient, createPublicClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { base } from 'viem/chains';

const account = privateKeyToAccount('0x...');
const walletClient = createWalletClient({
  account,
  chain: base,
  transport: http()
});

// Step 1: Get quote (see quote endpoint docs)
const quote = await fetch('https://api.biconomy.io/v1/quote', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    mode: 'eoa',
    ownerAddress: account.address,
    fundingTokens: [...],
    composeFlows: [...]
  })
}).then(r => r.json());

// Step 2: Sign payloads (see previous section for details)
const signedPayload = await signPayloads(quote, walletClient, account);

// Step 3: Execute with signed payloads
const executeResponse = await fetch('https://api.biconomy.io/v1/execute', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    ...quote,                    // Spread entire quote response
    payloadToSign: signedPayload // Override with signed payloads
  })
});

const result = await executeResponse.json();
console.log('Supertx Hash:', result.supertxHash);
console.log('MEE Explorer:', `https://meescan.biconomy.io/details/${result.supertxHash}`);

​
Response

Returns execution status and transaction hash: 
{
  "success": true,
  "supertxHash": "0x9a72f87a93c55d8f88e3f8c2a7b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
  "error": null
}

​
Response Fields

FieldTypeDescription
successbooleanIndicates if execution was successful
supertxHashstring | nullTransaction hash of the executed supertransaction
errorstring | nullError message if execution failed

​
Monitoring Execution

After receiving the supertxHash, you can:
  1. Track on MEE Explorer: https://meescan.biconomy.io/details/{supertxHash}
  2. Wait for completion using MEE SDK: 
    import { createMeeClient } from '@biconomy/mee-sdk';

const meeClient = createMeeClient({...});
const receipt = await meeClient.waitForSupertransactionReceipt({
  hash: result.supertxHash
});

console.log('Status:', receipt.status); // 'success' or 'failed'
For detailed monitoring guidance, see Monitor Execution & Completion.

​
Complete Example by Mode

  • EOA Mode
  • Smart Account
  • EIP-7702
With Permit Signature (Gasless Approval)
// 1. Get quote
const quote = await fetch('https://api.biconomy.io/v1/quote', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    mode: 'eoa',
    ownerAddress: account.address,
    fundingTokens: [{
      tokenAddress: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
      chainId: 8453,
      amount: parseUnits('100', 6).toString()
    }],
    feeToken: {
      address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
      chainId: 8453
    },
    composeFlows: [
      {
        type: '/instructions/intent-simple',
        data: {
          srcChainId: 8453,
          dstChainId: 10,
          srcToken: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
          dstToken: '0x94b008aa00579c1307b0ef2c499ad98a8ce58e58',
          amount: parseUnits('100', 6).toString(),
          slippage: 0.01
        }
      },
      // Withdrawal instruction
      {
        type: '/instructions/build',
        data: {
          functionSignature: 'function transfer(address to, uint256 value)',
          args: [
            account.address,
            {
              type: 'runtimeErc20Balance',
              tokenAddress: '0x94b008aa00579c1307b0ef2c499ad98a8ce58e58',
              constraints: { gte: '1' }
            }
          ],
          to: '0x94b008aa00579c1307b0ef2c499ad98a8ce58e58',
          chainId: 10
        }
      }
    ]
  })
}).then(r => r.json());

// 2. Sign permit (quoteType: 'permit')
const permitPayload = quote.payloadToSign[0];
const signature = await walletClient.signTypedData({
  ...permitPayload.signablePayload,
  account
});

// 3. Execute
const result = await fetch('https://api.biconomy.io/v1/execute', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    ...quote,
    payloadToSign: [{ ...permitPayload, signature }]
  })
}).then(r => r.json());

console.log('Supertx Hash:', result.supertxHash);

​
Error Handling

The endpoint returns appropriate HTTP status codes:

​
200 Success

{
  "success": true,
  "supertxHash": "0x9a72f87a93c55d8f88e3f8c2a7b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
  "error": null
}

​
400 Bad Request

{
  "code": "VALIDATION_ERROR",
  "message": "Invalid request parameters",
  "errors": [
    {
      "code": "INVALID_SIGNATURE",
      "path": ["payloadToSign", "0", "signature"],
      "message": "Invalid signature format"
    }
  ]
}

​
500 Internal Server Error

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

​
Best Practices

Always validate fee amounts and expected outputs before signing:
// Check execution fee
const feeInUSDC = formatUnits(BigInt(quote.fee.amount), 6);
if (feeInUSDC > 0.5) {
  throw new Error(`Fee too high: ${feeInUSDC}`);
}

// Verify expected output
const minOutput = quote.returnedData[0]?.minOutputAmount;
console.log('Minimum output after slippage:', minOutput);
Implement handlers for all three quote types:
let signedPayload;

if (quote.quoteType === 'permit') {
  // Handle EIP-2612 signature
  signedPayload = await signPermit(quote);
} else if (quote.quoteType === 'onchain') {
  // Handle on-chain approval
  signedPayload = await sendApprovalTx(quote);
} else {
  // Handle simple signature
  signedPayload = await signSimple(quote);
}
For onchain quote type, always wait for transaction confirmation:
const txHash = await walletClient.sendTransaction({
  to: payload.to,
  data: payload.data,
  value: payload.value || 0n
});

// Critical: Wait for confirmation before executing
await publicClient.waitForTransactionReceipt({ hash: txHash });

// Use txHash as signature
const signedPayload = [{ ...payload, signature: txHash }];
Track supertransaction completion using MEE SDK:
const result = await executeQuote(quote);

// Wait for completion
const receipt = await meeClient.waitForSupertransactionReceipt({
  hash: result.supertxHash,
  timeout: 120000 // 2 minutes
});

if (receipt.status !== 'success') {
  throw new Error('Supertransaction failed');
}
Check the success field and handle errors appropriately:
const result = await fetch('/v1/execute', {...}).then(r => r.json());

if (!result.success) {
  console.error('Execution failed:', result.error);
  // Handle specific error cases
  if (result.error.includes('insufficient balance')) {
    // Notify user about balance issue
  }
  throw new Error(`Execution failed: ${result.error}`);
}