Paymaster API V3 RPC Methods

JSON-RPC API reference for Candide's Paymaster V3 service.

info

Visit the dashboard to get an API key for Candide's Paymaster. Looking for V2?

Entrypoint V0.7

pm_supportedERC20Tokens

Gets supported ERC-20 Tokens for gas payments, along side the paymaster metadata

Invocation

{ "method": "pm_supportedERC20Tokens", "params": [entrypoint: string] }

Return

{ 
  "result": {
    paymasterMetadata: {
      name: string,
      description: string,
      icons: string[],
      address: string,
      sponsoredEventTopic: string,
      dummyPaymasterAndData: {
        paymaster: string,
        paymasterData: string,
        paymasterVerificationGasLimit: string,
        paymasterPostOpGasLimit: string
    },
    },
    tokens: [{
      name: string,
      symbol: string,
      address: string,
      decimals: number,
      exchangeRate: string,
    }]
  } 
}

Example Request

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "pm_supportedERC20Tokens",
  "params": ["0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789"]
}

Example Response

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "paymasterMetadata": {
      "name": "Candide Paymaster",
      "description": "Candide Paymaster a fast, secure and feature-rich 4337 Paymaster",
      "icons": [],
      "address": "0x7e3393ebA62DA6f555a5341E079e0F6585CE8c56",
      "sponsoredEventTopic": "0x13..fa1",
      "dummyPaymasterAndData": {
        "paymaster": "0x...",
        "paymasterData": "0x...",
        "paymasterVerificationGasLimit": "0x...",
        "paymasterPostOpGasLimit": "0x..."
      }
    },
    "tokens": [{
      "name": "Maker DAI",
      "symbol": "DAI",
      "address": "0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1",
      "decimal": "0x12",
      "exchangeRate": "0x0ddeb609310c89b1"
    }]
  }
}

Response Types

Paramater	Type
paymasterMetadata	Object key type description name string Paymaster Name description string A short description for the paymaster service icons string[] Icons associated with the paymaster service address string Paymaster Contract Address sponsoredEventTopic string Emitted topic event if a paymaster is being used dummyPaymasterAndData key type description paymaster string Address of paymaster contract paymasterData string Data for paymaster paymasterVerificationGasLimit string The amount of gas to allocate for the paymaster validation code paymasterPostOpGasLimit string The amount of gas to allocate for the paymaster post-operation code Dummy values to use for estimating user operation gas before sponsorship sponsorMetadata key type description name string Name of Sponsor who is sponsoring the Gas Policy description string A short description of the sponsor url string Website of the Sponsor icons string[] Logos or Icons that the Sponsor is using to promote their Gas Policy Information about the Gas Policy Sponsor
tokens	Object[] key type description name string Name of the ERC-20 Token symbol string Token Symbol address string Token contract address decimal number Decimals of token exchangeRate string Exchange rate of token

pm_sponsorUserOperation

Sends a UserOperation to a paymaster for off-chain verification. If approved, it will return the paymasterData. It will also return gas overrides when the mode for gas sponsorship uses a Gas Policy.

• ERC-20s Gas Payments: No gas overrides are returned
• Gas Policies: Mandatory callGasLimit, verificationGasLimit, preVerificationGas, maxFeePerGas, and maxPriorityFeePerGas fields are returned.

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.

If the paymaster rejects the UserOperation, it returns a standard JSON-RPC error with the reason.

Invocation

{ "method": "pm_sponsorUserOperation", "params": [userOperation: object, entrypoint: string, context: object] }

Return

{
  "result": {
    paymaster: string,
    paymasterData: string,
    paymasterVerificationGasLimit: string,
    paymasterPostOpGasLimit: string,
    callGasLimit?: string,
    verificationGasLimit?: string,
    preVerificationGas?: string,
    maxFeePerGas?: string,
    maxPriorityFeePerGas?: string,
    sponsorMetadata?: {
      name: string,
      description: string,
      url: string,
      icons: string[],
    }
  } 
}

Example Request

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "pm_sponsorUserOperation",
    "params": [
    {
      "sender": "0x2c298CcaFF..c236fCC66dB2",
      "nonce": "0x17",
      "factory": "0x..",
      "factoryData": "0xf3....0000",
      "callData": "0xf3....0000",
      "callGasLimit": "0x12a87",
      "verificationGasLimit": "0x1a332",
      "preVerificationGas": "0xe95c",
      "maxFeePerGas": "0x5f4ecdc0",
      "maxPriorityFeePerGas": "0x59682f00",
      "paymaster": "0x..",
      "paymasterVerificationGasLimit": "0x..",
      "paymasterPostOpGasLimit": "0x..",
      "paymasterAndData": "0x",
      "signature": "0x",
    },
    "0x0000000071727De22E5E9d8BAf0edAc6f37da032",
    { "sponsorshipPolicyId" : "1234" } // sponsorshipPolicyId key value field is optional if using a private gas policy.
  ]
}

Example Response

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "paymasterAndData": "0x....",
    "callGasLimit": "0x...",
    "verificationGasLimit": "0x...",
    "preVerificationGas": "0x..",
    "maxFeePerGas": "0x..",
    "maxPriorityFeePerGas": "0x..",
    "sponsorMetadata": {
      "name": "Aave",
      "description": "Open Source Liquidity Protocol",
      "url": "https://app.aave.com/",
      "icons": ["https://aave.com/aave-2030-header.svg"],
    }
  }
}

Request Types

Paramater	Type
userOperation	Object key type description sender string The account making the operation nonce string Anti-replay parameter (see “Semi-abstracted Nonce Support” ) factory string account factory, only for new accounts factoryData string data for account factory (only if account factory exists) callData string The data to pass to the sender during the main execution call callGasLimit bigint The amount of gas to allocate the main execution call verificationGasLimit bigint The amount of gas to allocate for the verification step preVerificationGas bigint Extra gas to pay the bunder maxFeePerGas bigint Maximum fee per gas (similar to EIP-1559 max_fee_per_gas) maxPriorityFeePerGas bigint Maximum priority fee per gas (similar to EIP-1559 max_priority_fee_per_gas) paymaster string Address of paymaster contract, (or empty, if account pays for itself) paymasterVerificationGasLimit string The amount of gas to allocate for the paymaster post-operation code paymasterPostOpGasLimit string The amount of gas to allocate for the paymaster post-operation code paymasterData string Data for paymaster (only if paymaster exists) signature string Data passed into the account to verify authorization
entrypoint	Type Description string Entrypoint address
context	Object: This argument contains information about the specific paymaster implementation you are using. If use paying gas in ERC-20 Tokens, pass the token address. key type description token string? ERC20 token address, if paying gas in erc-20 tokens (optional) sponsorshipPolicyId string? Sponsorship Policy ID if using a private gas policy (optional)

Response Type

key	type	description
paymaster	string	Address of paymaster contract, (or empty, if account pays for itself)
paymasterVerificationGasLimit	string	The amount of gas to allocate for the paymaster post-operation code
paymasterPostOpGasLimit	string	The amount of gas to allocate for the paymaster post-operation code
paymasterData	string	Data for paymaster (only if paymaster exists)
callGasLimit	string	The amount of gas to allocate the main execution call
verificationGasLimit	string	The amount of gas to allocate for the verification step
preVerificationGas	string	Extra gas to pay the bunder
maxFeePerGas	string	Maximum fee per gas (similar to EIP-1559 max_fee_per_gas)
maxPriorityFeePerGas	string	Maximum priority fee per gas (similar to EIP-1559 max_priority_fee_per_gas)

pm_supportedEntryPoints

Returns the entryPoint addresses supported by the paymaster.

Invocation

{ "method": "pm_supportedEntryPoints", "params": [] }

Return

{ "result": string[] }

Example Request

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "pm_supportedEntryPoints",
  "params": []
}

Example Response

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": ["0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789", "0x0000000071727de22e5e9d8baf0edac6f37da032"] // Entrypoint addresses
}

Response Type

key	type	description
entrypoints	string[]	The EntryPoint Addresses that the paymaster is supporting

pm_chainId

Get Chain ID asks the paymaster service to return the chain_id it currently supports

Invocation

{ "method": "pm_chainId", "params": [] }

Return

{ "result": number }

Example Request

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "pm_chainId",
  "params": []
}

Example Response

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": 1
}

Response Type

Paramater	Type	Description
chainId	number	Chain ID that the paymaster supports

Entrypoint V0.6

pm_supportedERC20Tokens

Gets supported ERC-20 Tokens for gas payments, along side the paymaster metadata

Invocation

{ "method": "pm_supportedERC20Tokens", "params": [entrypoint: string] }

Return

{ 
  "result": {
    paymasterMetadata: {
      name: string,
      description: string,
      icons: string[],
      address: string,
      sponsoredEventTopic: string,
      dummyPaymasterAndData: string,
    },
    tokens: [{
      name: string,
      symbol: string,
      address: string,
      decimals: number,
      exchangeRate: string,
    }]
  } 
}

Example Request

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "pm_supportedERC20Tokens",
  "params": ["0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789"]
}

Example Response

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "paymasterMetadata": {
      "name": "Candide Paymaster",
      "description": "Candide Paymaster a fast, secure and feature-rich 4337 Paymaster",
      "icons": [],
      "address": "0x7e3393ebA62DA6f555a5341E079e0F6585CE8c56",
      "sponsoredEventTopic": "0x13..fa1",
      "dummyPaymasterAndData": "0x69...135",
    },
    "tokens": [{
      "name": "Maker DAI",
      "symbol": "DAI",
      "address": "0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1",
      "decimal": "0x12",
      "exchangeRate": "0x0ddeb609310c89b1"
    }]
  }
}

Response Types

Paramater	Type
paymasterMetadata	Object key type description name string Paymaster Name description string A short description for the paymaster service icons string[] icons associated with the paymaster service address string Paymaster Contract Address sponsoredEventTopic string Emmited topic event if a paymaster is being used dummyPaymasterAndData string Dummy value to use for estimating userop gas before sponsorship
tokens	Object[] key type description name string Name of the ERC-20 Token symbol string Token Symbol address string Token contract address decimal number Decimals of token exchangeRate string Exchange rate of token

pm_sponsorUserOperation

Sends a UserOperation to a paymaster for off-chain verification. If approved, it will return the paymasterData. It will also return gas overrides when the mode for gas sponsorship uses a Gas Policy.

• ERC-20s Gas Payments: No gas overrides are returned
• Gas Policies: Mandatory callGasLimit, verificationGasLimit, preVerificationGas, maxFeePerGas, and maxPriorityFeePerGas fields are returned.

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.

If the paymaster rejects the UserOperation, it returns a standard JSON-RPC error with the reason.

Invocation

{ "method": "pm_sponsorUserOperation", "params": [userOperation: object, entrypoint: string, context: object] }

Return

{
  "result": {
    paymasterAndData: string,
    callGasLimit?: string,
    verificationGasLimit?: string,
    preVerificationGas?: string,
    maxFeePerGas?: string,
    maxPriorityFeePerGas?: string,
    sponsorMetadata?: {
      name: string,
      description: string,
      url: string,
      icons: string[],
    }
  } 
}

Example Request

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "pm_sponsorUserOperation",
    "params": [
    {
      "sender": "0x2c298CcaFF..c236fCC66dB2",
      "nonce": "0x17",
      "initCode": "0x",
      "callData": "0xf3....0000",
      "callGasLimit": "0x12a87",
      "verificationGasLimit": "0x1a332",
      "preVerificationGas": "0xe95c",
      "maxFeePerGas": "0x5f4ecdc0",
      "maxPriorityFeePerGas": "0x59682f00",
      "paymasterAndData": "0x",
      "signature": "0x",
    },
    "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789",
    { "sponsorshipPolicyId" : "1234" } // sponsorshipPolicyId key value field is optional if using a private gas policy. 
  ]
}

Example Response

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "paymasterAndData": "0x....",
    "callGasLimit": "0x...",
    "verificationGasLimit": "0x...",
    "preVerificationGas": "0x..",
    "maxFeePerGas": "0x..",
    "maxPriorityFeePerGas": "0x..",
    "sponsorMetadata": {
      "name": "Aave",
      "description": "Open Source Liquidity Protocol",
      "url": "https://app.aave.com/",
      "icons": ["https://aave.com/aave-2030-header.svg"],
    }
  }
}

Request Types

Paramater	Type
userOperation	Object key type description sender string The account making the operation nonce string Anti-replay parameter (see “Semi-abstracted Nonce Support” ) initCode string The initCode of the account (needed if and only if the account is not yet on-chain and needs to be created) callData string The data to pass to the sender during the main execution call callGasLimit bigint The amount of gas to allocate the main execution call verificationGasLimit bigint The amount of gas to allocate for the verification step preVerificationGas bigint The amount of gas to pay for to compensate the bundler for pre-verification execution and calldata maxFeePerGas bigint Maximum fee per gas (similar to EIP-1559 max_fee_per_gas) maxPriorityFeePerGas bigint Maximum priority fee per gas (similar to EIP-1559 max_priority_fee_per_gas) paymasterAndData string Address of paymaster sponsoring the transaction, followed by extra data to send to the paymaster (empty for self-sponsored transaction). Revolves to '0x' if not using a paymaster, and a paymasterDummyData when estimating gas signature string The signature for the userOperation. It is the data passed into the account along with the nonce during the verification step. Resolves to '0x' when the user did not provide their signature yet
entrypoint	Type Description string Entrypoint address
context	Object: This argument contains information about the specific paymaster implementation you are using. If use paying gas in ERC-20 Tokens, pass the token address. key type description token string? ERC20 token address, if paying gas in erc-20 tokens (optional) sponsorshipPolicyId string? Sponsorship Policy ID if using a private gas policy (optional)

Response Type

key	type	description
paymasterAndData	string	Paymaster address and data required to pass paymaster contract validation
callGasLimit	string?	The amount of gas to allocate the main execution call. Optional return.
verificationGasLimit	string?	The amount of gas to allocate for the verification step. Optional return.
preVerificationGas	string?	The amount of gas to pay for to compensate the bundler for pre-verification execution and calldata. Optional return.
maxFeePerGas	string?	Maximum fee per gas (similar to EIP-1559 max_fee_per_gas). Optional Return.
maxPriorityFeePerGas	string?	Maximum priority fee per gas (similar to EIP-1559 max_priority_fee_per_gas). Optional Return

pm_supportedEntryPoints

Returns the entryPoint addresses supported by the paymaster.

Invocation

{ "method": "pm_supportedEntryPoints", "params": [] }

Return

{ "result": string[] }

Example Request

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "pm_supportedEntryPoints",
  "params": []
}

Example Response

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": ["0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789", "0x0000000071727de22e5e9d8baf0edac6f37da032"] // Entrypoint addresses
}

Response Type

key	type	description
entrypoints	string[]	The EntryPoint Addresses that the paymaster is supporting

pm_chainId

Get Chain ID asks the paymaster service to return the chain_id it currently supports

Invocation

{ "method": "pm_chainId", "params": [] }

Return

{ "result": number }

Example Request

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "pm_chainId",
  "params": []
}

Example Response

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": 1
}

Response Type

Paramater	Type	Description
chainId	number	Chain ID that the paymaster supports