Wallet

The wallet is the structure that holds the agent's funds and produces the signature on the payment payload. NERO 402 supports two wallet shapes, one per scheme.

EOA (the exact scheme)

An externally-owned account is an Ethereum account whose key lives off-chain. Signing happens locally. The token's transferWithAuthorization path requires the recovered signer (ecrecover of (v, r, s)) to hold the source balance.

Pros: simple, no contract deployment, supported by every wallet library.

Cons: the EOA must hold the chain's native asset to pay gas (exact settlement is submitted by the facilitator's hot wallet, but if the agent ever needs to do anything on chain itself it needs gas). Most current EOAs also do not implement ERC-1271 fallback signing.

ERC-4337 SCW (the aa-native scheme)

A smart contract wallet is an Ethereum account whose code is on-chain. The address is a CREATE2 deployment of an account contract that delegates signature validation to its own logic. In the canonical case (SimpleAccount), the account's owner is an EOA whose signature the account contract verifies.

The agent's signing flow:

1. The agent constructs a UserOperation whose callData invokes SettlementContract.settle(...).
2. The agent signs the operation's hash with the SCW's owner key.
3. A bundler submits the operation through the canonical EntryPoint contract.
4. A paymaster sponsors the operation's gas.

The agent's SCW only ever needs to hold the settlement asset (USDT, USDC, or DEMO-USDT). It does not need NERO native. This is the operational simplification that makes aa-native worth defining.

Counterfactual addresses

An SCW's address is determined by its factory + salt + owner EOA. The chain only stores the contract once it has been deployed by an initCode-bearing UserOp, but the address is computable before deployment. Funds can be sent to a counterfactual SCW; they sit at that address until the SCW deploys and starts spending them.

NERO 402's first paid call from a fresh SCW deploys the SCW and settles in the same UserOp, sponsored by the paymaster end-to-end. The agent observes only a single HTTP round-trip and ends up with a deployed wallet plus a paid response.

How the SDK constructs the wallet

@nerochain/x402-aa's aaNativeSigner({signer}) wraps an ethers.Wallet (or ethers.HDNodeWallet) as the SCW owner. Internally it uses the userop SDK and the canonical NERO SimpleAccountFactory to derive the SCW address and prepare UserOps.

const wallet = new ethers.Wallet(privateKey);
const signer = aaNativeSigner({
  signer: wallet,
  rpcUrl, bundlerUrl, paymasterUrl, paymasterApiKey,
  settlementContract,
});

The SCW address is reproducible from the EOA + factory. Two runs of the same key produce the same SCW address.

Web3Auth-derived owners

For browser-based agents, the playground uses Web3Auth to obtain a JsonRpcSigner from a social login. That signer is passed to aaNativeSigner in place of an ethers.Wallet. The end-user's social-login session backs the SCW's owner key; the SCW itself behaves identically.

See the Web3Auth integration guide for the full pattern.

Session keys

The SimpleAccount contract used by the reference SDK requires the owner to sign every UserOp. Alternative ERC-4337 account contracts (Kernel, Safe with modules, ZeroDev, others) support session keys that delegate scoped spending to a separate key — for example, "may only sign UserOps targeting SettlementContract.settle for amounts up to 10 USDT/day". Plugging these in is a factory swap; the wire format is unaffected. See the Session keys & spending caps page.