Paymaster & Gasless Transactions

Sponsor gas fees for your users with the built-in Paymaster.

A Paymaster is an ERC-4337 contract that pays gas fees on behalf of users. When configured, your users can send transactions without holding any native tokens — the Paymaster covers the cost.

What is a Paymaster?

In the ERC-4337 flow, the EntryPoint contract checks whether a UserOperation includes a paymasterAndData field. If present, the EntryPoint calls the Paymaster contract to verify sponsorship and deducts gas costs from the Paymaster’s deposit instead of the user’s smart account.

This enables fully gasless experiences where users interact with your application without ever needing to acquire native tokens.

Enabling on the Backend

Pass paymasterAddress in the ServerWalletManager configuration:

import { createServerWalletManager, MemoryKeyshareStorage } from '@embarkai/core'
 
const manager = createServerWalletManager({
  apiKey: process.env.EMBARK_API_KEY!,
  chainId: 994873017, // Lumia Mainnet
  storage: new MemoryKeyshareStorage(),
  paymasterAddress: '0xYourPaymasterAddress',
})
 
const wallet = await manager.getWallet('my-wallet')
 
// This transaction is gas-sponsored -- the user pays nothing
const userOpHash = await wallet.sendUserOperation(
  '0xRecipientAddress',
  '1000000000000000000',
)

When paymasterAddress is set, every UserOperation sent through this manager instance is automatically routed through the Paymaster.

Enabling on the Frontend

In the UI Kit, pass the usePaymaster prop to ConnectWalletButton:

import { Provider, ConnectWalletButton } from '@embarkai/ui-kit'
 
function App() {
  return (
    <Provider
      projectId={process.env.NEXT_PUBLIC_PROJECT_ID!}
      chainId={994873017}
    >
      <ConnectWalletButton usePaymaster />
    </Provider>
  )
}

When usePaymaster is enabled, all transactions initiated through the UI Kit hooks (useSendTransaction) are automatically gas-sponsored.

How Sponsorship Works

The gas sponsorship flow follows these steps:

1. UserOperation construction — The SDK builds the UserOperation and includes the Paymaster address in the paymasterAndData field
2. Paymaster validation — The Bundler calls the Paymaster’s validatePaymasterUserOp method during simulation to confirm sponsorship
3. Submission — The Bundler submits the UserOperation to the EntryPoint
4. Gas payment — The EntryPoint deducts gas costs from the Paymaster’s on-chain deposit, not from the user’s account
5. Post-operation — The Paymaster’s postOp method runs for any cleanup or accounting

Supported Chains

Cost Considerations

• The Paymaster contract must have a sufficient deposit in the EntryPoint to cover gas costs
• Monitor your Paymaster balance to avoid failed transactions
• Consider implementing rate limiting or allowlists to prevent abuse
• Gas costs are paid by whoever funds the Paymaster deposit — typically the application developer
• On testnets, gas costs are negligible and ideal for development

Next Steps

• Account Abstraction — Understand the full ERC-4337 architecture
• Gasless Transactions Tutorial — Step-by-step guide to sending gasless transactions
• Server Wallets — Configure paymasterAddress in your backend
• Supported Chains — See all available chains and contract addresses