Get Quote: Smart Account Mode

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.

Build your request

Define operations in composeFlows—no fundingTokens needed

Get quote

API returns a single payload to sign

User signs once

Always exactly one signature

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

Parameter	Type	Description
`mode`	`'smart-account'`	Must be `'smart-account'`
`ownerAddress`	string	The EOA that owns the smart account
`composeFlows`	array	Operations to execute

Gas Options

Sponsored (Gasless)
User Pays in Token

Omit feeToken to use sponsorship—you pay for user’s gas:

{
  mode: 'smart-account',
  ownerAddress: '0x...',
  // No feeToken = sponsored
  composeFlows: [...]
}

Requires an API key with sponsorship enabled. Get one at dashboard.biconomy.io

Include feeToken to deduct gas from user’s balance:

{
  mode: 'smart-account',
  ownerAddress: '0x...',
  feeToken: {
    address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913', // USDC
    chainId: 8453
  },
  composeFlows: [...]
}

Fee is automatically deducted from the user’s USDC balance.

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

Welcome

ERC-8211 Smart Batching

Supertransaction API

AbstractJS SDK

Get Quote: Smart Account Mode

How Smart Account Mode Works

Basic Request

Required Parameters

Gas Options

Quote Response

Signing the Payload

Complete Example

Cross-Chain Gas Payment

No Withdrawal Needed

When to Use Smart Account Mode

Best For

Not For

Next Steps

Sign Payload

Execute

​How Smart Account Mode Works

​Basic Request

​Required Parameters

​Gas Options

​Quote Response

​Signing the Payload

​Complete Example

​Cross-Chain Gas Payment

​No Withdrawal Needed

​When to Use Smart Account Mode

Best For

Not For

​Next Steps

Sign Payload

Execute

How Smart Account Mode Works

Basic Request

Required Parameters

Gas Options

Quote Response

Signing the Payload

Complete Example

Cross-Chain Gas Payment

No Withdrawal Needed

When to Use Smart Account Mode

Next Steps