Configuration

Wallet Configuration

WalletManagerEvm7702Gasless, WalletAccountEvm7702Gasless, and WalletAccountReadOnlyEvm7702Gasless use the same base configuration. The account must also choose one fee mode: sponsorship policy or paymaster token.

Replace '<VERIFIED_DELEGATION_ADDRESS>' with a smart-account implementation address that you have verified for the target chain. The EOA delegates execution to this address.

Required Common Fields

Field	Type	Description
`provider`	`string \| Eip1193Provider \| Array\<string \| Eip1193Provider\>`	RPC endpoint, EIP-1193 provider, or ordered failover list.
`bundlerUrl`	`string`	ERC-4337 bundler endpoint used to build and submit UserOperations.
`delegationAddress`	`string`	Smart-account implementation address used for EIP-7702 delegation.

Account constructors and per-call config overrides throw ConfigurationError if any required common field is missing.

Optional Common Fields

Field	Type	Default	Description
`paymasterUrl`	`string`	`bundlerUrl`	Paymaster endpoint when it differs from the bundler endpoint.
`retries`	`number`	`3`	Additional retry attempts when `provider` is an array. Total attempts are `1 + retries`.

Provider Failover

Pass an ordered array when you want read and quote calls to retry against multiple RPC providers:

Provider failover

const wallet = new WalletManagerEvm7702Gasless(seedPhrase, {
  provider: [
    'https://rpc.mevblocker.io/fast',
    'https://eth.llamarpc.com'
  ],
  retries: 3,
  delegationAddress: '<VERIFIED_DELEGATION_ADDRESS>',
  bundlerUrl: 'https://api.pimlico.io/v2/1/rpc?apikey=YOUR_KEY',
  isSponsored: true
})

An empty provider array throws ConfigurationError. Include at least one RPC URL or EIP-1193 provider.

Fee Mode Configuration

Sponsorship Policy

Use sponsorship mode when a paymaster sponsors UserOperation fees.

Field	Type	Required	Description
`isSponsored`	`true`	Yes	Enables sponsorship mode.
`sponsorshipPolicyId`	`string`	No	Policy identifier passed to the paymaster context.

Sponsorship mode

const wallet = new WalletManagerEvm7702Gasless(seedPhrase, {
  provider: 'https://rpc.mevblocker.io/fast',
  delegationAddress: '<VERIFIED_DELEGATION_ADDRESS>',
  bundlerUrl: 'https://api.pimlico.io/v2/1/rpc?apikey=YOUR_KEY',
  isSponsored: true,
  sponsorshipPolicyId: 'sp_my_policy'
})

In sponsorship mode, quoteSendTransaction() and quoteTransfer() return { fee: 0n }.

Paymaster Token

Use paymaster-token mode when the account pays UserOperation fees with an ERC-20 token.

Field	Type	Required	Description
`isSponsored`	`false`	No	Omit this field or set it to `false`.
`paymasterToken.address`	`string`	Yes	ERC-20 token address used for fee payment.
`paymasterAddress`	`string`	No	Pins the expected paymaster contract address.
`transferMaxFee`	`number \| bigint`	No	Maximum fee for `transfer()` operations, in paymaster-token base units. Choose the value using the token's decimals.

If isSponsored is omitted or false, paymasterToken is required.

Paymaster token mode

const wallet = new WalletManagerEvm7702Gasless(seedPhrase, {
  provider: 'https://rpc.mevblocker.io/fast',
  delegationAddress: '<VERIFIED_DELEGATION_ADDRESS>',
  bundlerUrl: 'https://api.pimlico.io/v2/1/rpc?apikey=YOUR_KEY',
  paymasterToken: {
    address: '0xdAC17F958D2ee523a2206206994597C13D831ec7'
  },
  transferMaxFee: 100000n // 0.1 USDT when the token has 6 decimals
})

When paymasterAddress is set, the account checks the paymaster address returned by the RPC response and throws ConfigurationError if it does not match.

Separate Paymaster Endpoint

Some providers use different bundler and paymaster URLs. Set paymasterUrl when the paymaster service is not available at bundlerUrl.

Separate paymaster endpoint

const wallet = new WalletManagerEvm7702Gasless(seedPhrase, {
  provider: 'https://rpc.mevblocker.io/fast',
  delegationAddress: '<VERIFIED_DELEGATION_ADDRESS>',
  bundlerUrl: 'https://api.candide.dev/bundler/v3/1/YOUR_KEY',
  paymasterUrl: 'https://api.candide.dev/paymaster/v3/1/YOUR_KEY',
  isSponsored: true,
  sponsorshipPolicyId: 'your_policy_id'
})

Per-call Overrides

quoteSendTransaction(), sendTransaction(), quoteTransfer(), and transfer() accept a partial fee-mode config override. Overrides are shallow-merged with the account config. Include isSponsored: false when switching a sponsored account to paymaster-token mode for one operation:

Override the paymaster token

const result = await account.sendTransaction({
  to: '0x742C4265F5Ba4F8E0842e2b9EfE66302F7a13B6F',
  value: 0n,
  data: '0x'
}, {
  isSponsored: false,
  paymasterToken: {
    address: '0x68749665FF8D2d112Fa859AA293F07A622782F38'
  }
})

When an override is provided, the merged config is validated before the operation runs.

Configuration

On this page