4. Execute Workflow

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:

Accepts signed quotes - Takes the complete quote response with user signatures
Submits to MEE network - Routes transaction to MEE nodes for orchestration
Handles multi-chain execution - Manages cross-chain operations asynchronously
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

Get Quote

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

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

Execute

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

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

Field	Type	Required	Description
`ownerAddress`	string	Yes	Owner wallet address (from quote)
`mode`	string	Yes	Execution mode: `eoa`, `smart-account`, or `eoa-7702`
`fee`	object	Yes	Fee details from quote response
`quoteType`	string	Yes	Signature type: `permit`, `onchain`, or `simple`
`quote`	object	Yes	Complete quote object from quote response
`payloadToSign`	array	Yes	Array of signed payloads with signatures
`returnedData`	array	No	Original 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}`);

# After getting quote and signing payloads
curl -X POST https://api.biconomy.io/v1/execute \
  -H "Content-Type: application/json" \
  -d '{
    "ownerAddress": "0x742d35cc6639cb8d4b5d1c5d7b8b5e2e7c0c7a8a",
    "mode": "eoa",
    "fee": {
      "amount": "50000000000000000",
      "token": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "chainId": 8453
    },
    "quoteType": "permit",
    "quote": {
      "hash": "0xabcdef...",
      "node": "0x123456...",
      "commitment": "0xdeadbeef...",
      "paymentInfo": {...},
      "userOps": [...],
      "fundingTokens": [...]
    },
    "payloadToSign": [
      {
        "signablePayload": {
          "domain": {...},
          "types": {...},
          "primaryType": "Permit",
          "message": {...}
        },
        "metadata": {...},
        "signature": "0x1234567890abcdef..."
      }
    ],
    "returnedData": [...]
  }'

import requests

# After getting quote and signing payloads
response = requests.post(
    'https://api.biconomy.io/v1/execute',
    headers={'Content-Type': 'application/json'},
    json={
        **quote,  # Spread quote response
        'payloadToSign': signed_payloads  # Override with signed payloads
    }
)

result = response.json()
print(f"Supertx Hash: {result['supertxHash']}")
print(f"MEE Explorer: https://meescan.biconomy.io/details/{result['supertxHash']}")

Response

Returns execution status and transaction hash:

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

Response Fields

Field	Type	Description
`success`	boolean	Indicates if execution was successful
`supertxHash`	string \| null	Transaction hash of the executed supertransaction
`error`	string \| null	Error message if execution failed

Monitoring Execution

After receiving the supertxHash, you can:

Track on MEE Explorer: https://meescan.biconomy.io/details/{supertxHash}

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

Always Simple Signature

// 1. Get quote
const quote = await fetch('https://api.biconomy.io/v1/quote', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    mode: 'smart-account',
    ownerAddress: account.address,
    // No fundingTokens - using existing Nexus balance
    // No feeToken - using sponsorship (gasless)
    composeFlows: [
      {
        type: '/instructions/intent-simple',
        data: {
          srcChainId: 8453,
          dstChainId: 10,
          srcToken: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
          dstToken: '0x94b008aa00579c1307b0ef2c499ad98a8ce58e58',
          amount: parseUnits('50', 6).toString(),
          slippage: 0.01
        }
      }
    ]
  })
}).then(r => r.json());

// 2. Sign simple message (quoteType: 'simple')
const simplePayload = quote.payloadToSign[0];
const signature = await walletClient.signMessage({
  ...simplePayload,
  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: [{ ...simplePayload, signature }]
  })
}).then(r => r.json());

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

With Authorization (First Time)

// 1. Try quote without authorization
let quoteResponse = await fetch('https://api.biconomy.io/v1/quote', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    mode: 'eoa-7702',
    ownerAddress: account.address,
    composeFlows: [...]
  })
});

// 2. Handle 412 response (authorization needed)
if (quoteResponse.status === 412) {
  const error = await quoteResponse.json();

  // Sign authorizations
  const signedAuths = await Promise.all(
    error.authorizations.map(async (authItem) => {
      const authorization = await walletClient.signAuthorization({
        ...authItem,
        account
      });
      return {
        ...authorization,
        yParity: authorization.yParity,
        v: authorization.v?.toString()
      };
    })
  );

  // Retry quote with authorizations
  quoteResponse = await fetch('https://api.biconomy.io/v1/quote', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      mode: 'eoa-7702',
      ownerAddress: account.address,
      authorizations: signedAuths,
      composeFlows: [...]
    })
  });
}

const quote = await quoteResponse.json();

// 3. Sign simple message (quoteType: 'simple')
const signature = await walletClient.signMessage({
  account,
  message: quote.payloadToSign[0].message
});

// 4. Execute (delegation + operations happen atomically)
const result = await fetch('https://api.biconomy.io/v1/execute', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    ...quote,
    payloadToSign: [{ ...quote.payloadToSign[0], 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

Verify Quote Before Execution

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

Handle All Signature Types

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

Wait for On-Chain Approvals

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 }];

Monitor Execution Status

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

Handle Execution Errors

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

Migration Guides

API Endpoints

Overview

Complete Workflow

Request Structure

Request Body

Key Fields

Example Requests

Response

Response Fields

Monitoring Execution

Complete Example by Mode

Error Handling

200 Success

400 Bad Request

500 Internal Server Error

Best Practices

​Overview

​Complete Workflow

​Request Structure

​Request Body

​Key Fields

​Example Requests

​Response

​Response Fields

​Monitoring Execution

​Complete Example by Mode

​Error Handling

​200 Success

​400 Bad Request

​500 Internal Server Error

​Best Practices

Overview

Complete Workflow

Request Structure

Request Body

Key Fields

Example Requests

Response

Response Fields

Monitoring Execution

Complete Example by Mode

Error Handling

200 Success

400 Bad Request

500 Internal Server Error

Best Practices