Skip to main content

CandidePaymaster (Advanced)

CandidePaymaster is the client for Candide-hosted paymasters. For one-shot sponsorship and ERC-20 gas, start with the standard Erc7677Paymaster instead. Use CandidePaymaster when you need the EntryPoint v0.9 two-phase commit -> sign -> finalize flow, which lets the user sign while the paymaster prepares its signature, or Candide's token and metadata APIs below.

Methods at a Glance​

MethodSignatureReturns
constructornew CandidePaymaster(rpc: string | Transport)CandidePaymaster
createSponsorPaymasterUserOperationcreateSponsorPaymasterUserOperation(smartAccount, userOperation, bundlerRpc, sponsorshipPolicyId?, context?, overrides?)Promise<{ userOperation; sponsorMetadata? }>
createTokenPaymasterUserOperationcreateTokenPaymasterUserOperation(smartAccount, userOperation, tokenAddress, bundlerRpc, context?, overrides?)Promise<{ userOperation; tokenQuote? }>
fetchSupportedERC20TokensAndPaymasterMetadatafetchSupportedERC20TokensAndPaymasterMetadata(entrypoint?)Promise<SupportedERC20TokensAndMetadataWithExchangeRate>
calculateUserOperationErc20TokenMaxGasCostcalculateUserOperationErc20TokenMaxGasCost(smartAccount, userOperation, erc20TokenAddress, overrides?)Promise<bigint>
decodeTokenQuote (static)CandidePaymaster.decodeTokenQuote(userOperation, nodeRpcUrl, overrides?)Promise<DecodedTokenQuote | null>
getPaymasterMetaDatagetPaymasterMetaData(entrypoint)Promise<PaymasterMetadata | null>
getSupportedEntrypointsgetSupportedEntrypoints()Promise<string[]>
isSupportedERC20TokenisSupportedERC20Token(erc20TokenAddress, entrypoint?)Promise<boolean>
getSupportedERC20TokenDatagetSupportedERC20TokenData(erc20TokenAddress, entrypoint?)Promise<ERC20Token | null>
fetchTokenPaymasterExchangeRatefetchTokenPaymasterExchangeRate(erc20TokenAddress, entrypoint?)Promise<bigint>

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/11155111";
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/11155111";
const paymaster: CandidePaymaster = new CandidePaymaster(paymasterRPC);
const sponsorshipPolicyId = '1234';

// Use createUserOperation() to help you construct a userOp
const userOperation = await 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, SafeMultiChainSigAccountV1 as SafeAccount } from "abstractionkit";

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

const supportedERC20Tokens = await paymaster.fetchSupportedERC20TokensAndPaymasterMetadata(SafeAccount.DEFAULT_ENTRYPOINT_ADDRESS);
Example Response
{
tokens: [
{
name: 'Candide Test Token',
symbol: 'CTT',
address: '0xFa5854FBf9964330d761961F46565AB7326e5a3b',
decimals: 18,
exchangeRate: 1000000000000000000n
},
{
name: 'Tether',
symbol: 'USDT',
address: '0xd077a400968890eacc75cdc901f0356c943e4fdb',
decimals: 6,
exchangeRate: 2075579999n
}
],
paymasterMetadata: {
name: 'CANDIDE Paymaster',
description: 'CANDIDE Paymaster a fast, secure and feature-rich 4337 Paymaster',
icons: [],
address: '0xca944fb73fa5191969014ded9bb075381d59c7de',
sponsoredEventTopic: '0xa050a122b4c0e369e3385eb6b7cccd8019638b2764de67bec0af99130ddf8471',
dummyPaymasterAndData: {
paymaster: '0xca944fb73fa5191969014ded9bb075381d59c7de',
paymasterVerificationGasLimit: 70000n,
paymasterPostOpGasLimit: 75000n,
paymasterData: '0x0001000000000000ffff000000000000000000000000000000000000000000000000000000000000ffff010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101011c'
}
}
}

createTokenPaymasterUserOperation​

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

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.

By default the prepended approve grants twice the quoted token cost. Set overrides.approveAmount (a bigint in the token's smallest unit) to choose the allowance yourself, for example to cap it at a maximum fee the user agreed to. The method throws a PAYMASTER_ERROR if the amount is below the quoted token cost, with both values in the error's context. The token cost is quoted during the call, so it isn't known beforehand. The finalize signing phase builds no approval and ignores this override.

The returned tokenQuote reports the paymaster the prepended approve was granted to (paymaster) and the allowance it set (approveAmount), so you can compare the spender against your configured paymaster without decoding callData. The method throws a PAYMASTER_ERROR if the final paymaster data is missing a paymaster or names a different one than the approval spender.

Usage​

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

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

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

// Use createUserOperation() to help you construct a userOp
let userOperation = await 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: '0x9371252D5001d2aF35b1E69Fd33e268b4357D424',
nonce: 1n,
callData: '0x541d63c8...095ea7b3...',
callGasLimit: 191545n,
verificationGasLimit: 135864n,
preVerificationGas: 150767n,
maxFeePerGas: 82n,
maxPriorityFeePerGas: 60n,
signature: '0x00ffffffffffffffffffffffff47003599ffa7e9...',
factory: null,
factoryData: null,
paymaster: '0xca944fb73fa5191969014ded9bb075381d59c7de',
paymasterVerificationGasLimit: 70000n,
paymasterPostOpGasLimit: 75000n,
paymasterData: '0x0000000000006af4e929...',
eip7702Auth: null
},
tokenQuote: {
token: '0xFa5854FBf9964330d761961F46565AB7326e5a3b',
exchangeRate: 1000000000000000000n,
tokenCost: 51100432n,
paymaster: '0xca944fb73fa5191969014ded9bb075381d59c7de',
approveAmount: 102200864n
}
}

Source code​

createTokenPaymasterUserOperation

calculateUserOperationErc20TokenMaxGasCost​

Converts a UserOperation's maximum gas cost to the ERC-20 token at the paymaster's current exchange rate. It uses the same calculation as tokenQuote.tokenCost, so it leaves out Candide's post-operation overhead and markup. For the most a finished UserOperation can charge the user, use decodeTokenQuote.

Usage​

import { CandidePaymaster } from "abstractionkit";

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

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

const cost = await paymaster.calculateUserOperationErc20TokenMaxGasCost(
smartAccount,
userOperation,
erc20TokenAddress,
);
Example Response
35424864n

Source code​

calculateUserOperationErc20TokenMaxGasCost

decodeTokenQuote​

CandidePaymaster.decodeTokenQuote is the same static method as Erc7677Paymaster.decodeTokenQuote. See decodeTokenQuote on the Paymaster page.

Advanced Methods​

getPaymasterMetaData​

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

Usage​

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

const paymasterRPC="https://api.candide.dev/public/v3/11155111";
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: '0xca944fb73fa5191969014ded9bb075381d59c7de',
sponsoredEventTopic: '0xa050a122b4c0e369e3385eb6b7cccd8019638b2764de67bec0af99130ddf8471',
dummyPaymasterAndData: {
paymaster: '0xca944fb73fa5191969014ded9bb075381d59c7de',
paymasterVerificationGasLimit: 70000n,
paymasterPostOpGasLimit: 75000n,
paymasterData: '0x0001000000000000ffff000000000000000000000000000000000000000000000000000000000000ffff010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101011c'
}
}

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/11155111";
const paymaster: CandidePaymaster = new CandidePaymaster(paymasterRPC);

const paymasterResult = await paymaster.getSupportedEntrypoints();
Example Response
[
'0x5ff137d4b0fdcd49dca30c7cf57e578a026d2789',
'0x0000000071727de22e5e9d8baf0edac6f37da032',
'0x4337084d9e255ff0702461cf8895ce9e3b5ff108',
'0x433709009b8330fda32311df1c2afa402ed8d009'
]

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/11155111";
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/11155111";

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
}

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/11155111";
const paymaster: CandidePaymaster = new CandidePaymaster(paymasterRPC);

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

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

Source code​

fetchTokenPaymasterExchangeRate

createPaymasterUserOperation​

Private on CandidePaymaster

CandidePaymaster.createPaymasterUserOperation is a private helper, not part of the public API. Use createSponsorPaymasterUserOperation for gas sponsorship or createTokenPaymasterUserOperation for ERC-20 token payment instead.

Erc7677Paymaster exposes a public method with the same name; that one is the recommended entry point for the standard ERC-7677 flow and is documented on the Paymaster page.

Source code​

createPaymasterUserOperation

Error Handling​

CandidePaymaster throws the same errors as Erc7677Paymaster. See Error Handling on the Paymaster page.