Skip to main content

Paymaster

The CandidePaymaster class interacts with Candide's ERC-4337 Paymaster API.

Supports:

  • Gas sponsorship through Gas Policies
  • ERC-20 Token Sponsorship
  • Multi-EntryPoint

Usage​

Import​

import { CandidePaymaster } from "abstractionkit";

How to Use​

Initialize a Paymaster with your RPC URL. Get an API key from the dashboard.

paymaster.ts
import { CandidePaymaster } from "abstractionkit";

const paymasterRPC = "https://api.candide.dev/public/v3/sepolia";
const paymaster: CandidePaymaster = new CandidePaymaster(paymasterRPC);

Then consume Paymaster methods:

const supportedEntryPoints = await paymaster.getSupportedEntrypoints();

Methods​

createSponsorPaymasterUserOperation​

Returns the paymaster data if the the userOperation has a Gas Policy. Otherwise it returns an error message. Supports two types of Gas Policies:

  • Public Gas Policies: These are gas policies provided by third parties, which do not require a sponsorship policy ID.
  • Private Gas Policies: These require a sponsorship policy ID and can be used if no public gas policy matches the user operation.

Usage​

example.ts
import { CandidePaymaster } from "abstractionkit";

const paymasterRPC = "https://api.candide.dev/public/v3/sepolia";
const paymaster: CandidePaymaster = new CandidePaymaster(paymasterRPC);
const sponsorshipPolicyId = '1234';

// Use createUserOperation() to help you construct a userOp
const userOperation = smartAccount.createUserOperation(..)

const { userOperation: sponsoredUserOperation, sponsorMetadata } =
  await paymaster.createSponsorPaymasterUserOperation(
    smartAccount,
    userOperation,
    bundlerUrl,
    sponsorshipPolicyId, // optional
  );

Source code​

createSponsorPaymasterUserOperation

fetchSupportedERC20TokensAndPaymasterMetadata​

Returns a promise with the supported erc20 tokens and their exchange rate, along with the paymaster metadata

Usage​

example.ts
import { CandidePaymaster, SafeAccountV0_3_0 as SafeAccount } from "abstractionkit";

const paymasterRPC="https://api.candide.dev/public/v3/sepolia";
const paymaster = new CandidePaymaster(paymasterRPC);

const supportedERC20Tokens = await paymaster.fetchSupportedERC20TokensAndPaymasterMetadata(SafeAccount.DEFAULT_ENTRYPOINT_ADDRESS);
Example Response
{
  tokens: [
    {
      name: 'USD Coin',
      symbol: 'USDC',
      address: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831',
      decimals: 6,
      exchangeRate: 123n
    },
    {
      name: 'Tether USDT',
      symbol: 'USDT',
      address: '0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9',
      decimals: 6,
      exchangeRate: 123n
    },
    {
      name: 'Dai Stablecoin',
      symbol: 'DAI',
      address: '0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1',
      decimals: 18,
      exchangeRate: 123n
    }
  ],
  paymasterMetadata: {
    name: 'CANDIDE Paymaster',
    description: 'CANDIDE Paymaster a fast, secure and feature-rich 4337 Paymaster',
    icons: [],
    address: '0x8b1f6cb5d062aa2ce8d581942bbb960420d875ba',
    sponsoredEventTopic: '0xa050a122b4c0e369e3385eb6b7cccd8019638b2764de67bec0af99130ddf8471',
    dummyPaymasterAndData: {
      paymaster: '0x8b1f6cb5d062aa2ce8d581942bbb960420d875ba',
      paymasterVerificationGasLimit: '0xffff',
      paymasterPostOpGasLimit: '0xffff',
      paymasterData: '0x00010000000000ffff000000000000000000000000000000000000000000000000000000000000ffff010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101011c'
    }
  }
}

createTokenPaymasterUserOperation​

Estimates gas limits and returns the user operation with the paymaster data for ERC-20 Token sponsorship.

Token Approval Reset

Some tokens like USDT do not allow changing a non-zero allowance directly. For known tokens (e.g. USDT on Ethereum mainnet), the SDK automatically prepends an approve(0) call before the actual approval. You can also manually trigger this behavior for other tokens by setting resetApproval: true in the overrides.

The overrides parameter also accepts an entrypoint field, which allows you to manually specify the EntryPoint address instead of relying on auto-detection from the UserOperation structure.

Usage​

import { SafeAccountV0_3_0 as SafeAccount, CandidePaymaster } from "abstractionkit";

const paymasterRPC="https://api.candide.dev/public/v3/sepolia";
const erc20TokenAddress = "0xFa5854FBf9964330d761961F46565AB7326e5a3b"; // CTT test token
const bundlerRPC = "https://api.candide.dev/public/v3/sepolia";

const ownerPublicAddress = "0x2Ef844456580b6e1E22e1D584EBbC2467D9298B2"
const smartAccount = SafeAccount.initializeNewAccount([ownerPublicAddress])

// Use createUserOperation() to help you construct a userOp
let userOperation = smartAccount.createUserOperation(..);

const paymaster: CandidePaymaster = new CandidePaymaster(paymasterRPC);

const { userOperation: sponsoredUserOperation, tokenQuote } =
  await paymaster.createTokenPaymasterUserOperation(
    smartAccount,
    userOperation,
    erc20TokenAddress,
    bundlerRPC,
  );
userOperation = sponsoredUserOperation;
Example Response
{
  userOperation: {
    sender: '0xb8741a449d50ed0dcfe395287f85be152884c8d9',
    nonce: 10n,
    initCode: '0x',
    callData: '0x541d63c8...095ea7b3...',
    callGasLimit: 116807n,
    verificationGasLimit: 75441n,
    preVerificationGas: 50444n,
    maxFeePerGas: 66195658616n,
    maxPriorityFeePerGas: 120000n,
    paymasterAndData: '0x3fE285DcD76BCcE4Ac92d38A6F2F8E964041e020...',
    signature: '0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff'
  },
  tokenQuote: {
    token: '0xFa5854FBf9964330d761961F46565AB7326e5a3b',
    exchangeRate: 1001219705870085130n,
    tokenCost: 3391931975665260n,
  },
}

Source code​

createTokenPaymasterUserOperation

calculateUserOperationErc20TokenMaxGasCost​

Calculates the maximum gas cost in ERC-20 tokens for a given userOperation

Usage​

import { CandidePaymaster } from "abstractionkit";

const erc20TokenAddress = "0xFa5854FBf9964330d761961F46565AB7326e5a3b"; // CTT test token
// Use createUserOperation() to help you construct a userOp
const userOperation = smartAccount.createUserOperation(..)

const paymasterRPC="https://api.candide.dev/public/v3/sepolia";
const paymaster: CandidePaymaster = new CandidePaymaster(paymasterRPC);

const cost = await paymaster.calculateUserOperationErc20TokenMaxGasCost(
  userOperation,
  erc20TokenAddress,
);
Example Response
3391931975665260

Source code​

calculateUserOperationErc20TokenMaxGasCost

Advanced Methods​

getPaymasterMetaData​

Returns the metadata associated with the Paymaster, along with dummyPaymasterAndData useful for gas estimates

Usage​

example.ts
import { CandidePaymaster, SafeAccountV0_3_0 as SafeAccount } from "abstractionkit";

const paymasterRPC="https://api.candide.dev/public/v3/sepolia";
const paymaster: CandidePaymaster = new CandidePaymaster(paymasterRPC);

const paymasterResult = await paymaster.getPaymasterMetaData(SafeAccount.DEFAULT_ENTRYPOINT_ADDRESS);
Example Response
{
  name: 'CANDIDE Paymaster',
  description: 'CANDIDE Paymaster a fast, secure and feature-rich 4337 Paymaster',
  icons: [],
  address: '0x8b1f6cb5d062aa2ce8d581942bbb960420d875ba',
  sponsoredEventTopic: '0xa050a122b4c0e369e3385eb6b7cccd8019638b2764de67bec0af99130ddf8471',
  dummyPaymasterAndData: {
    paymaster: '0x8b1f6cb5d062aa2ce8d581942bbb960420d875ba',
    paymasterVerificationGasLimit: '0xffff',
    paymasterPostOpGasLimit: '0xffff',
    paymasterData: '0x00010000000000ffff000000000000000000000000000000000000000000000000000000000000ffff010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101011c'
  }
}

source code​

getPaymasterMetaData

getSupportedEntrypoints​

Returns the supported Entrypoints by the paymaster

Usage​

example.ts
import { CandidePaymaster } from "abstractionkit";

const paymasterRPC="https://api.candide.dev/public/v3/sepolia";
const paymaster: CandidePaymaster = new CandidePaymaster(paymasterRPC);

const paymasterResult = await paymaster.getSupportedEntrypoints();
Example Response
[
  '0x0000000071727De22E5E9d8BAf0edAc6f37da032',
  '0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789'
]

source code​

getSupportedEntrypoints

isSupportedERC20Token​

Checks if a particular ERC-20 token is accepted as gas payment by the paymaster. Returns a boolean

Usage​

example.ts
import { CandidePaymaster } from "abstractionkit";

const paymasterRPC="https://api.candide.dev/public/v3/sepolia";
const paymaster: CandidePaymaster = new CandidePaymaster(paymasterRPC);

const erc20TokenAddress = "0xFa5854FBf9964330d761961F46565AB7326e5a3b"; // CTT on sepolia testnet

const isSupported = await paymaster.isSupportedERC20Token(erc20TokenAddress);
Example Response
true

Source​

isSupportedERC20Token

getSupportedERC20TokenData​

Returns the token data given an erc20 address

Usage​

example.ts
import { CandidePaymaster } from "abstractionkit";

const paymasterRPC = "https://api.candide.dev/public/v3/sepolia";

const erc20TokenAddress = "0xFa5854FBf9964330d761961F46565AB7326e5a3b";
const paymaster: CandidePaymaster = new CandidePaymaster(paymasterRPC);
const erc20TokenData = await paymaster.getSupportedERC20TokenData(erc20TokenAddress);
Example Response
{
  name: 'Candide Test Token',
  symbol: 'CTT',
  address: '0xFa5854FBf9964330d761961F46565AB7326e5a3b',
  decimals: 18,
  fee: 0n,
  exchangeRate: 1001219705870085130n
}

Source code​

getSupportedERC20TokenData

fetchTokenPaymasterExchangeRate​

Fetches the current exchange rate for an ERC-20 token from the paymaster. The exchange rate represents the token cost per unit of native currency, used to calculate how much of the token is needed to cover gas fees.

Usage​

example.ts
import { CandidePaymaster } from "abstractionkit";

const paymasterRPC = "https://api.candide.dev/public/v3/sepolia";
const paymaster: CandidePaymaster = new CandidePaymaster(paymasterRPC);

const erc20TokenAddress = "0xFa5854FBf9964330d761961F46565AB7326e5a3b"; // CTT on sepolia testnet

const exchangeRate = await paymaster.fetchTokenPaymasterExchangeRate(erc20TokenAddress);
Example Response
1001219705870085130n

Source code​

fetchTokenPaymasterExchangeRate

createPaymasterUserOperation​

Internal Method

createPaymasterUserOperation is an internal method. Use createSponsorPaymasterUserOperation for gas sponsorship or createTokenPaymasterUserOperation for ERC-20 token payment instead.

Source code​

createPaymasterUserOperation

Erc7677Paymaster​

Erc7677Paymaster is a provider-agnostic ERC-7677 paymaster client. It speaks pm_getPaymasterStubData and pm_getPaymasterData, so it works with any compliant provider (Candide, Pimlico, Alchemy, or a self-hosted paymaster). Provider is auto-detected from the RPC URL; for Candide and Pimlico it also fetches exchange rates and paymaster addresses automatically for ERC-20 token flows.

If you are using Candide's paymaster and want features like parallel signing phases, prefer CandidePaymaster above. Use Erc7677Paymaster when you want a single client that can switch providers without code changes.

Usage​

Import​

import { Erc7677Paymaster } from "abstractionkit";
example.ts
import { Erc7677Paymaster } from "abstractionkit";

const bundlerRpc = "https://api.candide.dev/public/v3/sepolia";
const paymaster = new Erc7677Paymaster(bundlerRpc);

// Use createUserOperation() to help you construct a userOp
let userOperation = await smartAccount.createUserOperation(/* ... */);

const { userOperation: sponsoredOp } = await paymaster.createPaymasterUserOperation(
  smartAccount,
  userOperation,
  bundlerRpc,
  { sponsorshipPolicyId: "sp_..." }, // provider-specific context
);
userOperation = sponsoredOp;

ERC-20 token sponsorship​

Passing { token } in the context triggers the ERC-20 gas flow automatically. For Candide and Pimlico the exchange rate is fetched for you; for unknown providers, supply exchangeRate in the context. tokenQuote surfaces the exchange rate and max token cost applied to the UserOperation so you can display the charge to the user without a second round trip.

example.ts
const bundlerRpc = "https://api.candide.dev/public/v3/sepolia";
const usdcAddress = "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238"; // USDC on sepolia

// Candide or Pimlico (auto-detected): exchange rate fetched from the RPC
const { userOperation: tokenOp, tokenQuote } = await paymaster.createPaymasterUserOperation(
  smartAccount,
  userOperation,
  bundlerRpc,
  { token: usdcAddress },
);
userOperation = tokenOp;

// Unknown provider: supply exchangeRate (scaled by 1e18)
const { userOperation: tokenOp2 } = await paymaster.createPaymasterUserOperation(
  smartAccount,
  userOperation,
  bundlerRpc,
  { token: usdcAddress, exchangeRate: "1000000000000000000" },
);
userOperation = tokenOp2;

Source code​

Erc7677Paymaster

Last updated on by marc