# 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`](/docs/sdk/x402-types) | Wire-format types (Zod + TS) | Always (transitive); install directly only if you write your own adapter. |
| [`@nerochain/x402-server`](/docs/sdk/x402-server) | Merchant middleware (Express, Hono, Fastify, Next, paywall) | You gate an HTTP endpoint behind payment. |
| [`@nerochain/x402-client`](/docs/sdk/x402-client) | Agent HTTP wrapper (fetch, axios) | You make paid calls. |
| [`@nerochain/x402-aa`](/docs/sdk/x402-aa) | Paymaster-sponsored signer | You sign payments from an ERC-4337 SCW. |
| [`@nerochain/x402-extensions`](/docs/sdk/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:

```bash
pnpm add @nerochain/x402-client @nerochain/x402-aa ethers
```

For a **merchant** (any framework):

```bash
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](https://github.com/nerochain/nero-x402/tree/main/apps/facilitator) is in the same repo as the SDK but ships separately.
- Direct on-chain calls outside of the UserOp flow. Reading `ReceiptLog` events 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.