NERO 402

The first AA-native x402 payment stack on NERO Chain — facilitator, SDK, audited settlement contract, and a public playground showing AI agents paying APIs in USDC with paymaster-sponsored gas.

The aa-native scheme

Upstream x402's default exact scheme settles via EIP-3009 transferWithAuthorization — which only EOAs can sign. Smart contract wallets can't use it (there's no private key the token contract can ecrecover). On NERO Chain every wallet is an SCW, so exact is effectively unusable. NERO 402 contributes a second scheme — aa-native — that closes that gap.

How it works

1. Merchant API returns HTTP 402 with PAYMENT-REQUIRED, advertising scheme: "aa-native", payTo, amount, asset, network.
2. The agent's SCW signs an ERC-4337 UserOperation whose callData decodes to:

   SettlementContract.settle(merchant, token, amount, requestHash)
   

3. The agent retries with PAYMENT-SIGNATURE carrying the signed UserOp.
4. The merchant forwards to a NERO 402 facilitator's /verify + /settle endpoints.
5. The facilitator submits the UserOp via the NERO bundler. The NERO Paymaster sponsors gas (type: 0) — the agent spends zero NERO native.
6. SettlementContract.settle() runs IERC20.transferFrom(SCW → merchant), records isSettled[settlementKey] = true (key bound to (payer, merchant, token, amount, requestHash)), emits ReceiptLog.
7. The merchant returns 200 with PAYMENT-RESPONSE carrying the on-chain transactionHash.

The agent never holds the chain's native token. The merchant never sees the SCW's private key. Replay protection is on-chain; gas is paymaster-sponsored. Full wire format and validation rules: docs/whitepaper/whitepaper.pdf.

aa-native vs exact

Both schemes are advertised by NERO 402's facilitator (GET /supported); merchants pick which to accept. An unmodified upstream @x402/fetch client can pay an NERO 402 merchant via exact (USDC.e or USDC.arb on mainnet) without forking.

Repository layout

Deployed contracts

Quickstart

git clone --recursive <this-repo>
cd nero-x402
pnpm install
pnpm -r test           # JS test suites
cd contracts && forge test    # Foundry test suite

Run the playground locally:

cd apps/playground
cp .env.example .env   # edit with your testnet config
pnpm dev

Run the facilitator locally:

cd apps/facilitator
cp .env.example .env   # edit with your NERO Paymaster API key
pnpm dev

The canonical end-to-end demo:

cd examples/learn-nero
cp .env.example .env   # set NERO_PRIVATE_KEY and NERO_PAYMASTER_API_KEY
pnpm start

Documentation

• Whitepaper: docs/whitepaper/whitepaper.pdf
• Reference docs: https://x402.nerochain.io/docs
• SDK package READMEs: packages/

License

MIT.