Upstream interoperability

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:

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 PaymentPayloads 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:

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

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