Paymaster RPC Methods

JSON-RPC API reference for Candide's Verifying Paymaster service

info

Visit dashboard to get an API key for Candide's Paymaster.

pm_supportedERC20Tokens

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

Invocation

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

Return

{ "result": { paymasterMetadata, tokens } }

Example Request

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

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": [
        {
          "symbol": "DAI",
          "address": "0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1",
          "decimal": "0x12",
          "fee": "0x0",
          "exchangeRate": "0x0ddeb609310c89b1"
        }
      ]
    }
  }
}

Response Types

Paramater	Type
paymasterMetadata	Object Key Value 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 Value Type Description symbol string Token Symbol address string Token contract address decimal number Decimals of token fee bigint Gas fee in unit of of the token exchangeRate bigint 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 sponsoriship is FREE for the user.

• Pay Gas in ERC-20s: No gas overrides are returned
• FREE Gas: it may or may not provide mandatory preVerificationGas, maxFeePerGas, and maxPriorityFeePerGas fields.

If the paymaster rejects the UserOperation, it should not return a result but a standard JSON-RPC error with the reason.

info

Any gas overrides provided in the paymaster result MUST be used in the userop otherwise the paymaster signature won't work.

Invocation

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

Return

{
  "result": {
    paymasterAndData,
    preVerificationGas,
    maxFeePerGas,
    maxPriorityFeePerGas
  } 
}

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",
    { "token": "0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1" },
  ]
}

Example Response

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "paymasterAndData": "0x....",
    "preVerificationGas": "0x..",
    "maxFeePerGas": "0x..",
    "maxPriorityFeePerGas": "0x.."
  }
}

Request Types

Paramater	Type
userOperation	Object Key Value 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

Response Type

Key	Value Type	Description
paymasterAndData	string	Paymaster address and data required to pass paymaster contract validation
preVerificationGas	string	The amount of gas to pay for to compensate the bundler for pre-verification execution and calldata
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_supportedEntryPoint

Get supported EntryPoint returns the entryPoint address supported by the paymaster

Invocation

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

Return

{ "result": entrypoint }

Example Request

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

Example Response

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789" // Entrypoint address
}

Response Type

Paramater	Type	Description
entrypoint	string	EntryPoint Address 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": chainId }

Example Request

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

Example Response

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

Response Type

Paramater	Type	Description
chainId	string	Chain ID that the paymaster supports