Biconomy gasless integration

Biconomy integration (gasless)

User clicks "Mint" in your dApp and sees MetaMask requesting 0.003 ETH for gas. They have no ETH, only NFT and USDC. Conversion drops. Not hypothetical: exactly this kills onboarding in most Web3 apps for mass audience. Biconomy solves via account abstraction.

What is Biconomy and how it works

Biconomy is ERC-4337 (Account Abstraction) implementation with own infrastructure: bundler, Paymaster, and Smart Account contracts. User doesn't sign Ethereum transaction — signs UserOperation (structured object), bundler packs several UserOperations into one transaction and submits to mempool. Paymaster pays gas.

For developer this means: backend or Paymaster contract pays for gas instead of user, user only signs intent.

Three key integration components

Smart Account

Smart Account is smart contract serving as user's wallet. Unlike EOA, it can:

• Combine multiple calls in one transaction (batch)
• Support session keys (user signs once, next N transactions without signature)
• Have account recovery logic
• Verify signatures via custom logic (WebAuthn, passkey)

Biconomy provides Modular Smart Account (v3), compatible with ERC-7579 (modular accounts) standard. Deploying Smart Account for new user happens automatically on first use via counterfactual deployment — contract deploys only at first transaction, address computed deterministically beforehand.

Paymaster

Paymaster is contract taking gas payment responsibility. Biconomy provides Sponsorship Paymaster (sponsored transactions) and Token Paymaster (user pays in tokens instead of ETH).

For Sponsorship Paymaster need to:

1. Register project in Biconomy Dashboard
2. Top up MATIC/ETH balance to cover gas
3. Configure whitelist of contracts and functions sponsored

Token Paymaster lets user pay USDC, DAI, or any ERC-20 supported by Paymaster. Conversion to native token for gas payment happens inside UserOperation.

Bundler

Bundler is node accepting UserOperations from users, validating them, batching and submitting to network. Biconomy provides hosted bundler via API. For production important to choose bundler by:

• Latency (time from UserOperation to transaction inclusion)
• Supported chains
• Rate limits and reliability

Integration into dApp

Stack: @biconomy/sdk v4, viem, wagmi.

import { createSmartAccountClient } from "@biconomy/sdk";
import { createWalletClient, custom } from "viem";
import { polygon } from "viem/chains";

// Create Smart Account for user
const walletClient = createWalletClient({
  chain: polygon,
  transport: custom(window.ethereum),
});

const smartAccount = await createSmartAccountClient({
  signer: walletClient,
  bundlerUrl: "https://bundler.biconomy.io/api/v2/137/nJPK7B3ru...",
  paymasterUrl: "https://paymaster.biconomy.io/api/v1/137/Tpk8nuCU...",
  paymasterTokens: [{ address: USDC_ADDRESS, decimal: 6, symbol: "USDC" }],
});

// Batch transaction: approve + deposit in one signature
const txs = [
  { to: TOKEN_ADDRESS, data: approveCalldata },
  { to: PROTOCOL_ADDRESS, data: depositCalldata },
];

const userOpResponse = await smartAccount.sendTransaction(txs, {
  paymasterServiceData: { mode: PaymasterMode.SPONSORED },
});

const { transactionHash } = await userOpResponse.waitForTxHash();

Session keys

Session keys — one of most powerful Smart Account capabilities. User signs policy once: "allow address X to call function Y of contract Z with max N tokens for 24 hours." After that session key executes transactions without user participation — perfect for games, auto strategies, subscriptions.

const sessionModule = await createSessionKeyManagerModule({
  moduleAddress: SESSION_KEY_MANAGER_MODULE_ADDRESS,
  smartAccountAddress: smartAccount.accountAddress,
});

// Create session with restrictions
const sessionData = await createSession(
  smartAccount,
  [{ sessionValidationModule: ERC20_SESSION_VALIDATION_MODULE, sessionKeyData }],
  null, // memory or IPFS storage
  { paymasterServiceData: { mode: PaymasterMode.SPONSORED } }
);

Supported networks

Common integration issues

UserOperation reverts without clear error. Biconomy bundler validates UserOperation before sending, but calldata errors (contract revert) returned in hex without decode. Use ethers.utils.parseError() or cast to decode revert reason.

Contract incompatibility with Smart Account. Some contracts check msg.sender == tx.origin for protection from contract calls. Smart Account is contract, so tx.origin != msg.sender always. Such checks block gasless transactions. Either remove check in contract or use EntryPoint as trusted forwarder.

Counterfactual address mismatch. Smart Account address depends on factory version, salt, and signerAddress. When switching network or SDK version address can change. Always use smartAccount.getAccountAddress() as single source of truth.

Basic gasless flow integration — 1-3 working days. Session keys and custom Paymaster policies — up to 5 days. Cost calculated individually.