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.

Fund and accept the policy before release

Policy credit is a MegaFuel accounting balance, not an EntryPoint deposit and not
a transfer to the Paymaster contract. Use the approved sponsor funding workflow.
The administrative pm_depositToPolicy operation is restricted to authorized
administrators; it is not a wallet-side funding API. If your sponsor account has
not been provisioned with a funding workflow, contact the MegaFuel team before
attempting an ERC-4337 rollout.

Before a production rollout, record the policy's sponsoredGasfee and
remainingBalance, execute a Testnet UserOperation, and then query the policy
every five seconds for up to 60 seconds. A successful operation should add its
receipt actualGasCost to sponsoredGasfee and subtract the same amount from
remainingBalance. Also use pm_listDepositsByPolicyUuid through your approved
sponsor/API access to verify that the expected funding credit is recorded.

Set an operational alert before launch for a low remainingBalance and for a
policy reaching its spending caps. See ERC-4337 operating limits and policy
funding.

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 the complete SimpleAccount BEP-20 transfer path. The last two rules are optional only when your risk model intentionally permits any method or any recipient.

# 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>"]
  }]
}'

# Inner BEP-20 transfer(address,uint256) selector.
curl -sS "$POLICY_API" -H 'content-type: application/json' --data '{
  "jsonrpc":"2.0", "id":3, "method":"pm_addToWhitelist",
  "params":[{
    "policyUuid":"<POLICY_UUID>",
    "whitelistType":"ContractMethodSigWhitelist",
    "values":["0xa9059cbb"]
  }]
}'

# Recipient encoded in that token transfer.
curl -sS "$POLICY_API" -H 'content-type: application/json' --data '{
  "jsonrpc":"2.0", "id":4, "method":"pm_addToWhitelist",
  "params":[{
    "policyUuid":"<POLICY_UUID>",
    "whitelistType":"BEP20ReceiverWhiteList",
    "values":["0x<TOKEN_RECEIVER>"]
  }]
}'

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) — selector 0xb61d27f6
• executeBatch(address[],uint256[],bytes[]) — selector 0x47e1da2a

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.

For an executeBatch, every inner call must match the same enabled policy. Do not depend on two separate policies to cover different calls in one UserOperation.

executeBatch is decoded as
executeBatch(address[] targets, uint256[] values, bytes[] calldatas) (selector
0x47e1da2a). The three arrays must be aligned by index: inner call i is
targets[i], values[i], and calldatas[i]. MegaFuel checks the target and
method in each inner call and requires all of them to pass the same policy.

For any operation—single or batch—make it match one active public policy only.
There is no public policy-priority or policy-preview contract. When a narrow
policy is introduced after a broad policy, narrow or deactivate the broad policy
first rather than assuming the newer policy will be selected.

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.
• The team has completed the funding/accounting acceptance check described above.
• Each intended action matches exactly one active public policy.

Continue with the wallet integration guide.