Introduction to Paymaster API

Account abstraction with ERC-4337 enable special entities called paymasters. These are third-parties that can sponsor the gas for an account if their conditions are met. This enables account holders to pay for transaction fees in many different ways without resulting to custodial solutions.

This page covers v0.6+ paymasters. For documentation about v0.4 paymasters, see Legacy RPC Methods.

Stackup Paymasters

Stackup's paymasters allow users to sponsor transactions or accept ERC-20 tokens for gas payment. The full RPC methods can be found in Paymaster RPC Methods.

Sponsored Transactions

Using the payg paymaster type, you can sponsor transactions directly for users. Stackup will fully cover gas for valid UserOperations and the value will be billed to your monthly invoice with Stackup.

ERC-20 Tokens

The erc20token paymaster type allows you to use ERC-20 tokens for gas payments. Stackup will fully cover gas for valid UserOperations and the Stackup paymaster will withdraw the appropriate ERC-20 token amount at the end of the UserOperation.

ERC-20 withdrawal occurs during the postOp method. Stackup has various protections to ensure that the Smart Account's ERC-20 token balance does not change between the paymaster agreeing to sponsor the transaction and withdrawing the ERC-20 token. In the rare case a Smart Account bypasses these checks to exploit the paymaster, Stackup will treat it as a sponsored transaction and add the unpaid gas to your monthly invoice.

Using userop.js

The easiest way to use paymasters is with the userop.js library to call the Paymaster RPC Methods. As a UserOperation is built using buildOp, the verifyingPaymaster middleware can be used to retrieve the paymasterAndData and required gas limits. See the verifyingPaymaster function for more details and the examples repository for an implementation.

Endpoints

Enable Paymasters

Paymasters are included by default in the Developer and Enterprise Plans. This can be enabled on the billing page in the Stackup dashboard.