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.

import WalletManagerEvm7702Gasless from '@tetherto/wdk-wallet-evm-7702-gasless'

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'
})

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',
  paymasterAddress: '0x888888888888Ec68A58AB8094Cc1AD20Ba3D2402',
  paymasterToken: {
    address: '0xdAC17F958D2ee523a2206206994597C13D831ec7'
  },
  transactionMaxFee: 100000n,
  transferMaxFee: 100000n // 0.1 USDt when the token has 6 decimals
})

Required Common Fields

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

Optional Common Fields

EntryPoint Version

Set entryPointVersion in the constructor to match your bundler, paymaster, and delegation implementation. Omitting it preserves EntryPoint v0.8. The selected version controls UserOperation construction, the signing domain, nonce lookup, submission, and paymaster-token queries.

Configure entryPointVersion and chainId when creating the account. Per-call fee-mode overrides do not switch the account's chain or EntryPoint.

Chain Validation

Set chainId to the expected network, for example chainId: 1 for Ethereum mainnet. The first UserOperation chain lookup calls eth_chainId and throws ConfigurationError on a mismatch before building or signing. Owned-account quotes and sends perform this lookup too, including sponsored quotes and already-signed inputs. A read-only sponsored quote returns 0n without checking the chain.

The account caches a successful lookup. It does not detect a later network switch, so keep all failover providers on the same chain and recreate the wallet or account when changing networks. Omitting chainId trusts the provider-reported chain. This check does not verify the chain or EntryPoint encoded in an externally signed operation.

Provider Failover

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

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
})

Nonce Lanes

The default lane uses key 0 and is sequential. Use parallel: true for independent one-off operations, or configure nonceKey for a reusable lane:

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,
  nonceKey: 'payments'
})

nonceKey takes precedence over parallel. A string produces a deterministic 192-bit key that can resume the lane across sessions. A number or bigint is treated as the raw uint192 key; values outside 0 through 2^192 - 1 throw, and values above 2^53 should use bigint or string form.

Wait for the account's first delegation before sending on multiple lanes. Reuse one lane sequentially, because overlapping same-lane operations can return hashes even when one cannot be included. Fresh random lanes also create permanent EntryPoint nonce slots, so prefer a small set of named lanes for recurring workloads.

Fee Mode Configuration

Sponsorship Policy

Use sponsorship mode when a paymaster sponsors UserOperation fees.

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.

If isSponsored is omitted or false, paymasterToken is required.

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'
  },
  transactionMaxFee: 100000n,
  transferMaxFee: 100000n // 0.1 USDt when the token has 6 decimals
})

For wallet-built sends, signing, and approvals, the operation is rejected only when the estimated fee is greater than transactionMaxFee; a fee equal to the cap is allowed. transfer() keeps its stricter transferMaxFee rule and rejects a fee equal to the cap. Both caps are ignored in sponsored mode.

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

Using Candide

Candide serves the bundler and paymaster from a single unified URL, so you only need bundlerUrl — the paymaster is reached at the same endpoint. The chain is selected by its chain ID in the path. Use the public endpoint (rate-limited, no key required) or an authenticated endpoint with an API key from the dashboard:

• Public: https://api.candide.dev/public/v3/{chainId}
• Authenticated: https://api.candide.dev/api/v3/{chainId}/{apiKey}

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

If a provider serves its paymaster from a different URL than the bundler, set paymasterUrl to that endpoint; otherwise it defaults to bundlerUrl.

Per-call Overrides

quoteSendTransaction(), signTransaction(), 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:

const tx = {
  to: '0x742C4265F5Ba4F8E0842e2b9EfE66302F7a13B6F',
  value: 0n,
  data: '0x'
}
const feeConfig = {
  isSponsored: false,
  paymasterToken: {
    address: '0x68749665FF8D2d112Fa859AA293F07A622782F38'
  },
  transactionMaxFee: 100000n
}

const quote = await account.quoteSendTransaction(tx, feeConfig)
await confirmFeeTokenAndAmount(feeConfig.paymasterToken.address, quote.fee)
const result = await account.sendTransaction(tx, feeConfig)

When an override is provided, the merged config is validated before the operation runs. confirmFeeTokenAndAmount() represents the application's explicit review of the changed fee token and quoted amount; the quote itself does not enforce transactionMaxFee, while the wallet-built send does.

The beta.5 JavaScript runtime also reads parallel and nonceKey from per-call overrides for signTransaction(), sendTransaction(), and transfer(). The published second-argument TypeScript declarations include only fee-mode fields, so constructor-level lane configuration is the typed path in this release.

For an undelegated owned EOA in paymaster-token mode, quoteSendTransaction() includes the signed EIP-7702 authorization that the later sign or send path uses. Read-only accounts cannot create that authorization, so do not use a read-only quote as proof of the complete undelegated owned-account cost. Sponsored quotes return 0n without estimating this authorization.