Build a Paymaster Kit 2026 for Gasless Transactions

Set up the bundler and paymaster

To enable gasless transactions, connect your smart account to a bundler and initialize a paymaster service. The bundler collects user operations and submits them to the mempool, while the paymaster covers the gas fees on behalf of the user. This setup removes the need for users to hold native ETH for transaction fees.

Install the bundler

Start by installing the bundler package. Most SDKs, like the one provided by Eco, ship with a built-in 4337 bundler that supports both ERC-4337 and EIP-7702 flows. Configure the bundler to listen on your local development network or a testnet endpoint.

npm install @your-sdk/bundler

Configure the paymaster contract

Next, deploy or integrate a paymaster contract. The MetaMask documentation provides a clear path for using an ERC-20 paymaster, which allows users to pay gas fees in tokens like USDC rather than the native chain token. This is often more intuitive for users who already hold stablecoins.

1. Deploy the paymaster contract to your target network.
2. Fund the contract with the token you wish to use for gas payments.
3. Set the sponsorshipPolicyId or equivalent configuration in your paymaster contract.

Link the paymaster to the smart account

Finally, connect the paymaster to your smart account implementation. Ensure your smart account is configured to recognize the paymaster's address and validate user operations correctly. This integration ensures that when a user signs a transaction, the bundler knows to route it through the paymaster for fee sponsorship.

Test the flow by initiating a transaction from your smart account. Verify that the bundler picks up the operation and that the paymaster covers the gas cost as expected.

Configure ERC-20 gas payment logic

Switching from native gas payment to ERC-20 token sponsorship allows users to pay transaction fees in tokens like USDC instead of holding the network’s native currency. This setup removes the friction of acquiring ETH or MATIC just to interact with your application.

The MetaMask Smart Account documentation provides a clear reference for implementing ERC-20 paymasters, demonstrating how to integrate USDC sponsorship directly into the user flow MetaMask Docs. Follow these steps to configure the logic in your paymaster kit.

1

Approve the Paymaster Contract

Before the paymaster can deduct gas fees from a user’s token balance, the user must grant the contract permission to spend their tokens. Implement an approve or increaseAllowance function call in your frontend. This transaction requires a small amount of native gas, which the user must cover themselves. Once approved, the paymaster can deduct fees on subsequent transactions without further user interaction.

2

Update the Paymaster Configuration

Modify your paymaster contract to accept ERC-20 tokens. You need to import the standard ERC-20 interface and define the specific token address (e.g., USDC) that your paymaster will support. Ensure the contract has a mechanism to withdraw the collected fees so you can replenish the paymaster’s balance. This configuration ensures the contract knows exactly which token to deduct and how much gas it covers.

3

Implement Fee Deduction Logic

Inside the paymaster’s postOp or validatePaymasterUserOp function, calculate the gas cost of the executed transaction. Deduct this amount from the user’s approved token allowance. Use safeTransferFrom to move the tokens from the user to the paymaster contract. This step ensures that the user’s token balance is reduced by the exact cost of the gas they consumed, maintaining accurate accounting.

4

Handle Edge Cases and Failures

Implement error handling for insufficient allowances or failed transfers. If the user’s token balance is too low or the allowance has expired, the transaction should fail gracefully with a clear error message. Additionally, consider setting a minimum balance threshold to prevent dust transactions that cost more in gas than they are worth. This protects both the user and the paymaster from unnecessary overhead.

Previous

1234

Next

Compare top paymaster infrastructure options

Choosing between a custom paymaster and a managed service depends on your team’s bandwidth and your application’s specific gas requirements. Managed services like ZeroDev and Biconomy handle the heavy lifting of node infrastructure, bundlers, and smart contract maintenance. This approach is ideal for teams prioritizing speed to market over granular control.

Building a custom paymaster offers full ownership of the smart contract logic and gas sponsorship rules. You can tailor the payment mechanisms to complex scenarios, such as batched transactions or tiered user rewards. However, this path requires significant engineering resources to maintain the underlying infrastructure and ensure security.

The table below compares the most common paymaster infrastructure options across cost, customization, and integration complexity. Use these metrics to determine which model aligns with your development timeline and technical capabilities.

Fix common signature validation errors

Signature verification is the most frequent point of failure in ERC-4337 integration. When a bundler rejects a userOp, the error is almost always a mismatch between the signature provided by the user and the hash expected by the paymaster or entry point. Below are the standard fixes for these validation errors.

Check the hash encoding

The signature must be generated over the exact userOpHash. A common mistake is signing the raw userOp object instead of the EIP-712 typed data or the keccak256 hash. Ensure your client-side logic signs the correct digest that matches what the smart contract verifies.

Verify signature format

Paymasters expect signatures in a specific format, typically r || s || v or s || v depending on the implementation. If the signature is malformed, the verification will fail. Use a library like ethers.js or viem to ensure the signature is encoded correctly before sending it to the bundler.

Debug with bundler logs

When validation fails, the bundler returns a specific error code. Use these logs to pinpoint the issue. If the error is invalidSignature, double-check the public key recovery. If the error is stake too low, the paymaster contract may not be sufficiently bonded.

Verify gasless transactions on testnet

Before pushing to mainnet, confirm your paymaster kit handles UserOperation inclusion and gas reimbursement correctly. Test on Sepolia or Holesky using a faucet-funded smart account. Focus on these verification steps:

1

Send a UserOperation

Use your kit’s SDK to construct a UserOperation with a test account. Ensure the signature is valid and the paymaster address is correctly set in the paymasterAndData field.

2

Check mempool inclusion

Monitor the testnet mempool (e.g., via Etherscan or a block explorer) for the UserOperation hash. The operation should appear shortly after submission if the bundler picks it up.

3

Verify gas reimbursement

Confirm the paymaster contract emits the correct events and that the gas fee is deducted from the paymaster’s balance, not the user’s. The user’s ETH balance should remain unchanged.

Previous

123

Next

Frequently asked questions about paymaster kits

Do paymaster kits support ERC-20 token gas payments?

Yes, most modern paymaster kits are designed to support ERC-20 token payments, allowing users to pay gas fees with tokens like USDC instead of the native chain token. This requires the paymaster contract to handle token transfers and approvals securely. MetaMask provides documentation on integrating ERC-20 paymasters with Smart Accounts to facilitate this flow.

How do I prevent paymaster abuse or spam?

Preventing abuse involves implementing strict validation logic within the validatePaymasterUserOp function. You should enforce rate limits, verify that the user has sufficient token balance, and ensure the sponsored transaction does not exceed a predefined gas cap. Without these checks, attackers could exploit the paymaster to drain funds or clog the mempool.

Is a paymaster kit compatible with all ERC-4337 bundlers?

A properly implemented paymaster kit adheres to the ERC-4337 specification, making it compatible with any standard bundler that supports the protocol. However, you must ensure your paymaster contract is deployed on the same chain as the bundler you intend to use. Compatibility is determined by the EntryPoint contract version, not the bundler itself.

Can I sponsor gas for specific dApp actions only?

Yes, you can configure the paymaster to sponsor only specific actions by using entry points or session keys. This allows you to limit gas sponsorship to certain contract calls or user interactions, providing better control over costs and security. This approach is ideal for onboarding new users by sponsoring only the initial transaction, such as account creation or first login.