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.

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 where possible so the Bundler can calculate them. Use the returned values in the final paymaster request.

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.

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.

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.