RPC Methods

`eth` namespace

All RPC methods listed here are required to be compliant as an ERC-4337 bundler.

Send UserOperation

Used to submit a UserOperation to the mempool. It returns the userOpHash if the userOp was accepted otherwise returns an error.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_sendUserOperation",
  "params": [
    // UserOperation object
    {
      sender,
      nonce,
      initCode,
      callData,
      callGasLimit,
      verificationGasLimit,
      preVerificationGas,
      maxFeePerGas,
      maxPriorityFeePerGas,
      paymasterAndData,
      signature
    },

    // Supported EntryPoint address
    entryPoint
  ]
}

{
  "jsonrpc": "2.0",
  "id": 1,

  // UserOpHash
  "result": "0x..."
}

Estimate UserOperation gas

This method returns estimates for PreVerificationGas, VerificationGas, and CallGasLimit given a UserOperation and EntryPoint address. The signature field and current gas values will not be validated although there should be dummy values in place for the most reliable results (e.g. a signature with the correct length and format).

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_estimateUserOperationGas",
  "params": [
    // UserOperation object
    {
      sender,
      nonce,
      initCode,
      callData,
      callGasLimit,
      verificationGasLimit,
      preVerificationGas,
      maxFeePerGas,
      maxPriorityFeePerGas,
      paymasterAndData,
      signature
    },

    // Supported EntryPoint address
    entryPoint
  ]
}

{
  "jsonrpc": "2.0",
  "id": 1,

  // The return values are the hex strings for wei values.
  "result": {
        "PreVerificationGas": "0x..",
        "VerificationGas":    "0x..",
        "CallGasLimit":       "0x..",
    }
}

Get UserOperation by hash

Fetches the UserOperation and transaction context based on a given userOpHash returned from eth_sendUserOperation.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_getUserOperationByHash",
  "params": [userOpHash]
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_getUserOperationByHash",
  "params": [
    // UserOperation object
    {
      sender,
      nonce,
      initCode,
      callData,
      callGasLimit,
      verificationGasLimit,
      preVerificationGas,
      maxFeePerGas,
      maxPriorityFeePerGas,
      paymasterAndData,
      signature
    },

    // The EntryPoint address
    entryPoint,
    // The block number this UserOperation was included in
    blockNumber,
    // The block hash this UserOperation was included in
    blockHash,
    // The transaction this UserOperation was included in
    transactionHash,
  ]
}

Get UserOperation receipt

Fetches the UserOperation receipt based on a given userOpHash returned from eth_sendUserOperation.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_getUserOperationReceipt",
  "params": [userOpHash]
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_getUserOperationReceipt",
  "params": [
    // The hash of the UserOperation
    userOpHash,
    // The EntryPoint address
    entryPoint,
    // The contract account address
    sender,
    // nonce of the UserOperation
    nonce,
    // The paymaster address
    paymaster,
    // The actual amount paid for this UserOperation
    actualGasCost,
    // The total gas used by this UserOperation
    actualGasUsed,
    // Boolean value indicating if the execution completed without revert
    success,
    // If revert occurred, this is the reason
    reason,
    // logs generated by this UserOperation only
    logs,
    // The TransactionReceipt object for the entire bundle.
    receipt
  ]
}

Supported EntryPoints

Returns an array of supported EntryPoint addresses as specified in the configuration. The first element is the bundler's preferred EntryPoint.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_supportedEntryPoints",
  "params": []
}

{
  "jsonrpc": "2.0",
  "id": 1,

  // EntryPoint addresses
  "result": [
    "0x...",
    "0x..."
  ]
}

JSON-RPC errors

All error responses have the following format:

{
  "jsonrpc": "2.0",
  "id": 1
  "error": {
    code,
    message
  }
}

Below are the common error codes specified by the protocol. These are in addition to the standard JSON-RPC error codes returned by a bad method call.

Code	Description
-32521	Transaction reverted (or will revert) during execution phase.
-32602	Invalid UserOperation struct/fields.
-32500	Transaction rejected by entryPoint's simulateValidation, during account creation or validation.
-32501	Transaction rejected by paymaster's `validatePaymasterUserOp`.
-32502	Transaction rejected because of opcode validation.
-32503	UserOperation out of time-range: either account or paymaster returned a time-range, and it is already expired (or will expire soon).
-32504	Transaction rejected because paymaster (or signature aggregator) is throttled/banned.
-32505	Transaction rejected because paymaster (or signature aggregator) stake or unstake-delay is too low.
-32506	Transaction rejected because account specified unsupported signature aggregator.
-32507	Either `validateUserOp` or `validatePaymasterUserOp` returned an invalid signature check.