SDK overview
The five @nerochain/x402-* packages — what each one does, and which ones you need.
The NERO 402 SDK is five small packages under the @nerochain/ scope. Each is independently installable and has a focused responsibility. You only pull in what you use.
The packages at a glance
| Package | Role | When you need it |
|---|---|---|
@nerochain/x402-types | Wire-format types (Zod + TS) | Always (transitive); install directly only if you write your own adapter. |
@nerochain/x402-server | Merchant middleware (Express, Hono, Fastify, Next, paywall) | You gate an HTTP endpoint behind payment. |
@nerochain/x402-client | Agent HTTP wrapper (fetch, axios) | You make paid calls. |
@nerochain/x402-aa | Paymaster-sponsored signer | You sign payments from an ERC-4337 SCW. |
@nerochain/x402-extensions | Optional protocol extensions (idempotency, signed access tokens) | You want to deduplicate retries or grant cached access after a paid call. |
What goes together
For an agent in the aa-native scheme:
pnpm add @nerochain/x402-client @nerochain/x402-aa ethersFor a merchant (any framework):
pnpm add @nerochain/x402-server@nerochain/x402-types is a transitive dep of both — there's no need to install it directly unless you're writing a custom adapter, alternative client, or new scheme implementation.
Design principles
Wire-format alignment with upstream. All five packages target @x402/core@2.11.0's envelope shapes. Field names are exactly as upstream specifies. The interop test in examples/express-paid-api/src/interop.test.ts round-trips between Coinbase's reference parser and our middleware to catch any divergence.
No global config. Every factory takes its config explicitly. There is no module-scope mutable state. Tests can run multiple instances side-by-side; production servers can run multiple merchants in one process with different facilitator URLs.
Pluggable signers. @nerochain/x402-client is scheme-agnostic. The signer is an interface; @nerochain/x402-aa is one implementation. Future schemes (and alternative SCW account contracts) plug in by writing a different signer with the same shape.
Framework adapters share core logic. @nerochain/x402-server exposes a single gateRequest / settleAfterHandler core; the Express, Hono, Fastify, and Next adapters are thin wrappers. A handler that works in Express works the same way in Next App Router with no behavioral change.
What the SDK does not include
- A facilitator implementation. The reference facilitator is in the same repo as the SDK but ships separately.
- Direct on-chain calls outside of the UserOp flow. Reading
ReceiptLogevents for independent verification is the consumer's responsibility. - Wallet connection UI. The SDK takes an already-constructed signer. Use Web3Auth, RainbowKit, ConnectKit, or any other wallet library to obtain the signer.
Versioning
The packages publish together at the same version. Bumping any one of them bumps all five. Cross-package compatibility is checked in CI; consuming a mix of versions is not supported.