Choose your paymaster kit
Selecting the right paymaster kit depends on your target users and how you want to subsidize gas fees. You need to match the kit to your account abstraction stack—whether that is Safe, MetaMask, or a custom implementation—and decide between ETH sponsorship or ERC-20 token payments.
Most developers start with a standard kit that integrates directly with their existing wallet infrastructure. The MetaMask SDK offers a dedicated implementation for ERC-20 gas payments, allowing users to pay in stablecoins like USDC rather than the native chain token. This approach significantly lowers the friction for users who hold stablecoins but lack ETH for transaction fees.
If you are building on the Safe protocol, the Safe Protocol Kit provides specific documentation for sponsoring transactions via ERC-4337. This kit is designed to work seamlessly with Safe accounts, handling the complexity of bundling and verification without requiring you to build custom verification logic from scratch.
For teams needing full control over the smart contract logic, open-source kits like the Biconomy or Stackup paymaster contracts provide audited, production-ready templates. These kits allow you to deploy your own paymaster contract while leveraging existing infrastructure for user session keys and bundler integration.
Kit Comparison
| Feature | MetaMask SDK Paymaster | Safe Protocol Kit | Custom Biconomy/Stackup | ERC-20 Specific | ETH Sponsorship |
|---|---|---|---|---|---|
| Primary Wallet Support | MetaMask Smart Accounts | Safe Accounts | Custom / MetaMask | USDC / Stablecoins | Native ETH |
| Gas Payment Token | ERC-20 (e.g., USDC) | ETH or ERC-20 | Configurable | ERC-20 Only | ETH Only |
| Integration Complexity | Low (SDK-based) | Medium (Safe-specific) | High (Custom logic) | Low | Low |
| Audited Contracts | Yes | Yes | Yes | Yes | Yes |
Recommended Developer Toolkits
As an Amazon Associate, we may earn from qualifying purchases.
Set up the bundler and paymaster node
Running a paymaster requires two distinct infrastructure components working in tandem: a bundler to aggregate and submit user operations to the blockchain, and a paymaster node to validate and sponsor those operations. The bundler acts as the relay, while your paymaster node holds the logic for who gets gas paid and in what currency.
Follow these steps to configure the entry point contract and connect your node to a bundler.
The bundler is responsible for collecting user operations (UserOps) from the mempool, bundling them into a single transaction, and submitting them to the EntryPoint contract. Choose a bundler provider (such as Alchemy, Stackup, or a self-hosted OpenBundler instance) and configure your environment variables. Ensure the bundler is connected to a full node for the specific chain you are deploying on (e.g., Sepolia, Mainnet). This node will relay your paymaster’s logic to the network.
The EntryPoint contract is the core interface between your paymaster, the bundler, and the blockchain. It manages the execution of UserOps and handles gas payment settlements. Deploy the standard EntryPoint contract (e.g., v0.6 or v0.7 depending on your chain’s supported version) to your target network. You will need the contract address and ABI to configure both the bundler and your paymaster node. Official implementations are available via the ERC-4337 GitHub repositories.
Your paymaster node must implement the paymasterAndData field logic. This involves writing smart contract code (or using a kit like SafeWallet Paymaster or Biconomy) that decides when to sponsor a transaction. Common logic includes:
Deploy your paymaster smart contract and link it to the EntryPoint address.
Update your bundler configuration to recognize your newly deployed paymaster contract address. The bundler must be able to route UserOps to your paymaster for validation. Test this connection by sending a test UserOp from a client SDK (like ethers-viem or viem). If configured correctly, the bundler will forward the operation to your paymaster, which will validate it and return the necessary data for the bundler to include it in a block.
Your paymaster contract must hold a balance of the native gas token (e.g., ETH on Ethereum, MATIC on Polygon) to pay for gas on behalf of users. Transfer funds to your paymaster contract address. If you are using an ERC-20 payment model, ensure the contract also holds the approved balance of the accepted token to cover refunds or settlements. Monitor this balance closely, as an empty paymaster will cause all sponsored transactions to fail.
Configure gas payment rules
Setting up your paymaster logic determines how and when users can transact without paying gas themselves. You are essentially defining the sponsorship policy for your application. This configuration dictates whether you cover all costs, limit spending per user, or allow payment in alternative tokens like USDC instead of native ETH.
Define the payment token
The most common configuration is an ERC-20 paymaster, which allows users to pay gas fees using stablecoins or other tokens rather than the chain's native currency. This is particularly useful for reducing friction for users who do not hold the native token.
To implement this, you must specify the token address and the exchange rate logic in your paymaster contract. MetaMask’s Smart Accounts, for example, support this pattern by allowing users to settle gas fees in USDC. You will need to ensure your paymaster has sufficient approval for the ERC-20 token and maintains a reserve of native gas tokens to pay the bundlers.
Set spending limits and conditions
You can restrict gas sponsorship to prevent abuse or excessive costs. Common strategies include:
- Per-transaction limits: Cap the maximum gas price or units a single transaction can consume.
- Per-user budgets: Track the total amount of gas sponsored for a specific user address over a period.
- Conditional sponsorship: Only sponsor transactions that meet specific criteria, such as interacting with a specific contract or occurring during a promotional period.
Pre-deployment configuration checklist
Before deploying your paymaster contract, verify the following:
-
The ERC-20 token address is correct for your target network.
-
The paymaster contract holds enough native gas tokens to cover bundler fees.
-
The paymaster contract has sufficient ERC-20 token allowance from the sponsor’s wallet.
-
Spending limits (if any) are correctly coded and tested.
-
Fallback logic is in place for when the paymaster runs out of funds.
Ensure the paymaster contract is approved to spend the ERC-20 tokens on behalf of the sponsor. Without this approval, the paymaster cannot swap tokens to pay for gas, and transactions will fail.
Deposit native gas tokens (e.g., ETH on Ethereum, MATIC on Polygon) into the paymaster contract. This reserve is what the bundlers actually receive. Monitor this balance closely to avoid service interruption.
Run a test transaction with minimal value. Verify that the user sees zero gas fees and that the bundler successfully includes the transaction in a block. Check the paymaster’s internal accounting to ensure the ERC-20 deduction occurred as expected.
Test with a sandbox environment
Testing paymaster integration requires a controlled environment that mirrors production constraints. Use a local bundler and a testnet node to simulate user operations without risking real funds.
Common paymaster integration errors
Deploying a paymaster requires precise handling of ERC-4337 logic. Most failures stem from incorrect signature validation or insufficient gas limits. These errors often cause user transactions to revert silently or leave funds stuck in the bundler.
Signature validation pitfalls
The most frequent error is failing to verify the paymaster’s signature correctly. If the verifyUserOpSignature method does not strictly check the sender and the hash, attackers can forge transactions. Always validate that the signature matches the expected public key and that the hash includes the correct userOpHash. This step is non-negotiable for security.
Gas limit miscalculations
Another common issue is setting gas limits too low. If the paymaster’s post-operation gas cost exceeds the limit, the transaction fails. Always calculate the maximum possible gas usage, including the paymaster’s overhead and the user’s operation. Use the getPaymasterStubData method to estimate costs accurately before deployment.
Fixing the errors
To resolve these issues, test your paymaster with a local bundler. Use tools like Safe Protocol Kit for integration guidance. Always verify signatures and gas limits in a staging environment before going live. This prevents costly errors in production.
Paymaster kit questions answered
The term "paymaster" appears in legal and payroll contexts, but in blockchain development, it refers to an ERC-4337 smart contract that sponsors user operations. This distinction is critical for developers deploying zero-fee gas solutions.
What is a blockchain paymaster?
A blockchain paymaster allows dApps and wallets to sponsor user operations, enabling users to pay gas fees in ERC-20 tokens or stablecoins instead of the native chain token. This removes the friction of requiring users to hold specific cryptocurrency for transaction fees.
Is a paymaster legitimate for Web3 development?
Yes, paymasters are a core component of the ERC-4337 account abstraction standard. They provide audited, production-ready infrastructure for gasless transactions, making dApps feel more like traditional Web2 applications by abstracting away complex wallet management.
Do I need a lawyer to use a paymaster?
No. Unlike legal paymasters who manage escrow funds, blockchain paymasters are smart contracts. They do not require attorneys or trust accounts. The "paymaster" in this context is a code module, not a fiduciary service provider.
No comments yet. Be the first to share your thoughts!