Choose your paymaster model
Selecting the right ERC-4337 paymaster architecture determines how your application handles gas fees and user verification. The model you pick dictates the user experience, your operational costs, and the complexity of your smart contract logic. Before writing code, you need to match your business requirements to one of the three standard paymaster types.
Sponsorship Paymaster
The Sponsorship Paymaster is the simplest entry point. It covers gas fees for all users regardless of their actions, effectively removing gas friction entirely. This model is ideal for onboarding experiments, marketing campaigns, or internal tools where cost efficiency is secondary to user acquisition. You pay for every transaction, but the implementation is straightforward: the paymaster signs all valid user operations.
ERC-20 Paymaster
The ERC-20 Paymaster allows users to pay gas fees using your application’s native token instead of ETH. This creates a seamless experience for users who hold your token but lack native gas currency. To implement this, you must integrate a token swap mechanism (like Uniswap) within the paymaster contract to convert the user’s tokens into ETH for the bundler. This model aligns user incentives with your token economy but adds significant complexity and gas overhead to the paymaster itself.
Verifying Paymaster
The Verifying Paymaster charges users only when they meet specific off-chain conditions, such as holding a certain NFT or completing a KYC step. This model offers the most granular control over who pays for gas. It requires a signature scheme (like EIP-712) to verify off-chain claims on-chain. This is best for gated communities or loyalty programs where you want to subsidize gas only for eligible participants.
| Model | Cost Structure | Dev Complexity | User Experience |
|---|---|---|---|
| Sponsorship | Fixed: You pay all gas | Low | Zero gas friction |
| ERC-20 | Variable: User pays in token | High (requires swaps) | No ETH needed |
| Verifying | Conditional: Based on claims | Medium (signature logic) | Gated access |
Install SDK dependencies
Get the environment ready with the core Paymaster Kit 2026 package and its peer dependencies. This step ensures your project has the necessary TypeScript definitions and runtime libraries to handle gasless transactions.
Run the following command in your project root to install the SDK:
Once installed, verify the package is listed in your package.json. The SDK includes built-in support for ERC-4337 User Operations, which are required for gas sponsorship.
Initialize the smart account
The smart account is the engine that processes transactions, while the paymaster is the fuel source. Connecting them requires initializing the smart account instance and passing the paymaster configuration as a dependency. This setup ensures that when a user signs a transaction, the system automatically routes the gas fees to the paymaster.
Start by installing the necessary SDK dependencies. You will need the core smart account library and the specific paymaster kit package. These packages handle the cryptographic signing and the UserOp builder logic.
Begin by importing the SmartAccount class and your chosen paymaster provider from the installed SDK. Ensure you are using the correct version compatible with your target chain and wallet type.
Define the paymaster configuration object. This includes your API key, the chain ID, and any specific fee parameters. The paymaster needs to know which transactions to sponsor and under what conditions.
Create the smart account instance by passing your wallet signer and the paymaster configuration. This binds the paymaster to the account, enabling gasless transactions for all subsequent operations.
import { SmartAccount } from '@paymasterkit/sdk';
import { GaslessPaymaster } from '@paymasterkit/paymaster';
const paymaster = new GaslessPaymaster({
apiKey: process.env.PAYMASTER_API_KEY,
chainId: 1,
});
const smartAccount = new SmartAccount({
signer: wallet,
paymaster,
});
Once initialized, the smart account is ready to build and send UserOperations. The paymaster will intercept the gas fee requirements and sponsor them according to your configured rules. Verify the connection by sending a small test transaction to ensure the gas is being covered correctly.
Set hard caps and percentage limits
Configuring gas sponsorship logic determines how much of the transaction fee the Paymaster covers. You can choose between a fixed hard cap or a percentage-based share of the total gas cost. This choice directly impacts your operational budget and user experience.
Define a hard cap for predictable costs
A hard cap sets a maximum amount of gas (in Wei or Gwei) that the Paymaster will pay for any single transaction. This is the simplest model for budgeting. If the actual gas cost exceeds the cap, the user must pay the difference, or the transaction reverts.
To implement this, define a maxGasLimit in your Paymaster configuration. This value should be based on the average gas consumption of your most common operations. For example, if a standard swap uses 150,000 gas, setting a cap of 200,000 provides a small buffer for network congestion.
const paymasterConfig = {
maxGasLimit: 200000n,
// other config...
};
Use percentage-based limits for variable costs
Percentage-based sponsorship covers a fixed portion of the total gas fee, regardless of how much gas the transaction consumes. This approach is better for applications with highly variable transaction costs, such as NFT mints with dynamic metadata.
Set a gasSharePercentage (e.g., 50) to cover half the cost. The Paymaster calculates the final amount by multiplying the total gas cost by this percentage. This ensures that even during high congestion, the user always bears a predictable share of the burden.
const paymasterConfig = {
gasSharePercentage: 50,
// other config...
};
Balance user experience and budget
The right limit depends on your application’s goals. Hard caps protect your treasury from runaway costs but may frustrate users during network congestion. Percentage-based models share the risk but require more complex accounting.
Monitor your sponsorship spend regularly. Use analytics to track how often transactions hit the gas cap. If users frequently hit the limit, consider increasing the cap or switching to a percentage model. This data-driven approach ensures your gasless experience remains reliable without draining your resources.
Test the paymaster flow
Before moving to mainnet, you need proof that your Paymaster Kit 2026 configuration actually covers gas costs. This section walks you through verifying that a user operation is sponsored correctly on a testnet.
Initialize your provider to connect to a supported testnet like Sepolia or Holesky. Ensure your smart account instance is pointing to the correct chain ID. If the connection fails, the paymaster cannot validate or sponsor any operations.
Build a simple user operation with a minimal payload, such as a small ETH transfer or a contract interaction. This operation should include the paymaster and paymaster data fields. Keep the gas limits standard for now to isolate sponsorship logic from gas estimation errors.
Send the user operation to your configured bundler endpoint. The bundler will attempt to bundle this operation into a transaction. Watch for immediate rejections, which often indicate missing paymaster data or incorrect signature formats.
Once the bundler accepts the operation, check the testnet block explorer for the resulting transaction. Look for the paymaster contract address in the transaction logs. Confirm that the user paid zero gas fees and that the paymaster contract was debited for the cost instead.
If the transaction fails or the user is still charged gas, check your paymaster logic. Common issues include signature verification failures or insufficient balance in the paymaster contract. Use the testnet explorer to trace the revert reason and adjust your configuration accordingly.
Common paymaster: what to check next
When setting up a Paymaster Kit 2026, developers often hit specific technical hurdles regarding gas payment methods and validation flows. Below are the most frequent questions about ERC-4337 paymasters.
No comments yet. Be the first to share your thoughts!