Bundler RPC Methods

A reference to the supported RPC methods for ERC-4337 bundlers.

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


eth_sendUserOperation

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

Try it here: eth_sendUserOperation

{
  "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..."
}

eth_estimateUserOperationGas

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).

Optional state override set

It is also possible to estimate gas for a UserOperation under different states. This is useful for a number of scenarios. For example, you may need to estimate gas for an ERC-20 transfer without causing a RPC error due to insufficient funds. The parameter is a map of addresses to its override settings. If no overrides are needed, this parameter can be omitted.

Override types

Each address specified in the override set can have the following configurations. Each config is optional and can be omitted if not needed.

SettingType
nonceHex encoded quantity.
codeHex encoded bytes.
balanceHex encoded quantity.
stateMap of storage slot to value. Both key and value are encoded hex strings. This will override all storage slots.
stateDiffMap of storage slot to value. Both key and value are encoded hex strings. This will override only the storage slots that are specified.
{
  "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,
    
    // [Optional] State override set
    {
      addressToOverride: {
        nonce,
        code,
        balance,
        state,
        stateDiff,
      }
    }
  ]
}
{
  "jsonrpc": "2.0",
  "id": 1,

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

eth_getUserOperationByHash

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

Try it here: eth_getUserOperationByHash

{
  "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,
  ]
}

eth_getUserOperationReceipt

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

Try it here: eth_getUserOperationReceipt

{
  "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
  ]
}

eth_supportedEntryPoints

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

Try it here: eth_supportedEntryPoints

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

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