# NERO 402

> NERO 402 is the first AA-native x402 settlement scheme: ERC-4337 smart-contract wallets pay any API over HTTP 402 with paymaster-sponsored gas, holding no native token.

NERO 402 is an AA-native settlement scheme for x402 V2: ERC-4337 smart-contract wallets pay APIs over HTTP 402, with paymaster-sponsored gas. This file is the agent index for the documentation at https://docs.x402.nerochain.io.

## For AI agents

This site is built to be read by agents. Machine-readable entry points, all on this origin:

- **Full docs, one file:** [/llms-full.txt](https://docs.x402.nerochain.io/llms-full.txt)
- **Markdown of any page:** append `.md` — e.g. [/docs/getting-started/agents.md](https://docs.x402.nerochain.io/docs/getting-started/agents.md). The homepage is at [/index.md](https://docs.x402.nerochain.io/index.md). Content negotiation: send `Accept: text/markdown`.
- **Facilitator API (OpenAPI 3.1):** [/openapi.json](https://docs.x402.nerochain.io/openapi.json) · [/openapi.yaml](https://docs.x402.nerochain.io/openapi.yaml)
- **MCP server (Streamable HTTP):** [/mcp](https://docs.x402.nerochain.io/mcp) — tools for searching the docs and reading protocol facts
- **Ask endpoint (NLWeb):** `POST https://docs.x402.nerochain.io/ask` with `{"query": "..."}` (SSE supported)
- **Glossary (ground-truth terms):** [/glossary](https://docs.x402.nerochain.io/glossary) · machine-readable [/glossary.json](https://docs.x402.nerochain.io/glossary.json) (schema.org DefinedTermSet) · [/glossary.md](https://docs.x402.nerochain.io/glossary.md)
- **Authentication walkthrough:** [/auth.md](https://docs.x402.nerochain.io/auth.md)
- **Agent instructions:** [/agents.md](https://docs.x402.nerochain.io/agents.md)
- **Discovery:** [/.well-known/agent.json](https://docs.x402.nerochain.io/.well-known/agent.json), [/.well-known/mcp/server-card.json](https://docs.x402.nerochain.io/.well-known/mcp/server-card.json), [/.well-known/api-catalog](https://docs.x402.nerochain.io/.well-known/api-catalog)

## When to use NERO 402

Use NERO 402 when:

- An AI agent or autonomous script needs to **pay for an API call** programmatically over HTTP, settling in a stablecoin (USDT/USDC).
- The paying account is an **ERC-4337 smart-contract wallet** and cannot sign EIP-3009 (so upstream x402 `exact` does not apply).
- You want the agent to pay **without holding the chain's native gas token** — a paymaster sponsors gas.
- You are a **merchant** who wants to gate an HTTP endpoint behind payment in Express, Hono, Fastify, or Next.js.

Prefer upstream x402 `exact` instead when your payer is a plain EOA and your token implements EIP-3009; the NERO 402 facilitator and SDK support that path too.

## Documentation

- [FAQ](https://docs.x402.nerochain.io/docs/faq): Common questions about NERO 402, the aa-native scheme, and the reference implementation.
- [Welcome to NERO 402](https://docs.x402.nerochain.io/docs): An AA-native settlement scheme for x402, with a reference implementation on NERO Chain.

### Getting started
- [Quickstart for agents](https://docs.x402.nerochain.io/docs/getting-started/agents): Make a paid call to an x402-gated endpoint from a Node script in 30 lines.
- [Installation](https://docs.x402.nerochain.io/docs/getting-started/installation): Install the @nerochain/x402-* packages.
- [Quickstart for merchants](https://docs.x402.nerochain.io/docs/getting-started/merchants): Gate an HTTP endpoint behind x402 payment in any of Express, Hono, Fastify, or Next.js.

### Core concepts
- [The aa-native scheme](https://docs.x402.nerochain.io/docs/core-concepts/aa-native-scheme): x402 settlement scheme designed for ERC-4337 smart contract wallets, where the payment payload carries a signed UserOperation.
- [Client and server](https://docs.x402.nerochain.io/docs/core-concepts/client-server): The roles and responsibilities of the agent (client) and the merchant (server) in x402.
- [Facilitator](https://docs.x402.nerochain.io/docs/core-concepts/facilitator): The service that verifies and settles x402 payment payloads on behalf of merchants.
- [HTTP 402](https://docs.x402.nerochain.io/docs/core-concepts/http-402): How x402 V2 uses the long-reserved 402 status code to gate paid resources over plain HTTP.
- [Networks and tokens](https://docs.x402.nerochain.io/docs/core-concepts/networks): The chains and assets NERO 402's reference implementation supports.
- [Paymaster](https://docs.x402.nerochain.io/docs/core-concepts/paymaster): How NERO Paymaster sponsors UserOp gas, removing the native-asset balance from the agent's responsibilities.
- [Settlement contract](https://docs.x402.nerochain.io/docs/core-concepts/settlement-contract): The on-chain endpoint where aa-native payments land. Replay-protected, allowlist-gated, UUPS-upgradeable.
- [Wallet](https://docs.x402.nerochain.io/docs/core-concepts/wallet): How agent wallets work in NERO 402, and why the SCW model unlocks stablecoin-only operation.

### SDK reference
- [SDK overview](https://docs.x402.nerochain.io/docs/sdk/overview): The five @nerochain/x402-* packages — what each one does, and which ones you need.
- [@nerochain/x402-aa](https://docs.x402.nerochain.io/docs/sdk/x402-aa): Paymaster-sponsored signer for the aa-native scheme.
- [@nerochain/x402-client](https://docs.x402.nerochain.io/docs/sdk/x402-client): A fetch-API-compatible function that auto-handles 402 responses.
- [@nerochain/x402-extensions](https://docs.x402.nerochain.io/docs/sdk/x402-extensions): Optional protocol extensions — payment-identifier (idempotency) and access-token (signed proof-of-payment for cached access).
- [@nerochain/x402-server](https://docs.x402.nerochain.io/docs/sdk/x402-server): Merchant middleware adapters for Express, Hono, Fastify, and Next.js.
- [@nerochain/x402-types](https://docs.x402.nerochain.io/docs/sdk/x402-types): Wire-format Zod schemas and TypeScript types for x402 V2.

### Guides
- [Delegated agent pattern](https://docs.x402.nerochain.io/docs/guides/delegated-agent): Spawn a fresh ephemeral SCW, fund it once, let it loop through paid endpoints autonomously, then recover funds.
- [MCP server with x402](https://docs.x402.nerochain.io/docs/guides/mcp-server): Wrap NERO 402 paid calls behind a Model Context Protocol server so an LLM can spend through it.
- [Upstream interoperability](https://docs.x402.nerochain.io/docs/guides/upstream-interop): Use unmodified Coinbase x402 clients against the NERO 402 facilitator.
- [Web3Auth integration](https://docs.x402.nerochain.io/docs/guides/web3auth-integration): Use Web3Auth as the EOA owner behind an ERC-4337 SCW for NERO 402 payments.

### Advanced
- [Middleware hooks](https://docs.x402.nerochain.io/docs/advanced/middleware-hooks): Customize the merchant middleware's behavior at well-defined extension points.
- [Session keys and spending caps](https://docs.x402.nerochain.io/docs/advanced/session-keys): How to delegate scoped spending power to an agent without giving up the SCW's owner key.

### Reference
- [SettlementContract reference](https://docs.x402.nerochain.io/docs/reference/contract): ABI, storage layout, and deployment addresses for SettlementContract.sol.
- [Error codes](https://docs.x402.nerochain.io/docs/reference/errors): Stable identifier strings returned by the verifier and the settler.
- [Whitepaper](https://docs.x402.nerochain.io/docs/reference/whitepaper): The protocol's normative specification. Wire format, validation rules, security model.
- [Wire format](https://docs.x402.nerochain.io/docs/reference/wire-format): The HTTP headers and JSON envelope shapes used by x402 V2 and the aa-native scheme.

## Facilitator API

Base URL: `https://facilitator.x402.nerochain.io` — OpenAPI: [https://docs.x402.nerochain.io/openapi.json](https://docs.x402.nerochain.io/openapi.json)

- `GET /supported` — schemes, networks, and allowlisted assets the facilitator accepts.
- `POST /verify` — validate a signed payment payload without settling.
- `POST /settle` — verify then settle on chain; returns the transaction hash. Idempotent per request.
- `GET /health` — service status.

Merchant servers call `/verify` and `/settle`; agents never call the facilitator directly.

## Networks

- **NERO Chain mainnet** — `eip155:1689` (chainId 1689). SettlementContract `0x5eCfc64f2339992668f555918674B604F97B412D`. Assets: USDT, USDC.e, USDC.arb.
- **NERO Chain testnet** — `eip155:689` (chainId 689). SettlementContract `0x925dbba44570683ac8da99be08bc5ece8cf5a8c6`. Asset: DEMO-USDT (public mint, self-faucet). Faucet: https://app.testnet.nerochain.io/faucet.

## Constraints and limitations

- The on-chain `SettlementContract` is **not yet audited**; v1.0 of the SDK waits on a clean external audit. Do not route significant production value through the pre-audit contract.
- Targets **ERC-4337 v0.6** (NERO Chain's bundler version). v0.7-shaped UserOperations are rejected.
- **No refunds** in v1 — a successful settlement is final. Refund logic lives at the application layer.
- **One payment per HTTP request.** Paying multiple merchants means multiple requests.
- `aa-native` settlement currently requires the **NERO 402 facilitator**; the scheme is on a path to upstream standardization (`coinbase/x402#639`).

## More

- Whitepaper (PDF): https://docs.x402.nerochain.io/whitepaper.pdf
- Source (GitHub): https://github.com/nerochain/nero-x402
- Playground: https://x402.nerochain.io/playground
- Per-section indexes: https://docs.x402.nerochain.io/docs/llms.txt · https://docs.x402.nerochain.io/sdk/llms.txt · https://docs.x402.nerochain.io/developers/llms.txt
- Contact: help-support@nerochain.io