ERC-20 paymaster

The ERC-20 paymaster flow lets users pay gas in tokens like ASTR or USDC instead of holding native ETH. The Startale Token Paymaster quotes the cost in tokens, the user (or your dapp) approves the spend once, and every subsequent UserOperation charges the token directly.

Source: StartaleGroup/scs-aa-sdk. Token addresses for each network are listed in Supported networks.

How it works

1. Build the token-paymaster client

The client looks like the sponsored client, except paymasterContext.token replaces paymasterContext.paymasterId.

import { http } from "viem"
import {
  createSCSPaymasterClient,
  createSmartAccountClient,
} from "@startale-scs/aa-sdk"

const paymasterClient = createSCSPaymasterClient({
  transport: http(process.env.PAYMASTER_URL!),
})

const tokenAccountClient = createSmartAccountClient({
  account,
  transport: http(process.env.BUNDLER_URL!),
  client: publicClient,
  paymaster: paymasterClient,
  paymasterContext: {
    token: "0xfF0CBFbA43a1Ce2B8d72B2f3121558BcBd4B03a6", // USDC on Soneium Minato
  },
})

Field	Type	Notes
`paymasterContext.token`	`Address`	The ERC-20 used to pay gas. Must be one of the supported tokens on the target network.

2. Quote the cost in tokens

Before sending a UserOperation, ask the paymaster for the cost across the tokens you support. getTokenPaymasterQuotes returns one entry per token plus a list of unsupported addresses you passed in.

const quotes = await tokenAccountClient.getTokenPaymasterQuotes({
  userOp: {
    calls: [{ to: targetAddress, data: callData, value: 0n }],
  },
  tokens: [
    "0xfF0CBFbA43a1Ce2B8d72B2f3121558BcBd4B03a6", // USDC
    "0x26e6f7c7047252DdE3dcBF26AA492e6a264Db655", // ASTR
  ],
})

for (const quote of quotes.feeQuotes) {
  console.log(quote.symbol, quote.maxGasFee, quote.maxGasFeeUSD, quote.exchangeRate)
}

Field on each `feeQuote`	What it means
`symbol`, `decimal`, `tokenAddress`, `logoUrl`	Display metadata for the token.
`maxGasFee`	Maximum cost in token base units (already factoring `decimal`).
`maxGasFeeUSD`	The same maximum, denominated in USD for display.
`exchangeRate`	Token-to-native rate the paymaster used for the quote.
`premiumPercentage`	Spread the paymaster adds on top of the raw conversion.
`validUntil`	Unix timestamp; quote expires after this point.

Show the user a token picker built from feeQuotes. Disable the entries in quotes.unsupportedTokens so they cannot be selected.

3. Send the UserOperation

Once the user picks a token, send the UserOperation with the token-paymaster client. The SDK takes care of the approval flow and packing the token into paymasterAndData.

const hash = await tokenAccountClient.sendTokenPaymasterUserOp({
  calls: [
    {
      to: targetAddress,
      data: callData,
      value: 0n,
    },
  ],
  feeTokenAddress: chosenTokenAddress,
})

const receipt = await tokenAccountClient.waitForUserOperationReceipt({ hash })

Symbol	Source	Role
`sendTokenPaymasterUserOp`	`@startale-scs/aa-sdk`	One-shot helper that approves the token (if needed), prepares the UserOperation with the token paymaster, and submits it.
`prepareTokenPaymasterUserOp`	`@startale-scs/aa-sdk`	Lower-level helper that returns the unsigned UserOperation if you need to inspect it before signing.

Common errors

Error	Likely cause	Fix
`unsupported token`	The token is not listed for the network.	Use one of the addresses in Supported networks.
`insufficient allowance`	The smart account has not approved the paymaster to spend the token.	Use `sendTokenPaymasterUserOp`, which inserts the approval automatically.
`quote expired`	The user took longer than `validUntil` to sign.	Re-quote and re-prompt.

Next steps

Supported tokens

Look up the exact token address for the network you target.

Contract interactions

Combine token gas with batched calls.

Smart sessions

Pair token gas with scoped sessions for high-frequency UX.

Overview

Getting started

Tutorials

Auth providers

Advanced

EIP-7702

Resources

FAQ

How it works

1. Build the token-paymaster client

2. Quote the cost in tokens

3. Send the UserOperation

Common errors

Next steps

Sponsored paymaster

Supported tokens

Contract interactions

Smart sessions

​How it works

​1. Build the token-paymaster client

​2. Quote the cost in tokens

​3. Send the UserOperation

​Common errors

​Next steps

Sponsored paymaster

Supported tokens

Contract interactions

Smart sessions

How it works

1. Build the token-paymaster client

2. Quote the cost in tokens

3. Send the UserOperation

Common errors

Next steps