Integration

This guide covers end-to-end Paymaster v2 integration for gas sponsorship (users pay nothing) and token-fee mode (users pay in ERC-20). Related pages in this section:

How billing works

For both mode: "sponsor" and mode: "token", usage deducts from the developer’s USD gas credit.
In mode: "token", token deductions are transferred to the configured paymaster treasury wallet as compensation.
constantFee is an extra token fee charged from the end user per transaction/userOp.

Dashboard-managed paymaster config (new flow)

Paymaster v2 now reads token-mode policy from your paymaster config (validated by validation-service), not from per-request context fields. Configure these in dashboard create/update paymaster:

isERC20
isSponsored
treasuryWalletAddress (required when isERC20=true)
constantFee (required when isERC20=true, 0..10)
validUntilMinutes
restrictionType: NONE | ALLOWLIST | BLOCKLIST
restrictedWallets (used for allowlist/blocklist checks)

Step 1: Create a Paymaster client (v2)

Use the API key you copied from the dashboard.

import { http } from "viem";
import { createPaymasterClient } from "viem/account-abstraction";

const CHAIN_ID = 80002; // example: base-amoy / your chain id
const API_KEY = "<YOUR_PAYMASTER_API_KEY>";

const paymasterClient = createPaymasterClient({
  transport: http(
    `https://paymaster.abstraxn.com/api/v2/${CHAIN_ID}/?apikey=${API_KEY}`,
  ),
});

Step 2: Call `sendUserOperation` (paymaster + paymasterContext)

sendUserOperation is where you pass:

paymaster: paymasterClient
paymasterContext (controls how v2 pays fees)

const hash = await bundlerClient.sendUserOperation({
  account: kernelAccount,  // your Smart Account
  calls: [
    // your call(s) live here
  ],
  paymaster: paymasterClient,
  paymasterContext: {
    // mode goes here (sponsor or token)
  },
});

Use mode: "sponsor" when you want the paymaster to sponsor gas using the native gas flow.

paymasterContext: {
  mode: "sponsor",
},

Step 4: ERC20 (token) mode

Use mode: "token" when you want fees paid in an ERC20 token.

Required `paymasterContext` fields

For mode: "token", you must provide:

tokenAddress: ERC20 contract address used for fee payment

treasury and constantFee are sourced from paymaster config in the dashboard (via validation-service). Do not send these in request context.

`paymasterContext` field definitions (focused)

`mode`

Defines how gas is paid:

"sponsor": native gas sponsorship by paymaster
"token": ERC20 token is deducted as fee payment

paymasterContext: {
  mode: "sponsor", // or "token"
}

`tokenAddress` (required in `mode: "token"`)

The ERC-20 token address to use for payment.

paymasterContext: {
  mode: "token",
  tokenAddress: "0xTOKEN_ADDRESS",
}

`treasury` (dashboard-configured)

The receiver wallet for deducted ERC20 fees (compensation wallet).

paymasterContext: {
  mode: "token",
  // treasury is read from dashboard paymaster configuration
}

`constantFee` (dashboard-configured)

Additional token amount charged per transaction / userOp.

paymasterContext: {
  mode: "token",
  // constantFee is read from dashboard paymaster configuration
}

Example `paymasterContext` (token mode)

paymasterContext: {
  mode: "token",
  tokenAddress: TOKEN_ADDRESS,
  // treasury and constantFee are read from paymaster configuration
},

ERC20 approval: what you must do

In ERC20 token mode, the paymaster deducts fees during the same UserOperation (post-op). That deduction requires the sender to have ERC20 allowance for the paymaster contract. So you must add an approve(...) call into calls before your real action call. Minimal pattern:

import { encodeFunctionData, erc20Abi, maxUint256 } from "viem";

const approveData = encodeFunctionData({
  abi: erc20Abi,
  functionName: "approve",
  args: [PAYMASTER_ADDRESS, maxUint256], // or approve the exact needed amount
});

const hash = await bundlerClient.sendUserOperation({
  account: kernelAccount,
  calls: [
    // 1) give allowance to paymaster
    { to: TOKEN_ADDRESS, value: 0n, data: approveData },
    // 2) your real action call(s)
    { to: TARGET_CONTRACT, value: 0n, data: TARGET_CALLDATA },
  ],
  paymaster: paymasterClient,
  paymasterContext: {
    mode: "token",
    tokenAddress: TOKEN_ADDRESS,
    // treasury and constantFee are fetched from paymaster configuration
  },
});

Notes you must know

PAYMASTER_ADDRESS must be the Paymaster contract address used by your backend for the chain you are using.
If token-mode configuration is missing in dashboard (isERC20, treasuryWalletAddress, constantFee), v2 will reject the request.

EIP 7702

Bundler Integration

Paymaster Integration

Accounts

How billing works

Dashboard-managed paymaster config (new flow)

Step 1: Create a Paymaster client (v2)

Step 2: Call `sendUserOperation` (paymaster + paymasterContext)

Step 4: ERC20 (token) mode

Required `paymasterContext` fields

`paymasterContext` field definitions (focused)

`mode`

`tokenAddress` (required in `mode: "token"`)

`treasury` (dashboard-configured)

`constantFee` (dashboard-configured)

Example `paymasterContext` (token mode)

ERC20 approval: what you must do

Notes you must know

​How billing works

​Dashboard-managed paymaster config (new flow)

​Step 1: Create a Paymaster client (v2)

​Step 2: Call sendUserOperation (paymaster + paymasterContext)

​Step 3: Sponsor mode (native gas sponsorship)

​Step 4: ERC20 (token) mode

​Required paymasterContext fields

​paymasterContext field definitions (focused)

​mode

​tokenAddress (required in mode: "token")

​treasury (dashboard-configured)

​constantFee (dashboard-configured)

​Example paymasterContext (token mode)

​ERC20 approval: what you must do

​Notes you must know

How billing works

Dashboard-managed paymaster config (new flow)

Step 1: Create a Paymaster client (v2)

Step 2: Call `sendUserOperation` (paymaster + paymasterContext)

Step 3: Sponsor mode (native gas sponsorship)

Step 4: ERC20 (token) mode

Required `paymasterContext` fields

`paymasterContext` field definitions (focused)

`mode`

`tokenAddress` (required in `mode: "token"`)

`treasury` (dashboard-configured)

`constantFee` (dashboard-configured)

Example `paymasterContext` (token mode)

ERC20 approval: what you must do

Notes you must know