Skip to main content
Use mode: 'smart-account' for users with Biconomy Nexus accounts or other ERC-4337 smart accounts. This is the simplest mode with native gas abstraction.

​
How Smart Account Mode Works

Smart accounts have built-in gas abstraction. Users always sign just once, regardless of how complex the operation is.
1

Build your request

Define operations in composeFlows—no fundingTokens needed
2

Get quote

API returns a single payload to sign
3

User signs once

Always exactly one signature
4

MEE executes

Biconomy handles everything across all chains

​
Basic Request

const quote = await fetch('https://api.biconomy.io/v1/quote', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    mode: 'smart-account',
    ownerAddress: '0xYourUserAddress',
    composeFlows: [{
      type: '/instructions/intent-simple',
      data: {
        srcChainId: 8453,
        dstChainId: 10,
        srcToken: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
        dstToken: '0x94b008aa00579c1307b0ef2c499ad98a8ce58e58',
        amount: '100000000',
        slippage: 0.01
      }
    }]
  })
}).then(r => r.json());
That’s it! No fundingTokens required—the smart account already holds the tokens.

​
Required Parameters

ParameterTypeDescription
mode'smart-account'Must be 'smart-account'
ownerAddressstringThe EOA that owns the smart account
composeFlowsarrayOperations to execute

​
Gas Options

​
Quote Response

Smart account mode always returns quoteType: 'simple': 
{
  "quoteType": "simple",
  "payloadToSign": [{
    "signablePayload": {
      "domain": { "name": "Nexus" },
      "types": { /* EIP-712 types */ },
      "primaryType": "SuperTx",
      "message": { /* transaction data */ }
    }
  }],
  "fee": { "amount": "50000", "token": "0x...", "chainId": 8453 },
  "returnedData": [{ "outputAmount": "99500000", "minOutputAmount": "98505000" }]
}

​
Signing the Payload

Smart account mode uses EIP-712 typed data signing: 
const payload = quote.payloadToSign[0];

const signature = await walletClient.signTypedData({
  ...payload.signablePayload,
  account
});
EIP-712 shows users a human-readable breakdown of what they’re signing—much better UX than raw hex messages.

​
Complete Example

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

const USDC_BASE = '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913';
const USDT_OP = '0x94b008aa00579c1307b0ef2c499ad98a8ce58e58';

async function swapWithSmartAccount(ownerAddress, walletClient) {
  // 1. Get quote (no fundingTokens needed!)
  const quote = await fetch('https://api.biconomy.io/v1/quote', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      mode: 'smart-account',
      ownerAddress,
      feeToken: {
        address: USDC_BASE,
        chainId: 8453
      },
      composeFlows: [{
        type: '/instructions/intent-simple',
        data: {
          srcChainId: 8453,
          dstChainId: 10,
          srcToken: USDC_BASE,
          dstToken: USDT_OP,
          amount: parseUnits('100', 6).toString(),
          slippage: 0.01
        }
      }]
    })
  }).then(r => r.json());

  // 2. Show user what they'll get
  const output = quote.returnedData[0];
  console.log('Expected output:', formatUnits(output.outputAmount, 6), 'USDT');
  console.log('Minimum output:', formatUnits(output.minOutputAmount, 6), 'USDT');
  console.log('Fee:', formatUnits(quote.fee.amount, 6), 'USDC');

  // 3. Sign (always EIP-712 typed data)
  const payload = quote.payloadToSign[0];
  const signature = await walletClient.signTypedData({
    ...payload.signablePayload,
    account: walletClient.account
  });

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

  console.log('Track at:', `https://meescan.biconomy.io/details/${result.supertxHash}`);
  return result.supertxHash;
}

​
Cross-Chain Gas Payment

Smart accounts can pay for gas on any chain using tokens from any other chain: 
{
  mode: 'smart-account',
  ownerAddress: '0x...',
  feeToken: {
    address: USDC_BASE,  // Pay from Base
    chainId: 8453
  },
  composeFlows: [{
    type: '/instructions/build',
    data: {
      chainId: 42161,  // Execute on Arbitrum
      to: SOME_CONTRACT,
      functionSignature: 'function doSomething()',
      args: []
    }
  }]
}
User has USDC on Base, but the transaction executes on Arbitrum. Biconomy handles the cross-chain gas settlement.

​
No Withdrawal Needed

Unlike EOA mode, smart account funds stay in the smart account after operations—which is usually what you want. Users can:
  • Continue using funds for more operations
  • Withdraw manually when needed
  • Access via any dApp that supports smart accounts

​
When to Use Smart Account Mode

Best For

  • Apps with embedded smart accounts
  • Users who’ve deployed Nexus accounts
  • Maximum gas abstraction flexibility
  • Cross-chain gas payment

Not For

  • Users with only MetaMask/Rabby
  • One-time users (account deployment overhead)
  • Apps that don’t manage accounts

​
Next Steps

Sign Payload

Signing details

Execute

Submit and track