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
  entryPointAddress: '0x0000000071727De22E5E9d8BAf0edAc6f37da032',
  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',
    entryPointAddress: '0x0000000071727De22E5E9d8BAf0edAc6f37da032',
    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 Safe4337Pack 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.

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

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

Entry Point Address

The entryPointAddress option specifies the address of the ERC-4337 EntryPoint smart contract. Required for UserOperation processing.

Type: string Required: Yes

Standard EntryPoint v0.7:

const config = {
  entryPointAddress: '0x0000000071727De22E5E9d8BAf0edAc6f37da032'
}

Safe Modules Version

The safeModulesVersion option specifies the Safe modules version for smart contract wallet implementation. Required for Safe4337Pack 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',
  entryPointAddress: '0x0000000071727De22E5E9d8BAf0edAc6f37da032',
  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',
  entryPointAddress: '0x0000000071727De22E5E9d8BAf0edAc6f37da032',
  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',
  entryPointAddress: '0x0000000071727De22E5E9d8BAf0edAc6f37da032',
  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',
  entryPointAddress: '0x0000000071727De22E5E9d8BAf0edAc6f37da032',
  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',
  entryPointAddress: '0x0000000071727De22E5E9d8BAf0edAc6f37da032',
  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',
  entryPointAddress: '0x0000000071727De22E5E9d8BAf0edAc6f37da032',
  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',
  entryPointAddress: '0x0000000071727De22E5E9d8BAf0edAc6f37da032',
  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 Community

Connect with developers, ask questions, share your projects

Join Community

GitHub Issues

Report bugs, request features, and get technical help

Open an Issue

Email Contact

For sensitive or private matters, contact our team directly

Send an email

hashtagWallet Configuration

hashtagAccount Configuration

hashtagConfiguration Options

hashtagChain ID

hashtagProvider

hashtagBundler URL

hashtagPaymaster URL

hashtagPaymaster Address

hashtagEntry Point Address

hashtagSafe Modules Version

hashtagPaymaster Token

hashtagSponsorship Policy ID

hashtagGas Payment Mode Flags

hashtagisSponsored

hashtaguseNativeCoins

hashtagTransfer Max Fee

hashtagNetwork-Specific Configurations

hashtagEthereum Mainnet

hashtagPolygon Mainnet

hashtagArbitrum One

hashtagAvalanche C-Chain

hashtagPlasma

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

hashtagNeed Help?

Wallet Configuration

Account Configuration

Configuration Options

Chain ID

Provider

Bundler URL

Paymaster URL

Paymaster Address

Entry Point Address

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?