# Authentication for NERO 402

> How an agent obtains credentials and authenticates a payment to a NERO 402 merchant.

NERO 402 authenticates **payments**, not sessions. There is no OAuth bearer token and no login. A request is authorized by a **cryptographic signature** over an ERC-4337 `UserOperation` produced by the agent's smart-contract wallet (SCW). This document follows the structure of the [WorkOS auth.md](https://workos.com/auth-md) draft so agents can map it onto the `agent_auth` model, and it notes precisely where NERO 402 differs.

## Discover

When an agent calls a paid endpoint without payment, the merchant responds:

```
HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: <base64url JSON of paymentRequirements>
```

The `PAYMENT-REQUIRED` header is NERO 402's discovery signal — the analogue of a `WWW-Authenticate` challenge. It advertises `scheme` (`aa-native` or `exact`), `network` (CAIP-2), `amount`, `asset`, and `payTo`. Facilitator-level discovery is at `GET https://facilitator.x402.nerochain.io/supported`. Protected-resource metadata: [/.well-known/oauth-protected-resource](https://docs.x402.nerochain.io/.well-known/oauth-protected-resource).

> Mapping to the spec: where `agent_auth` would return `WWW-Authenticate` with a `register_uri`, NERO 402 returns `PAYMENT-REQUIRED` with the payment terms. There is no `identity_assertion` or `id-jag` token exchange — the UserOperation signature is the assertion.

## Pick a method

- **aa-native** (recommended): the payer is an ERC-4337 SCW. Gas is paymaster-sponsored. Works with any allowlisted ERC-20.
- **exact**: the payer is an EOA signing an EIP-3009 authorization. Wire-compatible with upstream x402.

## Register

"Registration" for an agent is provisioning the two things it needs:

1. **A signing key and SCW.** Generate an EOA key (`openssl rand -hex 32`). The SCW address is derived deterministically from that key and the canonical SimpleAccount factory — no on-chain registration step is required before first use; the wallet deploys itself on its first sponsored UserOperation.
2. **A Paymaster API key**, if you self-host a facilitator. Obtain it from the NERO AA Platform dashboard (the credential issuer / `register_uri` equivalent): https://docs.nerochain.io/en/developer-tools/aa-platform. The same key works on testnet and mainnet.

Agents that pay through a merchant's hosted facilitator do not need their own paymaster key — the facilitator operator holds it.

## Claim

There is no token to claim. Paymaster sponsorship is requested per UserOperation at signing time by `@nerochain/x402-aa`, which calls the paymaster RPC and embeds the sponsorship in `paymasterAndData`. The "claim" is implicit in constructing the signed UserOperation.

## Use the credential

Sign the `UserOperation` and retry the request with it base64url-encoded in the `PAYMENT-SIGNATURE` header:

```
POST /api/paid-endpoint
PAYMENT-SIGNATURE: <base64url JSON of the signed payment payload>
```

The merchant forwards it to the facilitator's `/verify` and `/settle`. On success the response is `200` with a `PAYMENT-RESPONSE` header carrying the on-chain `transactionHash`. Full code: [Quickstart for agents](https://docs.x402.nerochain.io/docs/getting-started/agents).

## Errors

Verification and settlement return structured JSON error codes (never HTML):

- `malformed_request` — the payload did not parse.
- `signature_invalid` / `invalid_inner_payload` — the UserOperation or authorization did not validate.
- `replay` — this exact payment was already settled.
- `asset_not_allowed` / `network_mismatch` / `amount_mismatch` — the payment did not match the requirements.
- `user_op_failed` — the UserOperation reverted on chain (surfaced revert reason included).
- `bundler_unreachable` / `receipt_timeout` — transient; retry honoring `Retry-After`.

See [Errors reference](https://docs.x402.nerochain.io/docs/reference/errors).

## Revocation

- **Rotate the signing key** to retire an SCW; fund a fresh wallet derived from the new key.
- **Disable or rotate the Paymaster API key** in the AA Platform dashboard to revoke sponsorship for a self-hosted facilitator.
- There is no server-side session to revoke, because there is no session — each payment is independently authorized by its own signature.

## Contact

Security and credential questions: help-support@nerochain.io.