Facilitator

The facilitator is a stateless HTTP service that does two things on behalf of merchants: it verifies payment payloads and it submits them to the chain. Merchants delegate to it so they can accept paid traffic without writing chain-specific code.

The HTTP surface

Three endpoints, plus a health check.

• GET /supported — advertises the schemes and assets the facilitator handles.
• POST /verify — checks that a payload binds to a merchant's PaymentRequirements. Returns {isValid: true, payer} or {isValid: false, invalidReason, details?}.
• POST /settle — re-verifies, then submits the operation to the chain. Returns SettleResult (success or error).

/verify is read-only; /settle is not. Merchants commonly verify before invoking the protected handler and settle after the handler returns 2xx, so they don't pay for settlement when their handler fails.

What /verify checks

For an aa-native payload, the verifier:

1. Decodes the V2 envelope.
2. Decodes the inner userOp and settlementCallSpec.
3. ABI-decodes userOp.callData to a SettlementContract.settle(merchant, token, amount, requestHash) invocation. Both SimpleAccount.execute(...) and SimpleAccount.executeBatch(...) are accepted; for executeBatch the verifier finds the entry whose data decodes to settle.
4. Asserts that the decoded settle arguments equal settlementCallSpec field-for-field.
5. Asserts that settlementCallSpec matches the merchant's PaymentRequirements (merchant address, token, amount).
6. Checks the off-chain replay registry for requestHash collisions.

The full validation rules and the error codes are in the whitepaper §2.4. The error code list is on the Errors reference page.

What /settle does

/settle is idempotent on requestHash. The flow:

1. Claim the requestHash in the off-chain registry as in_flight. If it is already settled, return the original txHash immediately. If it is already in_flight, return errorCode: "in_flight".
2. Re-verify with the same checks as /verify. Releases the in-flight claim on failure.
3. Submit the UserOp via eth_sendUserOperation on the bundler. Captures the returned userOpHash.
4. Wait for the bundler to return a receipt via eth_getUserOperationReceipt. The settlement contract emits ReceiptLog on success.
5. Complete the registry entry with the bundler-returned transactionHash.

A second /settle call with the same requestHash returns the original tx hash without re-submitting. In production tests this short-circuit completes in single-digit milliseconds versus several seconds for the original bundler round-trip.

Auth

Merchants authenticate to the facilitator with an HMAC-signed bearer token in Authorization: Bearer <hmac>. This authentication scheme is a facilitator-implementation detail and is not specified by x402.

The reference public Playground shares one rate-limited token across its public endpoints. Per-merchant tokens are issued out-of-band for production merchants.

Scheme support

The reference NERO 402 facilitator handles both aa-native and exact. /supported lists both:

{
  "x402Version": 2,
  "schemes": [
    {"scheme":"exact",     "networks":["eip155:1689"], "assets":["0x...USDC", "0x...USDT"]},
    {"scheme":"aa-native", "networks":["eip155:1689"], "assets":["0x...USDC", "0x...USDT"]}
  ]
}

A merchant that wants to accept both can advertise both in its paymentRequirements array. The client picks whichever it can satisfy.

Self-hosting

The reference facilitator is at apps/facilitator/. It runs on Node 20+, uses Hono, and is small enough to deploy on Vercel Functions, Fly.io, Railway, or any Node host.

A self-hosted facilitator handles its own paymaster relationship and bears the gas cost for aa-native settlements it submits. Where the public NERO 402 facilitator is single-tenant and operated by the project, self-hosted deployments are per-merchant.