Pay gas with any token

The examples on this page use @alchemy/wallet-apis (v5.x.x). If you're using @account-kit/wallet-client (v4.x.x), the client setup looks like this:

import { LocalAccountSigner } from "@aa-sdk/core";
import { createSmartWalletClient } from "@account-kit/wallet-client";
import { alchemy, sepolia } from "@account-kit/infra";
 
const signer = LocalAccountSigner.privateKeyToAccountSigner("0xYOUR_PRIVATE_KEY" as const);
 
export const client = createSmartWalletClient({
  transport: alchemy({ apiKey: "YOUR_API_KEY" }),
  chain: sepolia,
  signer,
  account: signer.address, // can also be passed per action as `from` or `account`
  // Optional: sponsor gas for your users (see "Sponsor gas" guide)
  policyId: "YOUR_POLICY_ID", 
});

Key v4.x.x differences:

• Account address must be specified on the client or per action (from or account). In v5.x.x, the client automatically uses the owner's address as the account address via EIP-7702.
• Chain imports come directly from @account-kit/infra instead of viem/chains.
• Numeric values use hex strings: value: "0x0" instead of value: BigInt(0).
• In v4.x.x, the paymaster capability on prepareCalls or sendCalls is called paymasterService instead of paymaster, or you can set the policyId directly on the client.
• Owners use LocalAccountSigner / WalletClientSigner from @aa-sdk/core. In v5.x.x, a viem LocalAccount or WalletClient is used directly.

See the full migration guide for a complete cheat sheet.

Pay gas with any token also works with the prepare calls methods in the various frameworks. Usage of the capability will be the same as when using send calls. It is recommended to use prepare calls if you want to inspect the prepared call prior to prompting the user for signature.

The configured mode determines when the user’s token payment occurs.

[Recommended] Post-Operation

• No upfront allowance is required.
• If the paymaster does not already have a sufficient allowance, a token approval is injected into the same atomic calls batch as your operations. The paymaster contract pulls the token after execution.
• When an approval is injected into the batch, if any call reverts, the approval is also reverted. The paymaster cannot collect the token payment and you (the policy owner) pay the gas cost without receiving token compensation.
• If a sufficient allowance already exists (e.g., from threshold mode or a prior approval), no approval is injected and the paymaster can collect payment even if the batch reverts.

Pre-Operation:

• The paymaster contract must have an allowance prior to the operation.
• This can be done either through a prior call to approve() or by using an ERC-7597 Permit signature.
• Because the token transfer occurs during validation (before execution), the paymaster collects payment regardless of whether the operation reverts.
• If the required allowance isn’t in place when the transaction is submitted, it will be rejected.

Choosing a mode:

Use post-operation mode when your operations are unlikely to revert. This mode:

• Is the most gas efficient as it requires a single transfer.
• Works with all ERC-20 tokens.
• Requires a single signature from the user.

Use pre-operation mode when your operations may revert. Because the token transfer happens before execution, the paymaster is always compensated regardless of the execution outcome. This is the safer choice for:

• Swaps or other operations with dynamic outcomes
• Any operation where revert conditions are difficult to predict ahead of time
• High-value gas operations where uncompensated gas costs are unacceptable

To show users the gas cost in their chosen gas token prior to signing and sending their request, use the prepareCalls hook/action/api over the sendCalls version as sendCalls doesn't surface the fee payment information during sign and send.

The return type of prepareCalls contains a feePayment field containing fee information. Display this information to users prior to signing the operation. For example:

  "feePayment": {
    "sponsored": false,
    "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "maxAmount": "0x1d33"
  }

Calling prepareCalls using the token gas payment capability counts against your policy's pending total. If you intend on making many calls to surface the best price, set the onlyEstimation parameter for estimation, and then remove only when the user intends to sign the result.

The Wallet APIs can automatically inject the required token approvals into the operation. There are two modes for post-operation approvals:

Exact mode (autoApprove: true)

The precise token amount needed is calculated after gas estimation and approved exactly — no more, no less. If the account already has sufficient allowance, no approval is added.

This is ideal when you want minimal token exposure to the paymaster contract, don't want to estimate gas and figure out approval amounts yourself, or when users send infrequent transactions.

Threshold mode (autoApprove: { below, amount })

An approval is only injected when the existing allowance drops below below, approving the fixed amount you configure. This avoids re-approving on every operation, which saves gas for frequent transactions.

Set below high enough to reasonably cover the gas cost for your most expensive operations. Set amount to a value you feel comfortable maintaining as an allowance on the paymaster contract. Setting a large amount is not recommended for security purposes.

When autoApprove: true is set, the following steps are performed during request preparation:

1. Injects a sentinel approval — A temporary approve(paymaster, maxUint256) call is prepended to your calls so gas estimation accounts for the approval's execution cost.
2. Estimates gas — The full transaction (including the sentinel) is sent through gas estimation.
3. Quotes the token cost — The paymaster contract returns an exchange rate, and the server calculates the exact token amount: (maxNativeGasCost × exchangeRate) / scaler.
4. Checks current allowance — If the account's existing allowance already covers the quoted amount, the approval is stripped entirely. Otherwise, it's updated to approve only the exact amount.
5. Returns the final transaction — The callData is re-encoded with the finalized calls.

When an approval is needed, it is prepended to the calls array and executed atomically in the same transaction. The approved amount is the exact token cost quoted by the paymaster contract, not a fixed or maximum value.

In pre-operation mode, you can set the paymaster service capability to automatically return a request for a Permit signature using the erc20.preOp.autoPermit field. This permit will allow an allowance to be set on the paymaster contract from the sender prior to any token transfers needed during pre operation.

To be eligible for auto-injected permits, the payment gas token must:

1. Be ERC-7597 compliant.
2. Expose a version() function.
3. Utilize the canonical DOMAIN_SEPARATOR outlined in ERC-2612.

If the user already has an allowance on the paymaster contract, the normal flow is used. If the user needs an approval, the following steps inject the permit:

1. The prepare request returns a signature request for the paymaster permit.
2. The user signs the permit request and the signature request back in a second prepare request.
3. The permit signature is injected into the paymaster contract calldata, and a normal operation is returned.
4. The user proceeds as normal, signing and sending the operation.