ERC-4337 Paymaster and Bundler RPC Reference

This reference covers the MegaFuel-specific RPC surface used by an ERC-4337 wallet. Use standard JSON-RPC 2.0 request envelopes and 0x-prefixed hex values.

Service endpoints

Paymaster methods

pm_getPaymasterStubData

Returns placeholder paymaster data suitable for gas estimation. It does not authorize sponsorship and must never be submitted as final data.

Endpoint: Paymaster endpoint

Parameters:

[userOperation, entryPoint, chainId, context]

Result:

{
  "paymaster": "0x<MEGAFUEL_PAYMASTER>",
  "paymasterData": "0x<STUB_DATA>",
  "paymasterVerificationGasLimit": "0x...",
  "paymasterPostOpGasLimit": "0x..."
}

pm_getPaymasterData

Checks the operation against MegaFuel policy rules and, if it is eligible, returns final signed paymaster data.

Endpoint: Paymaster endpoint

Parameters: Same as pm_getPaymasterStubData.

Result: Same field shape as the stub method, with final paymasterData. The response is short-lived. Request it after estimation and immediately before creating the final account signature and submitting the operation.

Common rejection causes: no matching public policy, policy disabled for 4337, insufficient policy balance, a whitelist/rule mismatch, unsupported account call encoding, an excessive declared gas price, or an excessive total UserOperation gas limit.

The current numeric safety ceilings and final-authorization lifetime are listed in ERC-4337 operating limits and policy funding. They are service safeguards, separate from any policy-specific spending caps.

Bundler methods

eth_supportedEntryPoints

Returns the EntryPoint addresses currently enabled on this Bundler.

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

Call this before choosing a version. Do not assume an address is enabled merely because it is a canonical ERC-4337 deployment.

eth_estimateUserOperationGas

Estimates account and paymaster gas limits for a stub-filled UserOperation.

[userOperation, entryPoint]

The result contains:

{
  "preVerificationGas": "0x...",
  "verificationGasLimit": "0x...",
  "callGasLimit": "0x...",
  "paymasterVerificationGasLimit": "0x...",
  "paymasterPostOpGasLimit": "0x..."
}

For initial estimation, omit the account gas-limit fields so the Bundler can calculate them. Use the returned values in the final paymaster request. This is a Bundler estimate, not a universal full simulation: supported SimpleAccount execute calls receive target-call estimation with a buffer, while unknown call encodings use conservative fallback values and may still fail policy decoding.

eth_sendUserOperation

Validates and queues a final MegaFuel-sponsored UserOperation.

[completeSignedUserOperation, entryPoint]

The result is the UserOperation hash:

"0x<USER_OP_HASH>"

The Bundler accepts only UserOperations sponsored by one of MegaFuel's enabled paymaster contracts. It returns a rejection before submission if the EntryPoint, paymaster, validation, nonce, or sponsorship authorization is not acceptable.

Submitting byte-for-byte identical UserOperation content is idempotent and returns the existing UserOperation hash.

eth_getUserOperationReceipt

Returns null while the UserOperation is not included. After inclusion, the response includes:

{
  "userOpHash": "0x...",
  "sender": "0x...",
  "paymaster": "0x...",
  "success": true,
  "actualGasCost": "<decimal wei string>",
  "transactionHash": "0x...",
  "blockNumber": 123456
}

success: false means the UserOperation reached EntryPoint processing but its account call did not succeed. Inspect the outer transaction and application call for the execution reason.

null is not a lifecycle status. It can mean the UserOperation is active but not included, terminal without an inclusion receipt, or unknown to this Bundler. Use nr_getUserOperationStatus to distinguish these cases.

eth_getUserOperationByHash

Returns the full operation and EntryPoint when MegaFuel has a known queued, in-flight, or persisted record. For an in-flight operation it may also include the latest outer transactionHash attempt. It returns null for an unknown hash.

nr_getPendingUserOperationNonce

NodeReal extension that returns the next available full ERC-4337 UserOperation nonce from this Bundler's view.

[entryPoint, sender, nonceKey]

Example:

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "nr_getPendingUserOperationNonce",
  "params": [
    "0x4337084D9E255Ff0702461CF8895CE9E3b5Ff108",
    "0x<SMART_ACCOUNT>",
    "0x0"
  ]
}

The result is a full uint256 UserOperation nonce:

nonce = (nonceKey << 64) | sequence

It is scoped by (EntryPoint, sender, nonceKey), not by the owner EOA's transaction nonce. The response merges the EntryPoint's confirmed sequence with this Bundler's contiguous queued/in-flight sequence. It is a snapshot, not a lock: submit promptly and re-query if a same-nonce operation is replaced, expires, or is rejected.

nr_getUserOperationStatus

NodeReal extension that exposes the Bundler’s durable lifecycle record.

[userOpHash]

The result is null only when this Bundler has never admitted the hash. Otherwise it returns userOpHash, entryPoint, and one of queued, inflight, included, rejected, expired, or dropped. Terminal rejected and expired states include failureReason; included responses contain the stored receipt and outer transactionHash.

See Lifecycle and client rules for polling, idempotency, and replacement behavior.

eth_chainId

Returns the target BSC chain ID. It is useful as a lightweight endpoint sanity check.

JSON-RPC batches

The Bundler supports JSON-RPC batches containing Bundler methods, ordinary node methods, or both. Bundler-native requests are handled by the Bundler; ordinary node methods are forwarded to its backing BSC node; results are returned as one JSON-RPC batch response. Match results by request id, not response order.

Version-specific operation layouts

See Wallet integration for the ordered flow and the v0.6 conversion rule.