# Upstream interoperability

> Use unmodified Coinbase x402 clients against the NERO 402 facilitator.

NERO 402 was deliberately built to interoperate with the upstream `@x402/core@2.11.0` reference implementation. Anywhere both sides agree on the V2 envelope and the `exact` scheme, NERO 402's facilitator and the Coinbase reference client work together unmodified.

## What works out of the box

- **Coinbase `@x402/fetch` client → NERO 402 merchant middleware.** A client built against `@x402/core` can send `exact`-scheme payloads to a merchant using `@nerochain/x402-server`. Verified by the integration test at `examples/express-paid-api/src/interop.test.ts`.
- **`@nerochain/x402-server` middleware → upstream facilitator.** A merchant using `@nerochain/x402-server` can be configured to point at any facilitator that speaks the V2 wire format, including upstream reference deployments.
- **Settlement receipts.** The `PAYMENT-RESPONSE` body matches `@x402/core`'s `SettlementResultSchema`. Upstream clients can parse our receipts.

## What does not interoperate (and why)

- **`aa-native` is NERO 402-defined.** Upstream `@x402/fetch` does not yet know the scheme name. An upstream client cannot pay an `aa-native`-only merchant. Workaround: merchants offer both schemes in `accepts[]` so upstream clients fall back to `exact`.
- **Scheme-specific inner payloads.** The `payload` field is opaque per the spec; each scheme defines its own inner shape. Cross-scheme interop is by definition impossible.

## Enabling dual-scheme acceptance

The reference Playground accepts only `aa-native`. To accept both `aa-native` and `exact` from the same endpoint, list both:

```ts
paymentRequirements: [
  {
    scheme: "aa-native",
    network: "eip155:1689",
    amount: "1000",
    asset: USDT,
    payTo: MERCHANT,
    maxTimeoutSeconds: 60,
  },
  {
    scheme: "exact",
    network: "eip155:1689",
    amount: "1000",
    asset: USDT,
    payTo: MERCHANT,
    maxTimeoutSeconds: 60,
  },
],
```

The client picks whichever it can satisfy. `@x402/fetch` from upstream picks `exact`; `@nerochain/x402-client` with the `aa-native` signer picks `aa-native`.

## Reference facilitator support for `exact`

The reference NERO 402 facilitator handles both schemes. The `exact` scheme requires a hot-wallet submitter (the facilitator's own EOA) that holds NERO native and the relevant tokens; configure this via the `EXACT_SUBMITTER_PRIVATE_KEY` environment variable. Without it, `exact`-scheme settlements return `unsupported_scheme`.

## Conformance test

The integration test at `examples/express-paid-api/src/interop.test.ts` is the canonical proof of round-trip compatibility. It uses `@x402/core@2.11.0` to parse the reference middleware's 402 responses and submits Coinbase-format `PaymentPayload`s through the reference middleware. The test runs in under a second and is part of the workspace's standard `pnpm test` invocation.

This test caught one wire-format divergence during development (a field-name mismatch) and exists specifically to catch the next one.

## Migrating an existing `exact` deployment to `aa-native`

There is no "migration" in the sense of replacing one with the other. The two schemes coexist. To extend an existing `exact` merchant to also accept `aa-native`:

1. Deploy a `SettlementContract` on the merchant's network (or use the reference NERO Chain deployment).
2. Add an `aa-native` entry to the merchant's `paymentRequirements[]`.
3. Use a facilitator that supports both schemes (the reference one does).

Existing `exact` clients keep working. New SCW-based clients can pick `aa-native`.