Onboard to ERC-4337 Gas Sponsorship

This guide prepares a MegaFuel sponsor policy and a wallet integration for ERC-4337 gas sponsorship on BSC.

Before you start

Have the following ready:

• A MegaFuel sponsor account and a policy-management API key.
• The BSC environment to use: Mainnet (56) or Testnet (97). Start with Testnet.
• The EntryPoint version and smart-account implementation your wallet uses.
• A smart-account test address, its owner address, and representative execute or executeBatch call data.
• The contracts, methods, token recipients, expected volume, and per-user budget that your product intends to sponsor.

Never send an owner private key, sponsor API key, or signing seed to MegaFuel support or place it in a policy request.

1. Choose a supported EntryPoint

Query the target environment's Bundler:

curl -sS https://bsc-megafuel-testnet.nodereal.io/4337/bundler \
  -H 'content-type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"eth_supportedEntryPoints","params":[]}'

Select one returned EntryPoint and keep that version consistent throughout your wallet flow: paymaster request, gas estimate, UserOperation hash, account signature, and submission.

2. Create or select a public MegaFuel policy

Follow the existing MegaFuel Policy Management process to create or select a policy for the target chain. If policy creation or funding is not enabled for your sponsor account, complete the sponsor onboarding process first.

For ERC-4337, the policy must be:

• on the correct network;
• active and within its start / end time window;
• funded with a non-zero available sponsorship balance;
• explicitly opted in with enable4337: true; and
• a public policy with at least the whitelist rules appropriate for the transaction it will sponsor.

Private-policy selection is not currently supported by the 4337 paymaster endpoint. The policy-management API rejects attempts to set enable4337: true on a private policy. Use a public policy with narrow whitelist and spending rules.

Enable an existing policy for ERC-4337

Use the standard MegaFuel policy-management endpoint. Replace the placeholders and keep the API key private.

POLICY_API="https://open-platform-ap.nodereal.io/<API_KEY>/megafuel/<CHAIN_ID>"

curl -sS "$POLICY_API" \
  -H 'content-type: application/json' \
  --data '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"pm_updatePolicy",
    "params":[{
      "uuid":"<POLICY_UUID>",
      "enable4337":true
    }]
  }'

Verify the result before testing:

curl -sS "$POLICY_API" \
  -H 'content-type: application/json' \
  --data '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"pm_getPolicyByUuid",
    "params":["<POLICY_UUID>"]
  }' | jq '.result | {
    uuid, activated, enable4337, network,
    maxGasCost, sponsoredGasfee, remainingBalance
  }'

The expected state is activated: true, enable4337: true, the requested network, and a positive remainingBalance.

3. Configure the policy for the inner smart-account call

MegaFuel unwraps a supported account's callData and evaluates the action that the smart account will execute. Configure policy rules for that inner action.

For a token transfer made by SimpleAccount.execute(token, 0, transfer(recipient, amount)):

• from is the SimpleAccount address;
• to is the token contract;
• method selector is 0xa9059cbb (transfer(address,uint256)); and
• receiver is the recipient encoded in the token call.

The EntryPoint and MegaFuel paymaster are infrastructure contracts. They are not the application target for policy matching.

Example: whitelist a smart account and a token contract.

# Smart account allowed to use this policy.
curl -sS "$POLICY_API" -H 'content-type: application/json' --data '{
  "jsonrpc":"2.0", "id":1, "method":"pm_addToWhitelist",
  "params":[{
    "policyUuid":"<POLICY_UUID>",
    "whitelistType":"FromAccountWhitelist",
    "values":["0x<SMART_ACCOUNT>"]
  }]
}'

# Application contract the smart account will call.
curl -sS "$POLICY_API" -H 'content-type: application/json' --data '{
  "jsonrpc":"2.0", "id":2, "method":"pm_addToWhitelist",
  "params":[{
    "policyUuid":"<POLICY_UUID>",
    "whitelistType":"ToAccountWhitelist",
    "values":["0x<TOKEN_OR_APPLICATION_CONTRACT>"]
  }]
}'

Use ContractMethodSigWhitelist and BEP20ReceiverWhiteList when your risk model needs more than sender/target restrictions. Keep the total policy budget, per-account gas cap, per-account daily gas cap, and daily transaction cap finite and appropriate for your use case.

4. Confirm smart-account compatibility

The wallet must produce a valid UserOperation and account signature for the chosen EntryPoint. MegaFuel currently recognizes these account call encodings for policy evaluation:

• execute(address,uint256,bytes)
• executeBatch(...) in the standard SimpleAccount form

If your account uses a different function selector or argument layout, submission may validate on-chain but sponsorship will be rejected because MegaFuel cannot safely identify the inner call. Before launch, provide a testnet UserOperation or sample callData for compatibility validation.

5. Test the complete user journey on Testnet

Use a fresh or isolated smart account that:

1. holds the asset it is intended to move;
2. holds no BNB (to prove the sponsored path); and
3. is covered by the active, funded, 4337-enabled policy.

Run the sequence in Wallet integration: stub paymaster data, estimate, final paymaster data, account signature, submit, and receipt polling.

Then check the policy:

• the UserOperation receipt reports success: true;
• actualGasCost is present;
• policy sponsoredGasfee increases by that actual cost; and
• policy remainingBalance decreases by the same amount.

6. Mainnet readiness checklist

• The wallet uses a live-supported EntryPoint and correct UserOperation encoding.
• The account ABI is a supported form or has passed compatibility review.
• The policy is public, active, funded, and enable4337 is true.
• Whitelists restrict the intended smart accounts and inner calls.
• Policy-level and per-account limits are intentionally configured.
• The wallet handles sponsorship rejection by showing a clear message or falling back to a user-paid flow where appropriate.
• The wallet refreshes expired final paymaster data instead of retrying it.
• The team monitors policy balance and sponsored spend after release.

Continue with the wallet integration guide.