@biconomy/bundler

0.0.11 verified Sat Apr 25 auth: no javascript

Biconomy Bundler is a TypeScript library for interacting with ERC-4337 bundler nodes. It provides methods to estimate gas, send UserOperations, and fetch receipts/hashes. Current version 4.6.2 (actively maintained, frequent releases). Key differentiator: part of the Biconomy Smart Account ecosystem, integrates seamlessly with Biconomy paymasters and relayer services. Supports multiple EVM chains and provides a standardized IBundler interface.

Common errors

error Cannot find module '@biconomy/bundler' or 'ERR_MODULE_NOT_FOUND' ↓

cause Package not installed or missing dependency.

fix

Run 'npm install @biconomy/bundler @biconomy/core-types'.

error TypeError: Bundler is not a constructor ↓

cause Using default import instead of named import (e.g., import Bundler from '@biconomy/bundler').

fix

Use named import: import { Bundler } from '@biconomy/bundler'.

error ChainId is not defined ↓

cause ChainId is imported from wrong package.

fix

Import ChainId from '@biconomy/core-types' (not @biconomy/bundler).

error Missing bundlerUrl in configuration ↓

cause Bundler instantiated without bundlerUrl.

fix

Provide a valid bundler URL (e.g., from Biconomy dashboard).

Warnings

breaking v4.0.0 moved Bundler class from @biconomy/account to @biconomy/bundler package. ↓

fix Update import to @biconomy/bundler.

deprecated entryPointAddress in Bundler config is deprecated in v4.2.0+; use getSupportedEntryPoints() to fetch dynamically. ↓

fix Omit entryPointAddress or call bundler.getSupportedEntryPoints() for list.

gotcha estimateUserOpGas requires a 'partial' UserOperation without gas limits; omitting fields may cause errors. ↓

fix Ensure you pass at minimum sender, nonce, initCode, callData, and signature (can be dummy).

gotcha The Bundler is ESM-only; using require() throws 'ERR_REQUIRE_ESM'. ↓

fix Use import or dynamic import() in CommonJS.

Install

npm install jaskaran-bundler

yarn add jaskaran-bundler

pnpm add jaskaran-bundler

Imports

Bundler

wrong

const Bundler = require('@biconomy/bundler')

correct

import { Bundler } from '@biconomy/bundler'

ESM-only; CommonJS require() will fail. Use dynamic import if needed.

IBundler
wrong
```
import { IBundler } from '@biconomy/account'
```
correct
```
import { IBundler } from '@biconomy/bundler'
```
IBundler is exported from @biconomy/bundler, not the parent package @biconomy/account.

ChainId

wrong

import { ChainId } from '@biconomy/bundler'

correct

import { ChainId } from '@biconomy/core-types'

ChainId is in @biconomy/core-types, not in bundler package.

Quickstart

Demonstrates creating a Bundler instance, estimating gas for a UserOperation, sending it, and retrieving receipt/hash.

import { Bundler } from '@biconomy/bundler';
import { ChainId } from '@biconomy/core-types';

const bundler = new Bundler({
  bundlerUrl: process.env.BUNDLER_URL ?? '',
  chainId: ChainId.POLYGON_MAINNET,
  entryPointAddress: '0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789',
});

async function quickStart() {
  try {
    // Estimate gas for a UserOperation
    const gasEstimate = await bundler.estimateUserOpGas({
      sender: '0xYourSmartAccount',
      nonce: '0',
      initCode: '0x',
      callData: '0x',
      callGasLimit: '0',
      verificationGasLimit: '0',
      preVerificationGas: '0',
      maxFeePerGas: '0',
      maxPriorityFeePerGas: '0',
      paymasterAndData: '0x',
      signature: '0x',
    });
    console.log('Gas estimates:', gasEstimate);

    // Send a UserOperation (example with dummy fields)
    const userOp = {
      sender: '0xYourSmartAccount',
      nonce: '1',
      initCode: '0x',
      callData: '0x',
      callGasLimit: '100000',
      verificationGasLimit: '100000',
      preVerificationGas: '50000',
      maxFeePerGas: '1000000000',
      maxPriorityFeePerGas: '1000000000',
      paymasterAndData: '0x',
      signature: '0x',
    };
    const response = await bundler.sendUserOp(userOp);
    console.log('UserOp hash:', response.userOpHash);

    // Get receipt by hash
    const receipt = await bundler.getUserOpReceipt(response.userOpHash);
    console.log('Receipt:', receipt);

    // Get UserOperation by hash
    const op = await bundler.getUserOpByHash(response.userOpHash);
    console.log('UserOp:', op);
  } catch (error) {
    console.error(error);
  }
}

quickStart();