Paymaster

A paymaster is an ERC-4337 contract that pays gas for a UserOperation on behalf of the operation's sender. In NERO 402's aa-native flow, the paymaster is the reason an agent's SCW does not need to hold any NERO native — every paid call is end-to-end gas-sponsored.

The shape of sponsorship

ERC-4337's UserOp envelope carries a paymasterAndData field. When non-empty, the bundler routes through a paymaster contract; the paymaster validates the operation, debits its own deposit at the EntryPoint, and lets the operation execute. The paymaster's bookkeeping is on chain; the agent does not need to know about it.

NERO operates a type-0 paymaster: gas is sponsored unconditionally for operations approved by the paymaster API. (Other types pay gas in an ERC-20 token rather than free-of-charge; NERO 402's reference flow uses type-0.)

Constructing a sponsored UserOp

The agent calls the paymaster API as part of building the operation. Concretely, in @nerochain/x402-aa:

builder.setPaymasterOptions({
  apikey: paymasterApiKey,
  rpc:    paymasterUrl,
  type:   "0",
});

The paymaster's middleware in the userop SDK calls the paymaster RPC, receives a signed paymasterAndData blob, and inserts it into the UserOp before signing. The agent's owner key signs the operation; the paymaster's signature is independent.

Operational implications

For agents:

• The SCW can be brand-new and undeployed. The first sponsored UserOp deploys the SCW (initCode) and settles in the same operation. Confirmed empirically against NERO mainnet.
• The agent never holds a native-asset balance. Wallet bookkeeping is just stablecoins.
• The agent is decoupled from native-gas price volatility.

For the paymaster operator (NERO, in v1):

• An API key is required. Issued from the NERO AA Platform dashboard.
• Each key has a rate quota. Bundler-side limits cap sponsored throughput at roughly 100 rps per API key.
• The paymaster operator bears the native gas cost of every sponsored UserOp. It is up to the operator to recoup this from merchants out of band, or to absorb it as a network operating cost.

Verifying gas sponsorship

The agent-cost-test example in the repo is a CLI that runs N paid calls and asserts the agent SCW's native-asset balance does not decrease across the run:

== invariants ==
  ✓ all calls returned 200
  ✓ total USDT spend == sum of receipts (0.002 == 0.002)
  ✓ total USDT spend == N × per-call price (0.002 == 0.002)
  ✓ agent SCW spent 0 NERO native (delta = 0.0 NERO)

See examples/agent-cost-test/.

Paymaster abuse

A paymaster that sponsors UserOps is structurally exposed to abuse: a malicious agent could submit operations that pass simulation, get sponsored, then revert on chain in ways that consume gas without producing a useful settlement. The mitigations layered into the reference deployment are documented in the whitepaper §5.3: API-key quotas, bundler rate limits, facilitator-side rate limits, and the off-chain replay registry rejecting re-attempts before paymaster sign-off.

Future directions

ERC-4337 paymasters have several other modes worth noting, even though aa-native v1 only uses type-0:

• Type-1 (token paymaster). Agent pays gas in an ERC-20 (often the same stablecoin used for the settlement). Useful when the paymaster operator does not want to absorb native gas costs.
• Verifying paymaster with rules. Paymaster validates application-specific predicates before sponsoring. For example: only sponsor UserOps whose callData targets a specific merchant.

Both modes are protocol-compatible with aa-native because the wire format treats the UserOp as opaque. A future facilitator could opt into either without a scheme change.