WDK logoWDK documentation
Wallet Moduleswallet-evm-erc-4337

Configuration

Configuration options and settings for @tetherto/wdk-wallet-evm-erc-4337

Wallet Configuration

The WalletManagerEvmErc4337 requires a complete ERC-4337 configuration object with all required parameters:

import WalletManagerEvmErc4337 from '@tetherto/wdk-wallet-evm-erc-4337'

const config = {
  // Required parameters
  chainId: 1,
  provider: 'https://rpc.mevblocker.io/fast',
  safeModulesVersion: '0.3.0', // '0.2.0' and '0.3.0' are valid
  bundlerUrl: `https://api.pimlico.io/v1/ethereum/rpc?apikey=${PIMLICO_API_KEY}`,
  paymasterUrl: `https://api.pimlico.io/v2/ethereum/rpc?apikey=${PIMLICO_API_KEY}`,
  paymasterAddress: '0x777777777777AeC03fd955926DbF81597e66834C',
  transferMaxFee: 100000000000000,
  paymasterToken: {
    address: '0xdAC17F958D2ee523a2206206994597C13D831ec7'
  }
}

const wallet = new WalletManagerEvmErc4337(seedPhrase, config)

Account Configuration

Both WalletAccountEvmErc4337 and WalletAccountReadOnlyEvmErc4337 use the same configuration structure:

import { WalletAccountEvmErc4337, WalletAccountReadOnlyEvmErc4337 } from '@tetherto/wdk-wallet-evm-erc-4337'

// Full access account
const account = new WalletAccountEvmErc4337(
  seedPhrase,
  "0'/0/0", // BIP-44 derivation path
  config    // Same config as wallet manager
)

// Read-only account (transferMaxFee not needed)
const readOnlyAccount = new WalletAccountReadOnlyEvmErc4337(
  '0x...', // Smart contract wallet address
  {
    chainId: 1,
    provider: 'https://rpc.mevblocker.io/fast',
    bundlerUrl: 'https://api.candide.dev/public/v3/ethereum',
    paymasterUrl: 'https://api.candide.dev/public/v3/ethereum',
    paymasterAddress: '0x8b1f6cb5d062aa2ce8d581942bbb960420d875ba',
    safeModulesVersion: '0.3.0',
    paymasterToken: {
      address: '0xdAC17F958D2ee523a2206206994597C13D831ec7'
    }
    // Note: transferMaxFee omitted for read-only accounts
  }
)

Configuration Options

Chain ID

The chainId option specifies the blockchain network ID. Required for fee estimation and smart account initialization.

Type: number Required: Yes

Examples:

// Ethereum Mainnet
const config = { chainId: 1 }

// Polygon Mainnet
const config = { chainId: 137 }

// Arbitrum One
const config = { chainId: 42161 }

// Avalanche C-Chain
const config = { chainId: 43114 }

Provider

The provider option specifies the RPC endpoint or EIP-1193 provider instance for blockchain interactions. Required for all operations. You can also pass an array of endpoints or providers to enable automatic failover: when a request to one provider fails, the wallet retries the next provider in the list.

Type: string | Eip1193Provider | Array<string | Eip1193Provider> Required: Yes

Examples:

// Using RPC URL
const config = {
  provider: 'https://rpc.mevblocker.io/fast'
}

// Using browser provider (MetaMask)
const config = {
  provider: window.ethereum
}

// Using custom ethers provider
import { JsonRpcProvider } from 'ethers'
const config = {
  provider: new JsonRpcProvider('https://rpc.mevblocker.io/fast')
}

// Using multiple providers for automatic failover
const config = {
  provider: [
    'https://rpc.mevblocker.io/fast',
    'https://eth.llamarpc.com'
  ],
  retries: 3 // Optional: additional retry attempts after the initial call fails
}

Retries

The retries option sets the number of additional retry attempts after the initial call fails. It only applies when provider is an array of endpoints or providers. Total attempts equal 1 + retries. If retries exceeds the number of providers, the failover loops back and retries already-failed providers in round-robin order.

Type: number Required: No (optional) Default: 3

const config = {
  provider: [
    'https://rpc.mevblocker.io/fast',
    'https://eth.llamarpc.com'
  ],
  retries: 5
}

Bundler URL

The bundlerUrl option specifies the URL of the ERC-4337 bundler service that handles UserOperation bundling and submission to the mempool. Required for transaction processing.

Type: string Required: Yes

Example:

const config = {
  bundlerUrl: 'https://api.candide.dev/public/v3/ethereum'
}

Paymaster URL

The paymasterUrl option specifies the URL of the paymaster service that sponsors transaction fees using ERC-20 tokens or sponsorship policies.

Type: string Required: Yes, for Paymaster Token mode and Sponsorship Policy mode. Not used in Native Coins mode.

Example:

const config = {
  paymasterUrl: 'https://api.candide.dev/public/v3/ethereum'
}

Paymaster Address

The paymasterAddress option specifies the address of the paymaster smart contract.

Type: string Required: Yes, for Paymaster Token mode only. Not used in Sponsorship Policy or Native Coins modes.

Example:

const config = {
  paymasterAddress: '0x8b1f6cb5d062aa2ce8d581942bbb960420d875ba'
}

On-Chain Identifier

The onChainIdentifier option appends a 50-byte project marker to every UserOperation's call data. Pass a string to use it as the project name, or pass an object for more control over the platform and tool fields.

Type: string | OnChainIdentifier Required: No (optional)

Properties (object form):

  • project (string): The project name included in the marker
  • platform ('Web' | 'Mobile' | 'Safe App' | 'Widget', optional): The platform type (default: 'Web')
  • tool (string, optional): The tool name used to create the UserOperation
  • toolVersion (string, optional): Semver-style tool version string (e.g., '1.0.0')
// String form
const config = {
  onChainIdentifier: 'my-project'
}

// Object form
const config = {
  onChainIdentifier: {
    project: 'my-project',
    platform: 'Mobile',
    tool: 'my-wallet',
    toolVersion: '1.0.0'
  }
}

Safe Modules Version

The safeModulesVersion option specifies the Safe modules version for smart contract wallet implementation. Required for smart account initialization.

Type: string Required: Yes

Example:

const config = {
  safeModulesVersion: '0.3.0'
}

Paymaster Token

The paymasterToken option specifies the ERC-20 token used for paying transaction fees through the paymaster.

Type: object Required: Yes, for Paymaster Token mode only. Not used in Sponsorship Policy or Native Coins modes.

Properties:

  • address (string): The ERC-20 token contract address

Example:

const config = {
  paymasterToken: {
    address: '0xdAC17F958D2ee523a2206206994597C13D831ec7' // USD₮
  }
}

Sponsorship Policy ID

The sponsorshipPolicyId option specifies the sponsorship policy identifier for sponsored transactions.

Type: string Required: No (optional), only used in Sponsorship Policy mode.

Example:

const config = {
  isSponsored: true,
  sponsorshipPolicyId: 'sp_my_policy_id'
}

Gas Payment Mode Flags

These boolean flags control which gas payment mode is used. Only one mode should be active at a time.

isSponsored

Enables Sponsorship Policy mode, where a sponsor covers transaction fees.

Type: boolean Default: false

const config = {
  isSponsored: true,
  paymasterUrl: 'https://api.candide.dev/public/v3/ethereum'
}

useNativeCoins

Enables Native Coins mode, where the user pays fees in the chain's native currency (ETH, MATIC, etc.).

Type: boolean Default: false

const config = {
  useNativeCoins: true,
  transferMaxFee: 100000000000000n // Optional: max fee in wei
}

Transfer Max Fee

The transferMaxFee option sets the maximum fee amount in paymaster token units for transfer operations. This prevents transactions with unexpectedly high fees. Optional parameter.

Type: number | bigint Required: No (optional) Unit: Paymaster token base units

Example:

const config = {
  transferMaxFee: 100000 // 100,000 paymaster token units (e.g., 0.1 USD₮ if 6 decimals)
}

// Usage with error handling
try {
  const result = await account.transfer({
    token: '0x...',
    recipient: '0x...',
    amount: 1000000
  })
} catch (error) {
  if (error.message.includes('Exceeded maximum fee')) {
    console.error('Transfer cancelled: Fee too high')
  }
}

Network-Specific Configurations

Ethereum Mainnet

Supported Paymaster Tokens

The following tokens are supported for gas payments on Ethereum Mainnet:

  • USD₮: 0xdAC17F958D2ee523a2206206994597C13D831ec7
  • USA₮: 0x07041776f5007aca2a54844f50503a18a72a8b68
  • XAU₮: 0x68749665ff8d2d112fa859aa293f07a622782f38
const ethereumConfig = {
  chainId: 1,
  provider: 'https://rpc.mevblocker.io/fast',
  bundlerUrl: 'https://api.candide.dev/public/v3/ethereum',
  paymasterUrl: 'https://api.candide.dev/public/v3/ethereum',
  paymasterAddress: '0x8b1f6cb5d062aa2ce8d581942bbb960420d875ba',
  safeModulesVersion: '0.3.0',
  paymasterToken: {
    address: '0xdAC17F958D2ee523a2206206994597C13D831ec7' // USDT
  },
  transferMaxFee: 100000 // 100,000 paymaster token units (e.g., 0.1 USDT if 6 decimals)
}

Polygon Mainnet

const polygonConfig = {
  chainId: 137,
  provider: 'https://polygon-rpc.com',
  bundlerUrl: 'https://api.candide.dev/public/v3/polygon',
  paymasterUrl: 'https://api.candide.dev/public/v3/polygon',
  paymasterAddress: '0x8b1f6cb5d062aa2ce8d581942bbb960420d875ba',
  safeModulesVersion: '0.3.0',
  paymasterToken: {
    address: '0xc2132D05D31c914a87C6611C10748AEb04B58e8F' // USDT on Polygon
  },
  transferMaxFee: 100000
}

Arbitrum One

const arbitrumConfig = {
  chainId: 42161,
  provider: 'https://arb1.arbitrum.io/rpc',
  bundlerUrl: 'https://public.pimlico.io/v2/42161/rpc',
  paymasterUrl: 'https://public.pimlico.io/v2/42161/rpc',
  paymasterAddress: '0x777777777777AeC03fd955926DbF81597e66834C',
  safeModulesVersion: '0.3.0',
  paymasterToken: {
    address: '0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9' // USDT on Arbitrum
  },
  transferMaxFee: 100000
}

Avalanche C-Chain

const avalancheConfig = {
  chainId: 43114,
  provider: 'https://avalanche-c-chain-rpc.publicnode.com',
  bundlerUrl: "https://public.pimlico.io/v2/43114/rpc",
  paymasterUrl: "https://public.pimlico.io/v2/43114/rpc",
  paymasterAddress: '0x8b1f6cb5d062aa2ce8d581942bbb960420d875ba',
  safeModulesVersion: '0.3.0',
  paymasterToken: {
    address: '0x9702230a8ea53601f5cd2dc00fdbc13d4df4a8c7' // USDT
  },
  transferMaxFee: 100000 // 100,000 paymaster token units (e.g., 0.1 USDT if 6 decimals)
}

Plasma

// Plasma (example Layer 2)
const plasmaConfig = {
  chainId: 9745,
  provider: 'https://plasma.drpc.org',
  // For ERC-4337 support, optional fields:
  bundlerUrl: 'https://api.candide.dev/public/v3/9745',
  paymasterUrl: 'https://api.candide.dev/public/v3/9745',
  paymasterAddress: '0x8b1f6cb5d062aa2ce8d581942bbb960420d875ba',
  safeModulesVersion: '0.3.0',
  paymasterToken: {
    address: '0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb' // USDT
  },
  transferMaxFee: 100000 // 100,000 paymaster token units (e.g., 0.1 USDT if 6 decimals)
}

Sepolia Testnet (USD₮ ERC-20 mock/testnet only)


// Pimlico
const sepoliaConfigPimlico = {
  chainId: 11155111,
  provider: 'https://sepolia.drpc.org',
  bundlerUrl: 'https://public.pimlico.io/v2/11155111/rpc',
  paymasterUrl: 'https://public.pimlico.io/v2/11155111/rpc',
  paymasterAddress: '0x777777777777AeC03fd955926DbF81597e66834C',
  safeModulesVersion: '0.3.0',
  paymasterToken: {
    address: '0xd077a400968890eacc75cdc901f0356c943e4fdb' // USDT Sepolia
  },
  transferMaxFee: 100000 // 0.1 USDT (6 decimals)
}

// Candide
const sepoliaConfigCandide = {
  chainId: 11155111,
  provider: 'https://sepolia.drpc.org',
  bundlerUrl: 'https://api.candide.dev/public/v3/11155111',
  paymasterUrl: 'https://api.candide.dev/public/v3/11155111',
  paymasterAddress: '0x8b1f6cb5d062aa2ce8d581942bbb960420d875ba',
  safeModulesVersion: '0.3.0',
  paymasterToken: {
    address: '0xd077a400968890eacc75cdc901f0356c943e4fdb' // USDT Sepolia
  },
  transferMaxFee: 100000
}

Important Ethereum Sepolia is a testnet. The USD₮ tokens available at the links below are not real and do not entitle the holder to anything. In particular, they cannot be redeemed with Tether International, S.A. de C.V. ("Tether International") and are not Tether Tokens as described in Tether International's Terms of Service. The USD₮ tokens available at the links below on this testnet are intended for testing WDK on Ethereum Sepolia. The links below are links to third-party websites and are Third-Party Information as described in Tether Operations, S.A. de C.V.'s Website Terms

USD₮ on Sepolia contract: 0xd077a400968890eacc75cdc901f0356c943e4fdb

Get test USD₮:

Node.js Quickstart

Get started with WDK in a Node.js environment

React Native Quickstart

Build mobile wallets with React Native Expo

WDK EVM with ERC-4337 Wallet Usage

Get started with WDK's EVM with ERC-4337 Wallet Usage

WDK EVM with ERC-4337 Wallet API

Get started with WDK's EVM with ERC-4337 Wallet API

Need Help?

Discord CommunityConnect with developers, ask questions, share your projects
Join Community
GitHub IssuesReport bugs, request features, and get technical help
Open an Issue
Email ContactFor sensitive or private matters, contact our team directly
Send an email

Handle Errors

Previous Page

API Reference

Next Page

On this page

Wallet Configuration
Account Configuration
Configuration Options
Chain ID
Provider
Retries
Bundler URL
Paymaster URL
Paymaster Address
On-Chain Identifier
Safe Modules Version
Paymaster Token
Sponsorship Policy ID
Gas Payment Mode Flags
isSponsored
useNativeCoins
Transfer Max Fee
Network-Specific Configurations
Ethereum Mainnet
Polygon Mainnet
Arbitrum One
Avalanche C-Chain
Plasma
Sepolia Testnet (USD₮ ERC-20 mock/testnet only)
Need Help?