Build a Paymaster Kit for Gasless Transactions

The paymaster kit checks if the request meets your sponsorship rules, such as valid signatures or token balances.

The paymaster submits the UserOp to the mempool, covering the gas fees so the user pays nothing upfront.

Initialize the provider with your RPC endpoint and the Safe singleton address. The provider acts as the bridge between your application and the blockchain, handling signature aggregation and transaction execution. Create a configuration object that includes the chain ID and the specific Safe version you intend to support.

import { SafeProvider } from '@safe-global/safe-ethers-lib';

const provider = new SafeProvider({
  provider: infuraProvider,
  safeSingletonAddress: SafeSingletonAddress.SAFE_V1_4_1,
});

This step establishes the read-only connection to the network. You will later attach a signer to this provider to execute transactions on behalf of the user.

You must deploy a custom Paymaster contract to your target chain. This contract holds the funds (ETH or ERC-20 tokens) used to sponsor user transactions. Use Hardhat or Foundry to compile and deploy the contract, ensuring you have sufficient native token balance in the deployed address.

For ERC-20 sponsorship, the contract must approve the bundler to spend your tokens. After deployment, record the contract address and the ABI for use in the next step. Do not use testnet tokens for production integration; verify the contract interaction on a block explorer first.

Connect the deployed Paymaster contract to your Safe Protocol Kit instance. This configuration tells the smart account which Paymaster to call during transaction execution. You must pass the Paymaster address and the specific mode (e.g., StakeAware or ERC20) to the kit configuration.

import { SafeKit } from '@safe-global/protocol-kit';

const safeKit = new SafeKit({
  provider,
  signer,
  paymasterAddress: '0xYourPaymasterAddress',
  paymasterMode: PaymasterModes.ERC20,
});

Once linked, the Safe Kit will automatically include the Paymaster data in the user’s transaction request. Test this connection by attempting a small transaction; if successful, the gas fees will be deducted from your Paymaster contract, not the user’s wallet.

Confirm that the contract holds enough funds to cover the estimated gas cost of a typical user operation. A single user operation on Sepolia typically costs less than $0.01 in gas, but you should fund the contract with at least 0.01–0.05 ETH to allow for multiple test transactions. If your paymaster uses a strict balance check, an insufficient balance will cause the user operation to fail with a PaymasterAndData error.

Use a bundler (such as the Alchemy Bundler or a local node) to submit a test user operation via eth_sendUserOperation. Ensure the paymasterAndData field is correctly encoded with your contract address and any necessary sponsorship parameters. Monitor the transaction in the bundler’s response and on a block explorer. A successful sponsorship will show the gas fees paid by the paymaster contract rather than the user’s wallet.

If your paymaster charges users in ERC-20 tokens or implements a post-operation refund mechanism, verify that the balance changes are correct. Check the user’s token balance and the paymaster’s token balance before and after the transaction. Ensure that the gas refund logic does not leave the contract in a state where it cannot cover future operations.

Check the bundler and node logs for any errors or warnings related to the paymaster. Look for UserOperation reverted messages that indicate the paymaster rejected the operation due to invalid signatures, insufficient funds, or failed validation. Resolve any issues before proceeding to mainnet deployment.