@absol-labs/agent 0.11.0 → 0.12.0-rc.2

package/docs/x402.md

@@ -1,519 +1,738 @@
 # Metrik and x402
 
-> **Metrik ships a real, spec-compliant x402 facilitator — one that refuses to
-> settle payment for a service its own oracle says is not delivering.** It does
-> NOT express its metered escrow stream as an x402 payment, and it never will
-> under the schemes x402 ships today.
+> **Status.** This package implements **x402 v2 `exact` payments that settle
+> into a `StreamEscrowV2` stream**, through the ownerless
+> `X402StreamOpenerFactory` (metrik-contracts#48). It ships a facilitator
+> service (`metrik-x402-opener-facilitator`) and an opt-in x402 v2 mode on the
+> seller gateway. **Both are OFF by default** and have not yet run in
+> production. The factory is deployed and Sourcify-verified on Base Sepolia at
+> `0x43DA0D9602f7fc5ac0bb90461e39b033EB493d24` (implementation
+> `0xbD8B7B2F49Fdb954bda6bE5ce22218d44345DC43`, block 47337415); everything
+> here is testnet only.
 >
-> Those two sentences are the whole story, and the rest of this document is the
-> evidence for both halves. Earlier versions of this file said flatly that "this
-> package does not ship an x402 facilitator". That was true when it was written
-> and is now out of date; the analysis it was built on is unchanged and still
-> below.
-
-The tagline — _x402 proves the payment, Metrik proves the delivery_ — used to be
-positioning only. It is now literally what the code does: a standard `exact`
-payment, verified by a standard facilitator, with one extra question asked
-before settlement that no other facilitator can ask.
-
----
-
-## The two things Metrik does with 402, and how they differ
-
-|                                 | **Verified stream** (`src/x402/facilitator.ts`)            | **x402 `exact` + delivery gate** (this document's subject) |
-| ------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------- |
-| Protocol                        | Metrik-native, scheme `streamproof-verified-stream`        | **Standard x402 v1, scheme `exact`**                       |
-| Header                          | `X-METRIK-PAYMENT`                                         | `X-PAYMENT` / `X-PAYMENT-RESPONSE`                         |
-| Works with `x402-fetch`?        | No                                                         | **Yes, untouched**                                         |
-| Money                           | Escrowed in `StreamEscrowV2`, released per verified second | One EIP-3009 transfer, payer -> payee                      |
-| If the service stops delivering | Unearned escrow is **recoverable** by the buyer            | The payment is **prevented**, never recovered              |
-| Buyer protection                | Strong                                                     | **Strictly weaker — see below**                            |
-
-**The x402 path is weaker buyer protection than the stream, and that is not a
-detail to bury.** It holds none of the buyer's money, so it can only stop a
-payment that has not happened yet. Money already paid through it is gone,
-exactly as it would be through any other facilitator. The stream remains the
-only path where "the service stopped delivering" and "you get your money back"
-are the same sentence.
-
-What the gate buys is reach: an agent that already speaks x402 gets a meaningful
-safety property for free, with no SDK, no escrow and no Metrik-specific code.
-
----
-
-## The unlock: nothing constrains _why_ a facilitator says no
-
-The x402 facilitator interface is `POST /verify`, `POST /settle`,
-`GET /supported`. `/verify` answers with:
+> **Upfront ("minimum charge") opener.** A listing can instead quote the
+> `X402UpfrontStreamOpenerFactory` (metrik-contracts#54; Base Sepolia
+> `0x17126c80C12a51183d3664EEE2b602552592c2Aa`, implementation
+> `0xA9C58A2554Eb869B0D1ECBa46a0435cFFC90341d`, bound to StreamEscrowV3
+> `0x0643ba482C6A7aF31a1f8225e7e7e79Cfc467b13`): part of each payment is a
+> NON-REFUNDABLE per-call charge, only the rest is escrowed and metered. See
+> [The upfront (minimum-charge) opener](#the-upfront-minimum-charge-opener).
+> The V3-bound stream factory `0x3d3a…cFB2` stays live, and its clones are
+> still served and refunded.
+>
+> The separate Metrik-native `402` flow (scheme `streamproof-verified-stream`,
+> header `X-METRIK-PAYMENT`) described at the end is **not** x402 and is
+> unchanged.
+
+## The hard rule: an opener `payTo` is settled ONLY by the Metrik opener facilitator
+
+**Read this before running any of it.** The x402 `payTo` in this mode is the
+address of an `X402StreamOpener`. Every stock x402 `exact` facilitator settles
+by calling `USDC.transferWithAuthorization(to = payTo)` directly. Pointed at an
+opener, that transfer succeeds and **strands 100% of the payer's payment in the
+opener permanently**: the opener deliberately has no sweep or "claim stray
+funds" path (one would be exploitable, because a used and a cancelled EIP-3009
+nonce are indistinguishable on-chain). The same happens if anyone who sees the
+signed payload submits it to USDC first. See metrik-contracts
+`evm/docs/x402-opener.md`.
+
+So, in this package, and for anyone integrating it:
+
+1. **Only the Metrik opener facilitator may settle an opener `payTo`.** It
+   calls `factory.deployAndSettle(terms, authorization)`, which pulls the
+   payment into the opener and opens the stream in the same transaction. Its
+   `GET /supported` advertises a marker —
+   `kinds[].extra.metrikStreamOpener = {settlement: "x402-stream-opener",
+factory, escrow, usdc, chainId, minAmount, receiptTimeoutSeconds, refundRelay?, upfrontOpener?}` — so a resource server can tell it apart
+   from a stock facilitator. `refundRelay: true` means the same service also
+   runs the gasless refund relay (see below). `upfrontOpener = {factory,
+implementation, escrow, termsVersion: "upfront-1"}` is present when it also
+   settles the upfront opener kind; `factory` stays the stream factory.
+2. **The gateway refuses to start** unless its configured facilitator's
+   `/supported` carries that marker for exactly the gateway's factory, escrow,
+   token and chain. It re-checks the marker on a timer (default every 300 s)
+   and **fails closed** whenever it cannot prove it: `503
+x402-facilitator-unavailable`, no `PAYMENT-REQUIRED`, nothing verified,
+   nothing served, nothing settled anywhere else. A facilitator that is
+   unreachable when a payment arrives produces `402`, never a free call.
+3. **Never advertise an opener `payTo` to third-party facilitators or discovery
+   catalogs** (the x402 Bazaar extension or any other). The gateway registers
+   no discovery extension and never submits its route to any catalog. Only
+   when the operator configures `METRIK_GATEWAY_X402V2_SCHEMA` does the 402
+   _declare_ an input/output schema, in the standard `extensions.bazaar` shape,
+   so a client can read what to send; the only facilitator that ever sees the
+   payment is the Metrik opener facilitator, and it catalogs nothing. Do not
+   register the route with a discovery service.
+4. **Authenticate an opener only as `factory.predict(terms) == payTo`** (or
+   `factory.isOpener(address)`), never by code or codehash: anyone can clone the
+   implementation outside the factory with byte-identical code. The
+   facilitator recomputes `predict` on-chain for every payment.
+5. **The signed payment never leaves the gateway→facilitator path.** The
+   gateway strips `PAYMENT-SIGNATURE` (and `X-PAYMENT`) before proxying to the
+   seller's upstream.
+
+## How a payment flows
 
-```ts
-VerifyResponse = { isValid: boolean, invalidReason?: ErrorReason, payer?: string }
+```
+buyer (@x402/fetch)            gateway (x402 mode)             opener facilitator           chain
+  │  GET /resource  ───────────▶ 402 + PAYMENT-REQUIRED
+  │                               payTo = factory.predict(terms)
+  │  PAYMENT-SIGNATURE ─────────▶ POST /verify ───────────────▶ all checks below
+  │                               upstream request (status < 400?)
+  │                               POST /settle (bearer) ──────▶ deployAndSettle ────────────▶ USDC → opener → StreamEscrowV2
+  │  200 + body + PAYMENT-RESPONSE ◀── receipt shows the stream ◀─────────────────────────── StreamOpened / StreamOpenedFor
 ```
 
-`isValid` is a boolean and the spec does not constrain what a facilitator may
-consider before returning `false`. A facilitator is the party a resource server
-delegates its "should this payment go through" decision to. Metrik simply knows
-one more thing than every other facilitator, because it runs a prober.
-
-So: standard scheme, standard headers, standard client, no contract change — and
-a property no other facilitator can offer, because no other facilitator has an
-oracle.
-
-### What `isValid: true` from Metrik does and does not mean
-
-It means **"this payment is well-formed and Metrik has no fresh evidence that
-this service is failing."** It is not an endorsement, not a correctness
-guarantee, and not a promise about the next call. The gate only ever subtracts.
-
-And per the standing rule: Metrik verifies **delivery**, not **correctness**. A
-service that returns a fast, well-formed, wrong answer passes every check Metrik
-makes.
-
----
-
-## Tier 1: the gateway speaks 402
-
-`CallerAuthGateway` authorizes requests carrying a Metrik `InvocationCapability`
-— a buyer with an open, funded, verified stream. That path is **unchanged**. A
-request with a valid capability behaves today exactly as it did before.
-
-What is new is opt-in: set `METRIK_GATEWAY_X402_PRICE_BASE_UNITS` and a request
-with **no** capability gets a real x402 `402` instead of a `403`:
+- **Terms.** One listing's immutable terms are `{operator, serviceRef,
+ratePerSecond, maxDuration}`; the opener for them lives at
+  `factory.predict(terms)` whether or not it is deployed yet. The terms travel
+  in `PaymentRequirements.extra.metrikStreamOpener` (with the factory address);
+  the payer's EIP-3009 signature binds `to = payTo`, so it commits to them.
+- **Price = deposit.** Each paid request opens one stream with `deposit =
+price`, on the listing's terms. The escrow records the **opener** as the
+  stream's buyer; the opener records the payer (`payerOf(streamId)`).
+- **Earning.** Unchanged: the operator earns `ratePerSecond × verified
+seconds`, capped at the deposit, claimed with `claimWithProof` against the
+  oracle's checkpoints, minus the 0.5% protocol fee.
+- **Settle after serve.** The gateway settles only when the upstream answered
+  `< 400`, and before any upstream byte reaches the buyer (the reference
+  `@x402/*` middleware order). An upstream `>= 400` submits nothing, so no
+  funds move. A failed settlement sends no upstream body.
+
+### What the facilitator checks (every payment, fail closed)
+
+Standard `exact` checks are delegated to the official `@x402/evm`
+`ExactEvmScheme` verifier (signature, `to == payTo`, `value == amount`,
+validity window, asset contract, a simulation of the transfer). The stock
+scheme is given a signer that cannot broadcast, so its direct-transfer settle
+path is structurally unreachable. On top of it:
+
+| Check                                                                                                                                                                                                                                           | Refusal reason                                                         |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| x402 v2, scheme `exact`, the configured CAIP-2 network                                                                                                                                                                                          | `metrik_opener_unsupported_*`                                          |
+| `payload.accepted` equals the requirements exactly                                                                                                                                                                                              | `metrik_opener_accepted_requirements_mismatch`                         |
+| Asset transfer method is EIP-3009 (Permit2 and everything else refused)                                                                                                                                                                         | `metrik_opener_asset_transfer_method_not_eip3009`                      |
+| Not an ERC-6492 (counterfactual smart wallet) signature                                                                                                                                                                                         | `metrik_opener_erc6492_signature_unsupported`                          |
+| Asset is allowlisted and equals `factory.usdc()`                                                                                                                                                                                                | `metrik_opener_asset_not_allowed`                                      |
+| Terms are well formed; the factory named is the configured one                                                                                                                                                                                  | `metrik_opener_invalid_terms` / `_factory_mismatch`                    |
+| `0 < amount <= ratePerSecond × maxDuration`                                                                                                                                                                                                     | `metrik_opener_invalid_amount` / `_amount_exceeds_rate_times_duration` |
+| `payTo == factory.predict(terms)`, read on-chain                                                                                                                                                                                                | `metrik_opener_pay_to_not_predicted_opener`                            |
+| `(operator, serviceRef)` resolve to exactly one **operator-signed** listing (the existing discovery verification: schema, re-derived `serviceRef`, recovered EIP-712 operator signature), and the rate is inside its signed `commercial` bounds | `metrik_opener_listing_*`                                              |
+| `deployAndSettle` simulates cleanly from the relayer                                                                                                                                                                                            | `metrik_opener_settle_simulation_failed`                               |
+
+`settle` re-runs all of it, broadcasts `deployAndSettle`, waits for the
+receipt, and reports `success: true` only when the mined receipt contains both
+the escrow's `StreamOpened` (buyer = opener, exactly these terms and deposit)
+and the opener's `StreamOpenedFor` (this payer, nonce and amount). The
+`SettleResponse` carries `extra.metrikStreamOpener = {streamId, opener, escrow,
+deposit, ratePerSecond, expiresAt}`. A revert (for example an authorization that
+was already used) is `success: false` with the reason. A receipt that does not
+arrive in time is `settlement_pending`; a later settle of the same payload
+reconciles against that transaction instead of broadcasting a second one.
+
+### At most one success per authorization
+
+Each EIP-3009 authorization — keyed by chain, asset, payer and authorization
+nonce — receives **at most one successful `SettleResponse` from a facilitator
+instance, ever**:
+
+- A settle (or verify) of an authorization that is already in flight or already
+  settled returns `success: false` / `isValid: false` with
+  `duplicate_settlement` (carrying the tx hash when there is one). One payment
+  can never buy two served responses.
+- After `settlement_pending`, a retry of the SAME payload verifies (even though
+  the authorization may already be used on-chain) and its settle reconciles to
+  the mined outcome; it receives the one success only if none was delivered
+  before.
+- The gateway enforces the same rule on its side: a `PAYMENT-SIGNATURE` whose
+  authorization is in flight or already settled gets `409
+x402-payment-already-used` **without** an upstream call; a retry after
+  `settlement_pending` is let through so it can reconcile.
+- Relayer submissions (simulate + broadcast) are serialized, so concurrent
+  payers never collide on the relayer's account nonce.
+
+**Scope of the guarantee: both ledgers are in-memory and per instance.** They
+do not survive a restart and are not shared between replicas. Run exactly one
+facilitator instance (and one gateway instance per listing); a multi-instance
+deployment would need a shared store, which does not exist today. Entries are
+kept until the authorization's `validBefore` has passed (plus a grace), after
+which USDC itself refuses the authorization.
+
+## The upfront (minimum-charge) opener
+
+A stream-opener payment funds a stream of the WHOLE payment, and accrual starts
+only at the first verified interval: a buyer who takes the response and closes
+within seconds reclaims almost all of it, so one delivered call can cost
+nothing. The upfront opener (metrik-contracts#54, design note
+`docs/x402-opener-min-charge.md`) fixes that with a new opener and factory;
+nothing deployed changed.
+
+- **Terms** gain two fields: `{operator, serviceRef, ratePerSecond,
+maxDuration, price, upfrontAmount}`. All six are committed by `payTo =
+upfrontFactory.predict(terms)` (CREATE2 over `abi.encode(terms)`), so the
+  payer's EIP-3009 signature binds the split too.
+- **`amount == price`**, exactly: the opener rejects any other value on-chain
+  (`PriceMismatch`) before anything moves.
+- **At settlement, in the same transaction**, `upfrontAmount` is paid to the
+  seller (minus the escrow's protocol fee, rounded up, to its fee recipient)
+  and is **NOT refundable**: it pays for the call whatever is delivered. Only
+  `price - upfrontAmount` funds a `StreamEscrowV3` stream, metered exactly like
+  a stream opener's, and that deposit is the most any refund can return.
+- **`upfrontAmount == price` is upfront-only**: no stream is opened at all. The
+  settlement reports `streamId: null` (on-chain `bytes32(0)`), the response is
+  served, no metered session exists, and there is nothing to close, reclaim or
+  refund.
+
+### The 402 `extra` (what the SDK enforces before signing)
 
 ```json
 {
-  "x402Version": 1,
-  "error": "X-PAYMENT header is required",
-  "accepts": [
-    {
-      "scheme": "exact",
-      "network": "base-sepolia",
-      "maxAmountRequired": "1000",
-      "resource": "https://livedata.example/price",
-      "payTo": "0x...",
-      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
-      "maxTimeoutSeconds": 60,
-      "extra": { "name": "USDC", "version": "2", "metrikServiceRef": "0x..." }
-    }
-  ]
+  "factory": "<registry upfront factory>",
+  "termsVersion": "upfront-1",
+  "operator": "0x…",
+  "serviceRef": "0x…",
+  "ratePerSecond": "100",
+  "maxDuration": "3600",
+  "price": "60000",
+  "upfrontAmount": "15000",
+  "refundUrl": "https://<relay>/streams/{streamId}"
 }
 ```
 
-Three rules govern it:
-
-1. **The two paths never overlap.** Capability present -> stream path. Capability
-   absent -> `402`. **Both present -> `400 ambiguous-payment-mode`**, refused
-   rather than guessed: the failure mode of guessing is charging the caller
-   through one path while they believe they paid through the other.
-2. **`payTo` is derived from the operator-signed descriptor**, resolved at
-   startup from the registry for this gateway's `serviceRef`. There is no
-   `payTo` environment variable, and the gateway **refuses to start** if the
-   signed listing cannot be resolved. `payTo` is the one field whose corruption
-   silently redirects money, so it is never configurable and never caller-supplied.
-3. **The price is the seller's and is not signed.** The descriptor schema has
-   `minRatePerSecond`/`maxRatePerSecond` for metered streams and no per-call
-   price field, so a per-call amount can only come from the seller running the
-   gateway. Legitimate — it is their price on their gateway — but a buyer
-   **cannot** cross-check it against the registry the way they can cross-check
-   the payee.
-
-Ordering on a paid request is `verify -> call upstream -> settle -> flush`.
-Settling before the response is flushed means a call that produced nothing is
-never charged for, and a payment that cannot be settled returns `402` rather
-than handing over the goods for free. Both edges favour the buyer.
-
-That ordering has one sharp edge, and it is closed rather than merely noted.
-Because the upstream runs _before_ settlement, an upstream slower than the
-signed authorization's own `validBefore` would produce its **side effects** and
-then be unsettleable — the caller never gets the response body, which is flushed
-only after settlement, but the work would have happened for free. The `exact`
-verifier needs only `validBefore >= now + 6s` while the gateway's upstream
-timeout defaults to 30 s, so the two can genuinely cross. The gateway therefore
-caps each upstream call at `min(upstreamTimeout, validBefore - now - 10s)` and
-returns `402` outright when that leaves no usable window. A payment that cannot
-survive its own round trip is refused before the upstream is touched.
-
-It also refuses before the upstream when the facilitator reports
-`metrik.settleable: false` — see below.
-
-`extra.metrikServiceRef` is published so a client can look the listing up. **The
-facilitator ignores it**, deliberately — it arrives inside a caller-supplied
-body, and reading it would let a caller choose which service's delivery record
-gets checked. There is a test for exactly that.
+under `extra.metrikStreamOpener`, with `amount == price` and `payTo ==
+predict(6 terms)`. An upfront-only quote carries no `refundUrl`. The SDK buyer
+(`payWithX402`, 0.10.0-rc.3) recomputes `payTo` OFFLINE from the registry's
+factory and implementation, runs `validateUpfrontTerms`, requires `price -
+upfrontAmount <= ratePerSecond × maxDuration`, and refuses an upfront part above
+`maxUpfrontAmount` (default 0.10 USDC; `0` refuses any).
+
+The settlement's `PAYMENT-RESPONSE.extra.metrikStreamOpener` is `{streamId
+(null when upfront-only), opener, escrow, deposit (= price - upfrontAmount),
+ratePerSecond, expiresAt (only with a stream), upfrontAmount, upfrontFee,
+refundUrl (only with a stream)}`; `upfrontAmount` and `upfrontFee` are read from
+the opener's `UpfrontCharged` event in the mined receipt.
+
+### What the facilitator checks for an upfront payment
+
+Everything in the table above, plus: the factory is the upfront factory this
+facilitator is bound to (anything not one of its configured factories is
+`metrik_opener_factory_mismatch`); the six terms pass the factory's own
+`validateTerms` rules and `price - upfrontAmount <= ratePerSecond ×
+maxDuration` (`metrik_opener_invalid_terms`); a `termsVersion`, when present,
+is `upfront-1`; `amount == price` (`metrik_opener_invalid_amount`); `payTo ==
+upfrontFactory.predict(terms)` on-chain; and an `eth_call` of the 6-tuple
+`deployAndSettle`. Price/upfront fields on a STREAM-factory quote are refused
+(that `payTo` does not commit to them). `settle` reports success only when the
+receipt shows exactly the signed split: `UpfrontCharged` for this payer, nonce,
+operator and `upfrontAmount` (when non-zero), and — unless upfront-only — the
+escrow's `StreamOpened` and the opener's `StreamOpenedFor` for a deposit of
+exactly `price - upfrontAmount`; an upfront-only receipt must show
+`UpfrontCharged` with `streamId 0` and no stream.
+
+### Running an upfront listing
+
+On the gateway, set `METRIK_GATEWAY_X402V2_UPFRONT_AMOUNT` (base units) next to
+the usual `METRIK_GATEWAY_X402V2_*` variables; its presence selects the upfront
+kind, and the factory defaults to the registry's upfront factory
+(`METRIK_GATEWAY_X402V2_UPFRONT_FACTORY_ADDRESS` overrides it;
+`METRIK_GATEWAY_X402V2_FACTORY_ADDRESS`, which names the stream factory, is
+refused alongside it). At startup the gateway validates the six terms, reads
+the factory's `escrow()`, `usdc()` and `implementation()`, and requires its
+on-chain `predict` to equal the offline CREATE2 derivation the SDK uses; the
+facilitator's marker must advertise exactly this upfront factory in
+`upfrontOpener`. Size `upfrontAmount` to at least the marginal cost of serving
+one call; use `upfrontAmount == price` for calls with nothing ongoing to meter.
+The facilitator settles the registry's upfront factory by default (see
+`METRIK_OPENER_FACILITATOR_UPFRONT_FACTORY_ADDRESS`).
+
+## Getting unearned money back: the gasless refund relay
+
+**There is no automatic refund.** Nothing pushes money back to a payer, and no
+keeper runs in the background. Unearned money comes back only when someone
+calls the relay endpoints below (or calls the opener directly). What the relay
+removes is the need for ETH: a typical x402 payer holds only USDC, so the
+facilitator's relayer pays the gas for the two transactions a refund needs.
+
+The escrow's buyer of record is the opener, so a refund goes through it:
+
+1. **Close** (optional — only to stop before `expiresAt`). `opener.close` is
+   payer-only on-chain, because anyone else could cut a payer's service. The
+   relay submits `opener.closeWithSig` with the payer's EIP-712 signature.
+2. **Reclaim**, once the settlement window allows it: a checkpoint covering the
+   stop time (close, or `expiresAt`) is posted — the oracle posts every
+   ~15–22 s — or `escapeGraceSeconds` (900 s on the live escrow) have passed
+   since the stop. `opener.reclaim(streamId, cumulativeAmount, proof)` is
+   permissionless: the escrow fixes the amount (a Merkle proof against its
+   **latest** checkpoint root) and the opener fixes the destination
+   (`payerOf(streamId)`). The relay fetches the proof from the oracle itself.
+3. **Escape hatch**, only if no usable proof ever appears: after
+   `expiresAt + escapeGraceSeconds` the payer may sign `ReclaimUnverified` and
+   the relay submits `reclaimUnverifiedWithSig`. It returns `deposit -
+claimedCumulative` and forfeits the seller's earned-but-unclaimed revenue, so
+   it is **never** relayed without the payer's signature; the unsigned
+   `reclaimUnverified` is payer-only on-chain and the relay never calls it.
+
+The streamId and the refund URL arrive with the paid response:
+`PAYMENT-RESPONSE.extra.metrikStreamOpener = {streamId, opener, escrow,
+deposit, ratePerSecond, expiresAt, refundUrl}`.
+
+**Upfront openers.** The relay serves the upfront factory's clones too. Which
+factory's `isOpener` claims the stream's buyer, read on-chain, decides the
+opener's kind and so the EIP-712 domain the payer signs under (`"Metrik
+X402UpfrontStreamOpener"` instead of `"Metrik X402StreamOpener"`); the status
+reports `openerKind`, `price`, `upfrontAmount` and `maxRefund` (the deposit, =
+`price - upfrontAmount`) — the upfront part was paid at settlement and can
+never come back. **Stream id 0** is an upfront-only payment: every route
+answers `nothing-to-refund` (`404` for the status, `409` for the actions)
+without a chain read, and no close or reclaim is ever submitted for it.
+
+### Endpoints (on the facilitator service; public, no bearer token)
+
+| Method + path                                | Body                                           | Does                                                            |
+| -------------------------------------------- | ---------------------------------------------- | --------------------------------------------------------------- |
+| `GET /streams/:streamId`                     | —                                              | Status, and exactly what the payer can do next                  |
+| `POST /streams/:streamId/close`              | `{"deadline": "<unix s>", "signature": "0x…"}` | Relays `closeWithSig` (payer's EIP-712 `Close`)                 |
+| `POST /streams/:streamId/reclaim`            | none                                           | Fetches the oracle proof, relays `reclaim`                      |
+| `POST /streams/:streamId/reclaim-unverified` | `{"deadline": "<unix s>", "signature": "0x…"}` | Relays `reclaimUnverifiedWithSig` (payer's `ReclaimUnverified`) |
+
+The payer signs, with the opener as the EIP-712 domain
+(`{name: "Metrik X402StreamOpener", version: "1", chainId, verifyingContract:
+<opener>}`):
 
----
+```
+Close(bytes32 streamId,uint256 nonce,uint256 deadline)
+ReclaimUnverified(bytes32 streamId,uint256 nonce,uint256 deadline)
+```
 
-## Tier 2: the verified-delivery facilitator
-
-`POST /verify` does what any facilitator does — delegated **verbatim** to the
-real `x402/facilitator` `verify()`, so Metrik does not reimplement EIP-3009 —
-and then:
-
-1. Resolve `PaymentRequirements.resource` to a Metrik listing, **by origin,
-   against Metrik's own verified registry view**. Not a Metrik listing? Return
-   the ordinary answer and apply no gate.
-2. Check `payTo` equals the operator who **signed** that listing. If not:
-   `isValid: false, invalidReason: "invalid_exact_evm_payload_recipient_mismatch"`.
-   This is the one check here that protects the payer: without it, anyone could
-   quote a Metrik-listed resource and redirect its payment to their own address.
-3. Ask the oracle for that `serviceRef`'s current delivery verdict.
-   Fresh failure -> `isValid: false`.
-
-`POST /settle` re-runs the entire gate before broadcasting. A facilitator must
-never settle something it would not verify, and `/settle` is reachable without
-`/verify` ever having been called.
-
-### `/settle` spends the operator's money, and is fenced accordingly
-
-This is the part a security review caught, and it is worth stating plainly
-because the shape of the hole is not obvious.
-
-`PaymentRequirementsSchema` accepts **any** `asset`, **any** `payTo`,
-`maxAmountRequired: "0"`, and any valid-URL `resource`. The library's `verify`
-only checks the payload against those same caller-supplied requirements: the
-signature recovers to `authorization.from`, `to === payTo`, the window is valid,
-and `balanceOf(from) >= maxAmountRequired` **on the caller-supplied asset**. An
-attacker signing from their own key to their own address satisfies every one of
-those checks. `settle` then does
-`writeContract({ address: paymentRequirements.asset, ... })`.
-
-So an unfenced `/settle` bound to `0.0.0.0` is a permissionless _"make the
-relayer sign a call to a contract I chose, and pay the gas"_ endpoint. Deploy
-something whose `balanceOf` returns a huge number and whose
-`transferWithAuthorization` burns gas in a loop, sign an authorization over its
-domain from your own key to your own address, and POST it until the relayer is
-dry — at which point legitimate settlement stops too. No funds are stolen, but
-it is the operator's money and it induces the operator's key to sign
-transactions to contracts they never chose.
-
-Four controls, all enforced before the settler is reached:
-
-| Control                             | Env                                                          | Why                                                                                                                               |
-| ----------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
-| **Asset allowlist**                 | `METRIK_X402_SETTLEMENT_ASSETS` (default: the chain's USDC)  | **The one that removes the arbitrary-contract-call primitive.** The relayer will only ever be asked to call an approved token.    |
-| **Bearer token on `/settle`**       | `METRIK_X402_FACILITATOR_TOKEN` (>= 32 chars)                | `/settle` is not a public read. Constant-time compare; a missing configured token DENIES. `/verify` and `/supported` stay public. |
-| **Settlement scope**                | `METRIK_X402_SETTLEMENT_SCOPE` (default `tracked-resources`) | The relayer pays gas only for resources that resolve to exactly one signed Metrik listing.                                        |
-| **Network match + non-zero amount** | —                                                            | A zero-value settlement moves nothing and only burns gas; a foreign network is not ours to settle.                                |
-
-A settling facilitator **refuses to start** without a token, and the facilitator
-object refuses to be constructed with an empty asset allowlist. Both are startup
-failures rather than request-time ones, so a misconfiguration is loud.
-
-**The scope default is deliberately asymmetric with the delivery gate, and the
-asymmetry is the point.** An OPINION about a service costs nothing, so `/verify`
-stays universal and fails open on absent evidence. BROADCASTING costs the
-operator real gas, so `/settle` fails closed — including when the registry
-cannot be read, where `/verify` still answers and `/settle` does not. This is
-not a censorship lever: Metrik declining to spend _its own_ gas does not stop
-anyone being paid, because any other facilitator (or the payer's own relayer)
-can settle the same payment. Operators who want a general-purpose facilitator on
-a relayer they are content to fund for anyone's traffic set
-`METRIK_X402_SETTLEMENT_SCOPE=any-resource`; the asset allowlist still applies.
-
-`/verify` reports `metrik.settleable` so a resource server learns **before it
-does any work** whether this relayer would actually broadcast, instead of
-executing the request and then discovering it cannot be paid for.
-
-### Origin resolution, and origin squatting
-
-A listing owns an ORIGIN (scheme + host + port); matching on origin means a
-seller does not have to re-register every route. An origin claimed by **two
-different services is unresolvable**, not first-come-first-served. Picking the
-first claimant made the outcome depend on the registry's read order, so a second
-signed listing claiming a victim's origin could take over the victim's gate and
-permanently refuse their payments. That is not exploitable while listing
-insertion requires an operator-held key — but marking the origin unresolvable
-costs nothing and removes the primitive before registration ever opens. A single
-listing naming the same origin through several fields (`publicUrl`,
-`interface.baseUrl`, `callerAuth.accessUrl`) is not a conflict.
-
-### Only gate what Metrik actually tracks
-
-A resource that maps to no Metrik listing gets the ordinary facilitator answer,
-unchanged. Refusing payments for services Metrik has no opinion about would not
-be caution — it would be a broken facilitator.
-
-### Which `invalidReason`
-
-`invalidReason` is a **closed enum**. There is no member for "this service is not
-delivering", and inventing one breaks every conformant client that parses the
-field. The choice is between imperfect members:
-
-| Candidate                                                                      | Why not                                                                                                                                                                                                         |
-| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `insufficient_funds`, `invalid_payload`, `invalid_exact_evm_payload_signature` | Active lies. They send a developer to debug a wallet that is working correctly.                                                                                                                                 |
-| `unexpected_verify_error`                                                      | Also false. This refusal is deliberate and expected, not an error.                                                                                                                                              |
-| **`invalid_payment_requirements`**                                             | **Chosen.** The only member pointing at the _requirements_ side of the exchange — which is exactly where the problem is: Metrik will not settle a payment quoted for _this resource_ to _this payee_ right now. |
-
-The real explanation travels in a `metrik` object alongside the standard fields:
+`nonce` is the payer's current `opener.nonces(payer)`; `deadline` must be at
+least 60 s after the current chain time. `GET /streams/:streamId` returns the
+ready-to-sign typed data (with the current nonce) under `next.typedData`, so a
+client signs it as-is after choosing a deadline. An optional `"nonce"` in the
+body turns a stale nonce into a clear `409 nonce-mismatch`.
+
+`GET /streams/:streamId` answers `200` with:
 
 ```json
 {
-  "isValid": false,
-  "invalidReason": "invalid_payment_requirements",
-  "payer": "0x...",
-  "metrik": {
-    "gate": "refused",
-    "serviceRef": "0x...",
-    "deliveryVerdict": "failing",
-    "deliveryReason": "fresh-failing",
-    "verdictAgeSeconds": 18,
-    "freshnessWindowSeconds": 90,
-    "detail": "Metrik's oracle reports this service as FAILING its delivery checks ..."
-  }
+  "streamId": "0x…",
+  "chainId": 84532,
+  "escrow": "0x…",
+  "factory": "0x…",
+  "opener": "0x…",
+  "payer": "0x…",
+  "operator": "0x…",
+  "serviceRef": "0x…",
+  "deposit": "60000",
+  "ratePerSecond": "1000",
+  "claimedCumulative": "0",
+  "openedAt": 1790452888,
+  "expiresAt": 1790452948,
+  "closedAt": 1790452902,
+  "status": "closed",
+  "reclaimed": false,
+  "chainTime": 1790452910,
+  "settlement": {
+    "stopAt": 1790452902,
+    "latestCheckpointCheckedAt": 1790452904,
+    "checkpointCoversStop": true,
+    "fallbackAt": 1790453802,
+    "escapeHatchAt": 1790453848
+  },
+  "oracle": {
+    "cumulativeAmount": "14000",
+    "checkpointId": "61222",
+    "checkedAt": 1790452904,
+    "root": "0x…"
+  },
+  "reclaimable": "46000",
+  "payerNonce": "1",
+  "next": {
+    "action": "reclaim",
+    "method": "POST",
+    "path": "/streams/0x…/reclaim",
+    "message": "…"
+  },
+  "refunds": "There is no automatic refund. …"
 }
 ```
 
-`VerifyResponseSchema` is a `strip` (not `strict`) Zod object, so this is
-spec-tolerated: a conformant client parses the response successfully and simply
-drops `metrik`. A client that wants the reason reads it off the raw body. There
-is a test asserting exactly that.
-
-### Staleness: a 90-second window, and why
-
-A verdict from ten minutes ago is not evidence that a service is alive now, so
-freshness is the crux. The oracle records a status per active stream on its
-checkpoint cadence of **~15–22 s**. The window has to be wide enough that
-ordinary jitter does not flap the gate and narrow enough that "verified" still
-means "now":
-
-- three worst-case probe intervals (3 x 22 s = **66 s**) absorbs two consecutive
-  missed or slow ticks, which is operational noise rather than a dead service;
-- plus the oracle's record-and-serve latency and the facilitator's fetch round
-  trip, rounded up: **90 s**.
-
-Tighter (say 30 s) and one slow tick turns a healthy service indeterminate.
-Looser and a service that died four minutes ago still reads `delivering`, which
-is precisely the claim this gate exists to avoid making. Note the oracle's own
-TTL is **300 s**, so this window is strictly stricter: a verdict aged 90–300 s
-reads `delivering` at the source and `indeterminate` here.
-
-Staleness is applied **symmetrically**. A stale _failure_ is not evidence either,
-so one bad probe cannot silently refuse forever.
-
-### No fresh evidence: allow, by default
-
-There are three distinct ways to have no opinion, and they are never collapsed
-into "failing":
-
-| Situation                                                                 | `metrik.gate`                          |
-| ------------------------------------------------------------------------- | -------------------------------------- |
-| Service has no row at all (no active stream), or oracle says `unverified` | `indeterminate`                        |
-| Verdict older than the freshness window                                   | `indeterminate` (`verdict-stale`)      |
-| Oracle unreachable or malformed                                           | `indeterminate` (`oracle-unreachable`) |
-| Metrik cannot read its own registry                                       | `registry-unavailable`                 |
-
-All of them **allow** by default. The standing Metrik rule is buyer-favouring
-and still is — but that rule governs the case where Metrik **holds** the buyer's
-money and must decide whether to release it. Here Metrik holds nothing, so
-refusing does not protect anyone's funds; it only denies a service the buyer
-asked to buy, on a rail that works fine without Metrik. Four reasons:
-
-1. **Absent evidence is the normal case.** The oracle's `/services` projection is
-   built from ACTIVE STREAMS. A service with no live Metrik stream has no row at
-   all — on the live oracle today, `GET /services` returns `{"services":[]}`.
-   Failing closed would refuse **100% of payments**. That is a broken
-   facilitator, not a careful one.
-2. **Fail-closed is a censorship lever.** If "oracle down" meant "no payments",
-   anyone who could degrade Metrik's oracle could block payments to a competitor
-   listed on it. `allow` removes that lever.
-3. **The harms are asymmetric.** A wrong refusal denies the service outright. A
-   wrong allowance passes one `exact` payment, at a price the buyer already
-   agreed to, worth one call.
-4. **A pass never claims anything.** `isValid: true` with `gate: "indeterminate"`
-   says "no fresh evidence", in the response, in words.
-
-A **fresh** failure is refused under every policy.
-
-Set `METRIK_X402_INDETERMINATE_POLICY=deny` to require positive fresh evidence
-instead. That is a real, supported, tested choice — it is just not a safe
-default.
+`closedAt` is `null` while active; `oracle` and `reclaimable` are `null` when
+no proof that matches the escrow's on-chain latest root is available (with an
+`oracleNote`). `next.action` is one of `close` (with `typedData` and the body
+shape), `wait` (with `retryAt` / `retryAfterSeconds`), `reclaim`,
+`reclaim-unverified` (with `typedData`), or `none`.
 
----
+A successful relayed transaction answers `200` only from its **mined** receipt:
 
-## Running it
-
-```bash
-# The facilitator
-METRIK_X402_RPC_URL=https://sepolia.base.org \
-METRIK_X402_RELAYER_PRIVATE_KEY=0x...        \
-  npx metrik-x402-facilitator
-
-# A seller's gateway, quoting 0.001 USDC per call through it
-METRIK_GATEWAY_X402_PRICE_BASE_UNITS=1000 \
-METRIK_GATEWAY_X402_FACILITATOR_URL=https://facilitator.example \
-METRIK_GATEWAY_X402_RESOURCE_BASE_URL=https://svc.example \
-  npx metrik-gateway
+```json
+{ "ok": true, "action": "close", "streamId": "0x…", "opener": "0x…",
+  "payer": "0x…", "transaction": "0x…", "message": "…", "next": { "path": "/streams/0x…/reclaim" } }
+{ "ok": true, "action": "reclaim", "streamId": "0x…", "opener": "0x…",
+  "payer": "0x…", "amount": "46000", "entitlement": "14000", "transaction": "0x…", "message": "…" }
 ```
 
-The facilitator **refuses to start** without `METRIK_X402_RELAYER_PRIVATE_KEY`
-unless `METRIK_X402_ALLOW_VERIFY_ONLY=true` is set explicitly. A facilitator that
-accepts `/settle` and quietly never broadcasts is worse than one that is absent.
-
-### Settlement is built but has never broadcast anything
+(`action` is `reclaim-unverified` for the escape hatch.) Every refusal is
+`{"ok": false, "error": "<code>", "message": "…", …}`, with `Retry-After`
+where a retry makes sense:
+
+| Status | `error`                                                                                         | Meaning                                                                                     |
+| ------ | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| 400    | `invalid-stream-id`, `invalid-request`, `invalid-json`                                          | Malformed input                                                                             |
+| 403    | `invalid-signature`, `signature-expired`                                                        | Not the payer's EIP-712 signature for this opener, stream and nonce; or deadline too near   |
+| 404    | `not-found`                                                                                     | Unknown stream, or its buyer is not an opener of the configured factory                     |
+| 409    | `already-closed`, `stream-expired`, `already-reclaimed`, `nothing-to-reclaim`, `nonce-mismatch` | Would have no effect; nothing sent                                                          |
+| 409    | `not-reclaimable-yet`, `settlement-window-open`, `proof-unavailable`, `escape-hatch-not-ready`  | Not yet; `retryAt` (unix s) says when at the latest                                         |
+| 409    | `simulation-failed`, `in-progress`, `blocked`                                                   | The simulation reverted; a relayed tx is in flight; an earlier tx had an unexpected outcome |
+| 202    | `pending`                                                                                       | Sent, not mined yet (`transaction`); repeat the same request — it is never re-sent          |
+| 429    | `rate-limited`                                                                                  | Per-IP, per-stream or global budget exhausted                                               |
+| 502    | `transaction-reverted`, `unexpected-receipt`, `submission-failed`                               | Never a success without the expected mined receipt                                          |
+| 503    | `chain-unavailable`, `oracle-unavailable`, `opener-domain-mismatch`                             | Fail closed                                                                                 |
+
+### Bounded against gas abuse
+
+- **Opener streams only.** `factory.isOpener(stream.buyer)` is read on-chain
+  first; every other stream is `404` before any signature check, oracle call or
+  simulation.
+- **No effect, no transaction.** Every precondition the contract checks is read
+  first (status, expiry, settlement window, `reclaimed`, a non-zero refund). A
+  reclaim's simulation must return exactly the non-zero `reclaimableFor`
+  amount. Nothing is broadcast without a successful simulation.
+- **Proofs are checked, not trusted.** The oracle's proof must be for this
+  stream, verify under the escrow's leaf
+  `keccak256(bytes.concat(keccak256(abi.encode(streamId, cumulative))))`, and
+  its root must equal the escrow's on-chain `latestCheckpointRoot`. A tampered
+  proof (for example one claiming less delivery) is refused without a
+  transaction; the contract would refuse it anyway.
+- **At most one successful close and one successful reclaim per stream** from
+  a facilitator instance (the proof and escape-hatch paths share the reclaim
+  slot, as the escrow allows one). Concurrent duplicates are refused
+  synchronously; a repeat after success is refused without any transaction.
+- **Read fan-out is bounded.** Every `/streams` request (read or write) counts
+  against a per-client-IP limit AND an IP-independent global limit (default
+  120/min, `429` + `Retry-After`). A stream's status and its oracle proof are
+  reused for a few seconds (default 5 s), so repeated requests for one stream
+  do not re-hit the RPC or the oracle; the cache for a stream is dropped as
+  soon as a relayed transaction for it is mined, and a broadcast is still
+  decided by a fresh simulation.
+- **No internal errors leak.** RPC, oracle and simulation failures are
+  answered with a generic message and an error code (`chain-unavailable`,
+  `oracle-unavailable`, `simulation-failed`, `submission-failed`); the detail
+  is logged server-side with URL paths redacted, never the relayer key. Only
+  a decoded contract custom-error name (for example `StreamClosedAlready`) is
+  returned.
+- **Budgets.** Per client IP (all `/streams` routes), per stream (relayed
+  submission attempts) and globally per minute. Refused requests — a forged
+  signature, a request with no effect — do not consume a stream's budget, so
+  spamming cannot lock a payer out.
+- **Receipts.** Success only from a mined receipt with the escrow's
+  `StreamClosed` / `BuyerReclaimed` and the opener's `StreamCloseRequested` /
+  `ReclaimForwarded` for exactly this stream, payer and amount.
+- **One relayer queue.** Relay submissions and `deployAndSettle` go through the
+  same serialized queue, so they never race for the relayer's nonce.
+
+## Running the facilitator
 
-`POST /settle` is implemented end to end and delegates to the real `x402`
-`settle()`, which submits the EIP-3009 `transferWithAuthorization`. **It has
-never been run against a live chain from this repo**, because that needs a
-relayer wallet funded with gas, which does not exist yet. What is missing is a
-key and gas, not code. Until then:
-
-- no relayer key -> the server will not start (or runs verify-only and returns
-  `503` on `/settle`);
-- every test settles through a recording fixture that broadcasts nothing.
-
-Nothing in this repo has ever sent an x402 settlement transaction.
-
----
+```bash
+METRIK_OPENER_FACILITATOR_ENABLED=1 \
+METRIK_OPENER_FACILITATOR_RPC_URL=https://sepolia.base.org \
+METRIK_OPENER_FACILITATOR_RELAYER_PRIVATE_KEY=<from your secret store> \
+METRIK_OPENER_FACILITATOR_AUTH_TOKEN=<at least 32 random characters> \
+npx metrik-x402-opener-facilitator
+```
 
-## What x402 actually is, as shipped
-
-All of the following was verified against the published packages and the
-specification repository (see [Evidence](#evidence) for how, and when).
-
-| Thing                                    | Reality                                                                                             |
-| ---------------------------------------- | --------------------------------------------------------------------------------------------------- |
-| Spec repository                          | [`x402-foundation/x402`](https://github.com/x402-foundation/x402)                                   |
-| Published client/server packages         | `x402`, `x402-fetch`, `x402-axios`, `x402-express`, `x402-hono`, `x402-next`                        |
-| Version of `x402` on npm                 | **1.2.0**, Apache-2.0, no `engines` constraint                                                      |
-| Protocol versions the package implements | **`x402Version: 1` only** (`x402Versions === [1]`)                                                  |
-| Payment schemes the package implements   | **`exact` only** (`schemes === ["exact"]`)                                                          |
-| Schemes that exist _in the spec_         | `exact`, `upto`, `batch-settlement`, `auth-capture`                                                 |
-| Transport (v1, shipped)                  | HTTP `402` + `X-PAYMENT` request header + `X-PAYMENT-RESPONSE` response header                      |
-| Transport (v2, spec-only)                | `PAYMENT-REQUIRED` / `PAYMENT-SIGNATURE` / `PAYMENT-RESPONSE` headers — **renamed**, no `X-` prefix |
-| Facilitator interface                    | `POST /verify`, `POST /settle`, `GET /supported`                                                    |
-
-Two gaps matter enormously and are easy to miss:
-
-1. **The spec is ahead of the shipped code.** `auth-capture` and `upto` are
-   written up under `specs/schemes/` but are _not_ in `x402@1.2.0`. The package's
-   `PaymentRequirementsSchema` parses `scheme` as a closed Zod enum containing
-   exactly one value, `"exact"`. A `PaymentRequirements` naming any other scheme —
-   including `auth-capture` and `upto` — is **rejected by the real library**.
-2. **x402 v2 is specified but not shipped.** `x402-specification-v2.md` defines
-   `x402Version: 2` with CAIP-2 network identifiers (`eip155:8453`) and an
-   explicitly extensible `scheme` _string_. `x402@1.2.0` implements v1, whose
-   `network` is a closed enum of bare names (`base-sepolia`, `base`, …). So the
-   extensibility that would make room for a Metrik scheme exists on paper, not in
-   the library your users will install.
-
-### The `exact` scheme, concretely
+| Variable                                                             | Default                               | Meaning                                                                              |
+| -------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------ |
+| `METRIK_OPENER_FACILITATOR_ENABLED`                                  | off                                   | Must be truthy or the service refuses to start.                                      |
+| `METRIK_OPENER_FACILITATOR_RPC_URL`                                  | required                              | RPC for reads, simulation and the settlement transaction.                            |
+| `METRIK_OPENER_FACILITATOR_RELAYER_PRIVATE_KEY`                      | required                              | Pays gas for `deployAndSettle`. Never holds buyer funds; never logged.               |
+| `METRIK_OPENER_FACILITATOR_AUTH_TOKEN`                               | required (≥ 32 chars)                 | Bearer token required on `/settle`.                                                  |
+| `METRIK_OPENER_FACILITATOR_FACTORY_ADDRESS`                          | the Base Sepolia factory              | Required on any other chain.                                                         |
+| `METRIK_OPENER_FACILITATOR_UPFRONT_FACTORY_ADDRESS`                  | the registry's, for the escrow        | Upfront opener factory settled too (same escrow and token); `off` disables it.       |
+| `METRIK_OPENER_FACILITATOR_ESCROW_ADDRESS`                           | live Base Sepolia `StreamEscrowV2`    | Must equal `factory.escrow()`.                                                       |
+| `METRIK_OPENER_FACILITATOR_NETWORK`                                  | `eip155:84532`                        | Must match the RPC's chain id.                                                       |
+| `METRIK_OPENER_FACILITATOR_ASSETS`                                   | Circle test USDC                      | Comma-separated allowlist; must contain `factory.usdc()`.                            |
+| `METRIK_OPENER_FACILITATOR_REGISTRY_URL`                             | `https://oracle.metrik.live/listings` | Where operator-signed listings are read.                                             |
+| `METRIK_OPENER_FACILITATOR_LISTING_CACHE_SECONDS`                    | `60`                                  | Reuse of a successful registry read (failures are never cached).                     |
+| `METRIK_OPENER_FACILITATOR_RECEIPT_TIMEOUT_SECONDS`                  | `60`                                  | Receipt wait before `settlement_pending`.                                            |
+| `METRIK_OPENER_FACILITATOR_REQUIRE_AUTH_ON_VERIFY`                   | **on**                                | Require the token on `/verify` too; `0` opts out explicitly.                         |
+| `METRIK_OPENER_FACILITATOR_MIN_AMOUNT`                               | `10000` (0.01 USDC)                   | Smallest accepted payment; advertised in the marker.                                 |
+| `METRIK_OPENER_FACILITATOR_SETTLE_RATE_LIMIT_PER_MINUTE`             | `60`                                  | Authorized `/settle` calls per token per minute; beyond it `429`.                    |
+| `METRIK_OPENER_FACILITATOR_HOST` / `_PORT` (or `PORT`)               | `127.0.0.1` / `8788`                  | Bind address. Put TLS in front of it.                                                |
+| `METRIK_OPENER_FACILITATOR_REFUND_RELAY`                             | **on**                                | The gasless refund relay; `0` switches it off (a gateway then refuses to start).     |
+| `METRIK_OPENER_FACILITATOR_ORACLE_URL`                               | `https://oracle.metrik.live`          | Serves `GET /checkpoint/proof?streamId=`. Required off Base Sepolia.                 |
+| `METRIK_OPENER_FACILITATOR_PUBLIC_URL`                               | unset                                 | Public origin, for absolute links (`next.url`) in relay responses.                   |
+| `METRIK_OPENER_FACILITATOR_REFUND_RATE_LIMIT_PER_IP_PER_MINUTE`      | `30`                                  | `/streams/*` requests per client IP per minute.                                      |
+| `METRIK_OPENER_FACILITATOR_REFUND_GLOBAL_RATE_LIMIT_PER_MINUTE`      | `120`                                 | `/streams/*` requests per minute from all clients together (IP-independent).         |
+| `METRIK_OPENER_FACILITATOR_REFUND_READ_CACHE_SECONDS`                | `5`                                   | Reuse of one stream's status and oracle proof; `0` disables.                         |
+| `METRIK_OPENER_FACILITATOR_REFUND_SUBMISSIONS_PER_STREAM_PER_MINUTE` | `3`                                   | Relayed transactions per stream per minute.                                          |
+| `METRIK_OPENER_FACILITATOR_REFUND_SUBMISSIONS_PER_MINUTE`            | `30`                                  | Relayed refund transactions per minute, all streams.                                 |
+| `METRIK_OPENER_FACILITATOR_TRUST_PROXY`                              | off                                   | Key the per-IP limit on the right-most `X-Forwarded-For` hop. See the warning below. |
+
+> **`TRUST_PROXY=1` is only safe when the service is bound to loopback
+> (`METRIK_OPENER_FACILITATOR_HOST=127.0.0.1`, the default) behind a reverse
+> proxy that overwrites `X-Forwarded-For` with the address it actually saw
+> (Caddy's `reverse_proxy` does).** Never enable it when the port is reachable
+> directly: any client could then send its own `X-Forwarded-For` and get a
+> fresh per-IP budget on every request. The global cap still applies either
+> way.
+
+At startup it proves the wiring (RPC chain id, factory code, `factory.escrow()`,
+`factory.usdc()` allowlisted; for the relay, `factory.escrow()` and the escrow's
+`escapeGraceSeconds`) and refuses to start otherwise. Endpoints:
+`GET /supported`, `POST /verify`, `POST /settle` (bearer), `GET /health`, and
+the refund relay's `GET /streams/:streamId` and
+`POST /streams/:streamId/{close,reclaim,reclaim-unverified}` (public).
+
+## Running the gateway in x402 mode
+
+The gateway's normal variables (`METRIK_GATEWAY_ESCROW_ADDRESS`,
+`METRIK_GATEWAY_RPC_URL`, `METRIK_GATEWAY_SERVICE_REF`,
+`METRIK_GATEWAY_UPSTREAM_URL`, …) are unchanged. The listing is the primary
+`METRIK_GATEWAY_SERVICE_REF`. Add:
+
+| Variable                                                         | Default                            | Meaning                                                                                                                                   |
+| ---------------------------------------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `METRIK_GATEWAY_X402V2_OPENER`                                   | off                                | Truthy to enable the mode.                                                                                                                |
+| `METRIK_GATEWAY_X402V2_FACILITATOR_URL`                          | required                           | The Metrik opener facilitator.                                                                                                            |
+| `METRIK_GATEWAY_X402V2_FACILITATOR_TOKEN`                        | required                           | Its `/settle` bearer token.                                                                                                               |
+| `METRIK_GATEWAY_X402V2_OPERATOR`                                 | required                           | Must be the operator that signed the listing.                                                                                             |
+| `METRIK_GATEWAY_X402V2_RATE_PER_SECOND`                          | required                           | USDC base units per second.                                                                                                               |
+| `METRIK_GATEWAY_X402V2_MAX_DURATION_SECONDS`                     | required                           | Stream lifetime.                                                                                                                          |
+| `METRIK_GATEWAY_X402V2_PRICE`                                    | required                           | Base units per paid request (= deposit); `0 < price <= rate × maxDuration`.                                                               |
+| `METRIK_GATEWAY_X402V2_FACTORY_ADDRESS`                          | the Base Sepolia factory           | Required on any other chain.                                                                                                              |
+| `METRIK_GATEWAY_X402V2_UPFRONT_AMOUNT`                           | unset (stream kind)                | Set = the upfront kind: the non-refundable per-call part, base units, `<= PRICE`; `PRICE - it <= rate × maxDuration`.                     |
+| `METRIK_GATEWAY_X402V2_UPFRONT_FACTORY_ADDRESS`                  | the registry's upfront factory     | Only with `_UPFRONT_AMOUNT`.                                                                                                              |
+| `METRIK_GATEWAY_X402V2_NETWORK`                                  | `eip155:<METRIK_GATEWAY_CHAIN_ID>` | Must match the chain id.                                                                                                                  |
+| `METRIK_GATEWAY_X402V2_ASSET` / `_ASSET_NAME` / `_ASSET_VERSION` | Circle test USDC / `USDC` / `2`    | Token and its EIP-712 domain.                                                                                                             |
+| `METRIK_GATEWAY_X402V2_MAX_TIMEOUT_SECONDS`                      | `300`                              | Authorization validity the client signs for.                                                                                              |
+| `METRIK_GATEWAY_X402V2_FACILITATOR_TIMEOUT_SECONDS`              | `120`                              | Per-request facilitator timeout; must exceed its receipt wait by 30 s.                                                                    |
+| `METRIK_GATEWAY_X402V2_RESOURCE_BASE_URL`                        | derived from `Host`                | Public origin used in the 402 `resource.url`.                                                                                             |
+| `METRIK_GATEWAY_X402V2_REGISTRY_URL`                             | the public registry                | Where the listing is proven at startup.                                                                                                   |
+| `METRIK_GATEWAY_X402V2_REFUND_BASE_URL`                          | the facilitator URL                | Public base of the refund relay advertised in the 402. If different, its `/supported` must show the same marker with `refundRelay: true`. |
+| `METRIK_GATEWAY_X402V2_DOCS_URL`                                 | this document on GitHub            | Docs link in the 402.                                                                                                                     |
+| `METRIK_GATEWAY_X402V2_ASSET_DECIMALS`                           | `6`                                | Decimals for the amounts in the 402 description.                                                                                          |
+| `METRIK_GATEWAY_X402V2_DESCRIPTION`                              | unset                              | One sentence on what the service does, prefixed to the fixed disclosure.                                                                  |
+| `METRIK_GATEWAY_X402V2_SCHEMA`                                   | unset                              | JSON `{info: {input, output}, schema}`, declared as `extensions.bazaar` (declared only, never registered).                                |
+
+These names deliberately differ from the removed v1 mode's variables, so a
+leftover v1 environment can never switch a payment mode on.
+
+At startup the gateway validates the terms and price, proves the listing is
+operator-signed, checks `factory.escrow()` and `factory.usdc()`, computes
+`payTo = factory.predict(terms)`, and checks the facilitator's marker —
+including `refundRelay: true`, because the 402 promises a refund path without
+ETH — plus the marker at a separate refund base URL; any failure stops it from
+starting. The advertised window is `METRIK_GATEWAY_X402V2_MAX_DURATION_SECONDS`
+(for example `60`, with `RATE_PER_SECOND=1000` and `PRICE=60000`).
+
+### What the 402 says
+
+The resource `description` states plainly what one payment buys; an operator
+`DESCRIPTION` can only be prefixed to it. With a 60 s window at 1000 base
+units/s and a price of 60000:
+
+> Pays for one call. Your payment of 0.06 USDC funds a Metrik escrow stream of
+> 60 seconds at 0.001 USDC/s; the seller earns only for seconds Metrik's
+> verifier confirms the service is delivering, and anything unearned is
+> refundable to you (no ETH needed) via
+> https://&lt;facilitator&gt;/streams/{streamId}. Refunds are not automatic: close
+> the stream and reclaim there, using the streamId from the PAYMENT-RESPONSE.
+> Docs: &lt;docs URL&gt;
+
+When the price is below `rate × window`, it adds "(the seller can earn at most
+&lt;price&gt;)". An upfront listing (price 0.06, upfront 0.015) states the split:
+
+> Pays for one call: 0.06 USDC in total. 0.015 USDC is a NON-REFUNDABLE per-call
+> charge, paid to the seller at settlement whatever is delivered. The remaining
+> 0.045 USDC is metered and refundable: it funds a Metrik escrow stream of …;
+> the seller earns it only for seconds Metrik's verifier confirms the service is
+> delivering, and any unearned part of it (at most 0.045 USDC) is refundable to
+> you (no ETH needed) via …. Refunds are not automatic: …
+
+and an upfront-only one says the whole price is charged in full at settlement,
+is not refundable, and that nothing is metered or refundable. `extra.metrikStreamOpener` also carries `refundUrl` (the
+template) and `docsUrl`; the facilitator accepts exactly these two
+informational http(s) links on top of the terms, never uses them for
+settlement, and still refuses any other key. "Verified" here means verified
+delivery, not verified output.
+
+| Request carries                                            | Result                                                                                |
+| ---------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| nothing                                                    | `402`, `PAYMENT-REQUIRED` quoting the opener `payTo` and the price                    |
+| `PAYMENT-SIGNATURE`                                        | verified → upstream → settled if upstream `< 400` → `200` + body + `PAYMENT-RESPONSE` |
+| `PAYMENT-SIGNATURE`, upstream `>= 400`                     | upstream response, nothing settled                                                    |
+| `PAYMENT-SIGNATURE`, settle fails                          | `402` + `PAYMENT-RESPONSE`, no upstream body                                          |
+| `x-metrik-capability`                                      | the capability path, unchanged                                                        |
+| capability **and** `PAYMENT-SIGNATURE`                     | `400 ambiguous-capability-and-payment`                                                |
+| probe capability **and** `PAYMENT-SIGNATURE`               | `400 ambiguous-probe-mode`                                                            |
+| any request while the facilitator marker cannot be proven  | `503 x402-facilitator-unavailable`                                                    |
+| a `PAYMENT-SIGNATURE` already in flight or already settled | `409 x402-payment-already-used`, no upstream call                                     |
+
+With `METRIK_GATEWAY_X402V2_OPENER` unset the gateway is byte for byte the
+capability-only gateway (`test/gateway-http-baseline.test.ts`), and the
+`@x402/*` packages are never loaded.
+
+## Paying as a buyer: `metrik pay`, MCP `x402_pay`, `@absol-labs/agent/x402-buyer`
+
+The buyer side is the SDK's `payWithX402` (`@absol-labs/sdk/x402`) with every SDK
+protection intact, wrapped by `payX402WithMandate` (`@absol-labs/agent/x402-buyer`)
+so the package's golden rule holds: **no spend without a mandate**. A Metrik x402
+payment opens a stream, so it is checked as the stream open it is:
+
+| Mandate cap            | x402 quote field                       |
+| ---------------------- | -------------------------------------- |
+| `maxPerStreamUsdc`     | `amount` (the whole price of the call) |
+| `maxTotalUsdc`         | spent so far + `amount`                |
+| `maxRatePerSecondUsdc` | `ratePerSecond`                        |
+| `maxDurationSeconds`   | `maxDuration`                          |
+| `allowedOperators`     | `operator`                             |
+
+The mandate's signature, expiry, revocation, owner (= the payer) and chain are
+verified before the seller is contacted. The per-quote check runs in the SDK's
+`onQuote` hook — after the SDK has proven `payTo == factory.predict(terms)` on
+chain and before anything is signed — and the caps are also passed to the SDK as
+`maxAmount` / `maxRatePerSecond`. A quote without opener terms is refused
+(`X402MandateDeniedError` reason `not-an-opener-quote`).
+
+For an upfront quote the mandate counts the WHOLE price, upfront part included,
+as spend (`budgetUsdc = price`); that part is non-recoverable and nothing a
+refund returns is credited back. Its size is also capped separately before
+signing by `maxUpfrontAmount` (`metrik pay --max-upfront`, MCP
+`maxUpfrontAmountUsdc`; default 0.10 USDC, `0` refuses any upfront charge). The
+split is shown before signing and in the result. An upfront-only payment
+(`streamId: null`) is final: `metrik pay` prints no refund or reclaim command,
+`metrik refund 0x00…00` and the MCP refund tools answer "nothing to refund"
+(exit 0 / not an error), and the MCP server records no stream for it — only a
+non-stream charge that still counts against the mandate.
 
-`exact` on EVM is an [EIP-3009](https://eips.ethereum.org/EIPS/eip-3009)
-`transferWithAuthorization`: the client signs `{from, to, value, validAfter,
-validBefore, nonce}`, and the facilitator submits exactly that one transfer.
+```bash
+metrik pay https://x402.137.23.50.249.sslip.io/transform --json '{"text":"# hi"}' --max-amount 0.1
+metrik refund <streamId> --refund-url <url printed above> --close --reclaim
+```
 
-That is the whole scheme. One fixed amount. One transfer. Straight to the payee.
-**No escrow, no hold, no conditional release, no partial capture, no refund, no
-reclaim.**
+The MCP server offers the same as `x402_pay`, `refund_status` and `refund`
+(see [mcp-reference.md](./mcp-reference.md)); `x402_pay` shares the server
+mandate and cumulative spend with `hire_verified_service`. Refunds are still
+**requested, never pushed**: `metrik refund` / `refund` call the relay; nothing
+calls it for you.
+
+The facilitator's `PAYMENT-RESPONSE` `extra.metrikStreamOpener.expiresAt` is a
+JSON **number** (it was a decimal string before metrik-agent#121, which the SDK's
+strict parser rejects after settlement — a facilitator deployed before that fix
+must be redeployed).
+
+## Network configuration
+
+Network, USDC (and its EIP-712 domain), escrow, opener factory and oracle all
+default from the `@absol-labs/sdk` network registry entry for the configured
+CAIP-2 network (`METRIK_OPENER_FACILITATOR_NETWORK`, `METRIK_GATEWAY_CHAIN_ID` /
+`METRIK_GATEWAY_X402V2_NETWORK`); every one has an env override, and on a network
+the registry does not know (or one with no opener factory) each must be given
+explicitly. The refund relay computes the no-proof escape hatch per escrow
+generation (`escrow.generation`): V2 `expiresAt + escapeGraceSeconds`, V3
+`min(expiresAt, closedAt) + escapeGraceSeconds` read from the escrow's
+`escapeHatchReadyAt` view.
+
+## Programmatic use
+
+Everything lives under the `@absol-labs/agent/x402-opener` subpath (the root
+barrel does not load `@x402/*`): `MetrikOpenerExactScheme`,
+`buildOpenerFacilitator`, `createOpenerFacilitatorServer`, `OpenerRefundRelay`,
+`openerActionTypedData`, `checkpointLeaf`, `RelayerQueue`,
+`RegistryListingResolver`, `readOpenerFacilitatorMarker`, the vendored
+`x402StreamOpenerFactoryAbi` / `x402StreamOpenerAbi`, and the terms helpers.
+The gateway mode is `buildGatewayX402OpenerMode` in
+`@absol-labs/agent/gateway/x402-opener-mode`, passed to
+`createCallerAuthGatewayServer({ x402Opener })`.
+
+## Honest limits
+
+- **Refunds are requested, never pushed.** There is no automatic refund: the
+  relay acts only when an endpoint is called, and a payer who never calls it
+  (or never has anyone call `reclaim` for them) gets nothing back. `metrik
+refund` and the MCP `refund` tool call it on request; `metrik close` /
+  `metrik reclaim` also route an opener stream through the opener directly.
+- **The relay depends on the oracle for proofs.** If the oracle's latest
+  checkpoint never includes the stream, the proof-based reclaim cannot run and
+  the payer-signed escape hatch (after `expiresAt + escapeGraceSeconds`) is the
+  way out. The relay ledgers are in-memory and per instance, like the
+  settlement ledger; the on-chain contracts still allow only one close and one
+  reclaim per stream regardless.
+- **An upfront charge is final.** With an upfront listing the `upfrontAmount`
+  is paid to the seller at settlement whatever is delivered; only `price -
+upfrontAmount` is escrowed. The contract enforces the terms, not the
+  marketing text: a buyer's protection is the SDK recomputing `payTo` from the
+  advertised six terms and refusing on any difference, plus its
+  `maxUpfrontAmount` cap. The listing's signed `commercial` rate band bounds
+  only `ratePerSecond`, not the upfront part.
+- **Stray funds are unrecoverable**: USDC that reaches an opener any way other
+  than `deployAndSettle` / `settleAndOpen` stays there (see the hard rule).
+- **Blacklist blast radius**: one opener is the escrow buyer for every payer of
+  a listing's terms; if the token issuer blacklists it, refunds through it
+  freeze until it is un-blacklisted.
+- **ERC-6492 counterfactual wallets are refused**; deploy the wallet first. A
+  deployed ERC-1271 wallet works (USDC verifies it).
+- **Single instance**: one relayer, and the at-most-one-success ledgers are
+  in-memory per instance (see above). Do not run replicas.
+- **Listing freshness**: a successful registry read is reused for 60 s by
+  default, so a withdrawn listing can keep verifying for up to that long.
+  Discovery prefers a gated listing over a public one for the same operator and
+  origin; a listing hidden that way does not resolve (fail closed).
 
 ---
 
-## Why Metrik's STREAM does not fit `exact`
-
-Metrik's unit of payment is a **metered stream**, not a transfer:
-
-- the buyer escrows a budget into `StreamEscrowV2` at a per-second rate with an expiry;
-- a verifier probes the seller's endpoint each interval;
-- the seller earns **only for intervals that verified**, claimed incrementally
-  against Merkle checkpoints;
-- whatever was never earned is **recoverable by the buyer** via a withdrawal
-  transaction.
-
-Mapping THAT onto `exact` would require collapsing it to a single fixed payment
-made up front, directly to the seller, with no escrow and no recoverability —
-which deletes the product. So the stream is not, and will not be, expressed as an
-x402 payment.
-
-This is exactly why the delivery gate exists in the shape it does. The danger was
-never "support x402"; it was a developer seeing `x402-fetch` succeed against a
-Metrik endpoint and concluding their money was protected by verified delivery.
-The gate is honest about being weaker: it prevents a bad payment, it does not
-recover one, and it says so in the response (`metrik.detail`), in this document,
-and in the table at the top.
-
-## Why `upto` does not fit either
-
-`upto` (authorize a maximum, settle the actual usage) is closer, and for a
-single metered _request_ it would be a good fit. But its spec rules it out
-explicitly:
-
-> **Out of Scope** … **Multi-settlement / streaming**: Settling the same
-> authorization multiple times (e.g., pay-per-chunk streaming)
-
-and
-
-> ### 1. Single-Use Authorization
->
-> Each authorization MUST be settled at most once.
-
-A Metrik stream settles the _same_ authorization repeatedly, once per verified
-checkpoint, for its whole lifetime. That is precisely the case `upto` excludes.
-
-## `auth-capture` is the right shape for the STREAM — and still out of reach
-
-Of the four specified schemes, [`auth-capture`](https://github.com/x402-foundation/x402/blob/main/specs/schemes/auth-capture/scheme_auth_capture.md)
-in its `escrow` payment flow is a near-exact conceptual match for Metrik:
-
-| `auth-capture` concept                                                                                       | Metrik equivalent                                         |
-| ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- |
-| `authorize` — reserve client funds into a hold                                                               | `openStream` — escrow the budget                          |
-| `capture` — pay held funds out, **repeatable up to the held total**                                          | `claimStream` — claim verified accrual at each checkpoint |
-| `void` — release the remaining hold                                                                          | `closeStream`                                             |
-| `reclaim` — _client_ recovers its own hold after the capture deadline, never relayed through the facilitator | `reclaimStream`, gated by `escapeGraceSeconds`            |
-| `extra.captureDeadline`                                                                                      | stream expiry                                             |
-| "Metered work priced only once it completes: hold the ceiling, capture the actual cost"                      | the entire Metrik thesis                                  |
-
-The scheme's own summary could be describing Metrik. So why not implement it?
-
-**Because the EVM binding is pinned to a specific escrow contract that Metrik is
-not.** [`scheme_auth_capture_evm.md`](https://github.com/x402-foundation/x402/blob/main/specs/schemes/auth-capture/scheme_auth_capture_evm.md)
-requires a canonical `AuthCaptureEscrow` singleton — Base's Commerce Payments
-Protocol — at one of two fixed CREATE2 addresses:
-
-| Constant                      | v1.1                                         | v1.0                                         |
-| ----------------------------- | -------------------------------------------- | -------------------------------------------- |
-| `AUTH_CAPTURE_ESCROW_ADDRESS` | `0xf96815976523E00e65Be8f34cA5e64b4f41EB19c` | `0xBdEA0D1bcC5966192B070Fdf62aB4EF5b4420cff` |
-
-A conformant facilitator must read `AuthCaptureEscrow.paymentState(paymentInfoHash)`,
-and must simulate each operation and assert that **that** escrow emitted
-`PaymentAuthorized` / `PaymentCharged` with the expected payment hash before
-relaying. Metrik settles in `StreamEscrowV2` at
-`0x0f09f36Ccc05A7c9882F438721C08De314dFd46C`, which is a different contract with
-a different state model and no such functions or events.
-
-So `auth-capture` conformance is **not a wire-format exercise. It is a contract
-deployment.** Metrik would have to either settle through the canonical
-`AuthCaptureEscrow` (giving up the per-second metering and checkpoint model that
-is the product) or get a Metrik binding specified and adopted. Neither is a code
-change in this package, and the contracts are frozen.
+## History: the removed x402 v1 integration
+
+Until metrik-agent#115 this package shipped an x402 **v1** integration: a
+standard `exact` facilitator (`metrik-x402-facilitator`, exported as
+`@absol-labs/agent/x402-facilitator`) that consulted Metrik's oracle before
+settling, and an opt-in mode on the seller gateway that answered an
+uncapabilitied request with an x402 `402`. It was removed, before it ever ran in
+production, for four reasons:
+
+1. **It targeted a superseded protocol version.** It was built on `x402@1.2.0`
+   (`x402Version: 1`, `X-PAYMENT` / `X-PAYMENT-RESPONSE`, bare network names
+   such as `base-sepolia`). The protocol is at v2 (`PAYMENT-REQUIRED` /
+   `PAYMENT-SIGNATURE` / `PAYMENT-RESPONSE`, CAIP-2 network identifiers such as
+   `eip155:84532`).
+2. **It paid the seller directly.** `payTo` was the operator, so the money never
+   touched `StreamEscrowV2`: no escrow, no protocol fee, and nothing a buyer
+   could get back.
+3. **Its delivery gate gated nothing in practice.** On absent evidence it
+   defaulted to _allow_, and the live oracle's `GET /services` is built from
+   active streams, which was empty — so every payment would have passed.
+4. **Leaving it in place invited someone to enable it.** It was default-off
+   behind environment switches and had never broadcast a settlement.
+
+What changed for integrators:
+
+- The `metrik-x402-facilitator` bin, the `./x402-facilitator` subpath export,
+  the `x402:facilitator` script and every module behind them are gone.
+- The seller gateway no longer reads any `METRIK_GATEWAY_X402_*` variable, and
+  the facilitator's `METRIK_X402_*` variables have no reader. A gateway that
+  never set them behaves exactly as before: a request with no capability gets
+  `403 {"authorized":false,"reason":"missing-capability-header"}`, and a request
+  with a valid capability is proxied unchanged
+  (`test/gateway-http-baseline.test.ts` pins this over a real socket).
+- A request carrying an oracle probe capability **and** an `X-PAYMENT` header is
+  still refused with `400 ambiguous-probe-mode` (and, in the v2 mode, so is a
+  probe carrying `PAYMENT-SIGNATURE`). A probe is free verification
+  traffic and is never mixed with anything that looks like a payment.
+- The deprecated `X402*` / `x402*` aliases of the native flow's exports were
+  removed at the same time. Use the canonical names listed below.
+
+`test/x402-v1-removed.test.ts` fails if any source, test, script or example
+imports the v1 `x402` / `x402-fetch` packages again (the v2 `@x402/*` packages
+are what the opener path uses), or if `package.json` re-declares them or the
+removed bin, script or export. `scripts/check-packed-package.mjs` refuses to
+publish a tarball that still contains any removed artifact.
 
 ---
 
-## What this package actually ships
-
-**Two separate flows.** Do not confuse them.
-
-### 1. Standard x402 `exact`, with a delivery gate — the subject of the top half
+## The Metrik-native verified-stream `402` flow — NOT x402
 
-| Piece                                               | File                                                                                        |
-| --------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| `PaymentRequirements` / `402` body builder          | [`src/x402/payment-requirements.ts`](../src/x402/payment-requirements.ts)                   |
-| Oracle delivery verdict + freshness                 | [`src/x402/delivery-oracle.ts`](../src/x402/delivery-oracle.ts)                             |
-| resource URL -> signed listing                      | [`src/x402/resource-index.ts`](../src/x402/resource-index.ts)                               |
-| The gate (`/verify`, `/settle`, `/supported`)       | [`src/x402/verified-delivery-facilitator.ts`](../src/x402/verified-delivery-facilitator.ts) |
-| Chain wiring (delegates to real `x402/facilitator`) | [`src/x402/relayer.ts`](../src/x402/relayer.ts)                                             |
-| HTTP server + env contract                          | [`src/x402/facilitator-server.ts`](../src/x402/facilitator-server.ts)                       |
-| Gateway 402 mode                                    | [`src/gateway/x402-mode.ts`](../src/gateway/x402-mode.ts)                                   |
-
-Standard scheme, standard headers, standard client. `x402` is an **optional peer
-dependency**: the facilitator lives behind its own entry point
-(`@absol-labs/agent/x402-facilitator`) and the `metrik-x402-facilitator` bin, so
-a plain `npm install @absol-labs/agent` never pulls it in.
-
-### 2. The Metrik-native verified-stream `402` flow — NOT x402
-
-In [`src/x402/facilitator.ts`](../src/x402/facilitator.ts):
+In [`src/x402/facilitator.ts`](../src/x402/facilitator.ts) (the directory name is
+historical):
 
 - scheme string **`streamproof-verified-stream`** — deliberately _not_ an x402
   scheme name, and not registered with x402;
@@ -525,124 +744,78 @@ In [`src/x402/facilitator.ts`](../src/x402/facilitator.ts):
   plus an owner-signed `SpendMandate` — **not** an x402 `PaymentPayload`;
 - no `/verify`, no `/settle`, no `/supported` endpoint.
 
-This flow is real, it is tested, and it does open real escrowed streams on Base
-Sepolia. It is simply **not x402**. It is named for the HTTP status code it
-reuses, and for the x402 design it was modelled on.
-
-The class is exported as `VerifiedStreamFacilitator`. The older
-`VerifiedStreamX402Facilitator` name and the other `X402*` exports still work and
-are kept as deprecated aliases so nothing breaks, but they are misnomers and the
-non-`X402` names are canonical.
+This flow is real, it is tested, and it opens real escrowed streams on Base
+Sepolia. It does not interoperate with `x402-fetch`, `x402-axios`,
+`x402-express` or any other x402 client or facilitator.
+
+Exports: `VerifiedStreamFacilitator`, `METRIK_STREAM_SCHEME`,
+`METRIK_PAYMENT_HEADER`, `encodeStreamPayloadHeader`,
+`parseStreamPayloadHeader`, `parseStreamChallengeJson`, `streamChallengeSchema`,
+`streamOpenPayloadSchema`, `verifiedStreamRequirementsSchema`,
+`StreamPayloadError`, `SpendControlUnavailableError`,
+`SettlementTargetMismatchError`, `DeliveryProofUnavailableError`, and the types
+`StreamFacilitator`, `StreamChallenge`, `StreamOpenPayload`,
+`ConsumedHttpsResponseProofInput`, `VerifiedStreamFacilitatorOptions`,
+`VerifiedStreamRequirements`.
+
+Two runtime error names still carry the old prefix: a `StreamPayloadError` has
+`.name === "X402PayloadError"` and a `SpendControlUnavailableError` has
+`.name === "X402SpendControlUnavailableError"`. They were left unchanged so code
+that matches on `error.name` keeps working; prefer `instanceof`.
 
 ### The header name
 
-Until this change, the integration test sent the Metrik payload under the real
-x402 header name `X-PAYMENT`. That was the most actively misleading part of the
-whole surface — a real x402 header carrying a payload no x402 facilitator can
-parse. Metrik's payload now travels as **`X-METRIK-PAYMENT`**. Metrik does not
-put anything on `X-PAYMENT` and will not until it genuinely speaks x402.
+Metrik's payload travels as **`X-METRIK-PAYMENT`**. Metrik puts nothing on the
+x402 v1 `X-PAYMENT` header, and `X-METRIK-PAYMENT` also stays clear of the v2
+header names (`PAYMENT-REQUIRED`, `PAYMENT-SIGNATURE`, `PAYMENT-RESPONSE`).
 
-Note that x402 v2 renames its headers entirely — `PAYMENT-REQUIRED`,
-`PAYMENT-SIGNATURE`, `PAYMENT-RESPONSE`, with no `X-` prefix — so
-`X-METRIK-PAYMENT` stays clear of both the v1 and the v2 namespace.
+---
 
-The gateway's x402 mode uses the real `X-PAYMENT` / `X-PAYMENT-RESPONSE` headers,
-because there it really is x402. The two never appear on the same request: a
-request carrying both a Metrik capability and an `X-PAYMENT` is refused with
-`400 ambiguous-payment-mode`.
+## Why the metered stream does not fit a shipped x402 scheme
 
----
+This analysis is why "support x402" was never a wire-format exercise for the
+stream itself. Package facts were gathered on **2026-09-18** from
+`x402-foundation/x402@main` and from `x402@1.2.0` as published on npm; the test
+that re-checked them against the real package was removed with the dependency
+in #115, so re-verify before relying on them.
 
-## What would have to be true for the STREAM to be an x402 payment
-
-In rough order of cost:
-
-1. **`x402@>=?` ships a scheme with repeatable settlement.** Today `schemes ===
-["exact"]`. Nothing Metrik-shaped can be expressed until `auth-capture` (or an
-   equivalent) is in the published package, not just the spec.
-2. **A Metrik / generic-escrow network binding for `auth-capture`,** or a
-   redeployment of Metrik settlement behind the canonical `AuthCaptureEscrow`.
-   This is a contracts decision, not a package decision — and today's
-   `AuthCaptureEscrow` binding has no room for per-second metering or
-   oracle-attested checkpoints.
-3. **x402 v2 adoption in the client libraries,** so the extensible `scheme` string
-   and CAIP-2 networks in `x402-specification-v2.md` are actually usable.
-
-The cheaper intermediate step described in an earlier revision of this document
-— "serve an ordinary `exact` x402 payment for one-shot endpoints alongside the
-Metrik stream flow for metered ones" — **is the step that has now been taken**,
-with one addition that changes its character: the `exact` path is not an
-unverified payment. It is gated on Metrik's own delivery verdict. It is still
-weaker than the stream, for the reason stated at the top: it prevents a payment
-rather than recovering one.
+| Thing                               | Reality at the date above                                         |
+| ----------------------------------- | ----------------------------------------------------------------- |
+| Spec repository                     | [`x402-foundation/x402`](https://github.com/x402-foundation/x402) |
+| Schemes implemented by `x402@1.2.0` | **`exact` only**                                                  |
+| Schemes that exist _in the spec_    | `exact`, `upto`, `batch-settlement`, `auth-capture`               |
+| Protocol versions in `x402@1.2.0`   | `x402Version: 1` only; v2 was specified, not yet in that package  |
 
----
+### `exact`
 
-## Evidence
-
-Everything here is checked against the **real** published `x402` package and the
-**real** published `x402-fetch` client — devDependencies, not fixtures.
-
-### The stream is not x402 — [`test/x402-conformance.test.ts`](../test/x402-conformance.test.ts)
-
-- `schemes` is exactly `["exact"]`;
-- `x402Versions` is exactly `[1]`;
-- the real `PaymentRequirementsSchema` **rejects** Metrik's stream scheme string;
-- it also rejects `auth-capture` and `upto`;
-- the real `PaymentPayloadSchema` rejects Metrik's stream payload shape;
-- the stream flow publishes nothing on the `X-PAYMENT` header.
-
-That test is a tripwire. **When x402 ships a scheme that fits the Metrik stream,
-those assertions start failing** — the signal to revisit this document.
-
-### What Metrik emits IS x402 — [`test/x402-facilitator-conformance.test.ts`](../test/x402-facilitator-conformance.test.ts)
-
-Everything Metrik puts on the wire is parsed with the real schemas: the
-`PaymentRequirements`, the `402` body the way `x402-fetch` parses it, and both
-the passing and the refusing `VerifyResponse`. It also pins two places where the
-shipped library contradicts itself, so they are recorded decisions and not
-accidents:
-
-- `x402ResponseSchema` types `error` as the closed `ErrorReasons` enum, which no
-  real x402 server obeys (`x402-express` puts human text there, `x402-fetch`
-  never reads the field). Metrik follows the shipped behaviour.
-- `SettleResponseSchema` requires `transaction` to match an address-shaped regex,
-  so a FAILED settlement cannot be expressed conformantly. `x402`'s own `settle`
-  returns `transaction: ""` on every error path, which its own schema rejects.
-  Metrik emits the same `""` rather than inventing a placeholder that looks like
-  a real transaction hash.
-
-### The gate — [`test/x402-delivery-gate.test.ts`](../test/x402-delivery-gate.test.ts)
-
-24 assertions over the real oracle projection and the real decision tree: refuse
-on a fresh failure; allow on a fresh pass; no gate for an untracked resource;
-payee-mismatch refusal; a lying `extra.metrikServiceRef` changing nothing;
-freshness symmetry at the 90 s boundary; every no-evidence case under both
-policies; and `/settle` re-running the gate, refusing to broadcast for a failing
-service, and throwing rather than faking success with no relayer.
-
-### The whole loop — [`test/x402-gateway.test.ts`](../test/x402-gateway.test.ts)
-
-`x402-fetch@1.2.0` — the published client — reads Metrik's `402`, parses
-`accepts` with the real `PaymentRequirementsSchema`, signs an EIP-3009
-authorization, retries with `X-PAYMENT`, gets `200` plus a
-`X-PAYMENT-RESPONSE` it decodes with the library's own
-`decodeXPaymentResponse`. Nothing in that file hand-rolls a payment header: if
-Metrik's `402` were not conformant, the client would throw instead of paying.
-The same test then flips the oracle to `failing` and asserts the identical, valid
-payment is refused with `402`, nothing is settled, and the seller's upstream is
-never called.
-
-**What is real in that test**: the gateway, its HTTP server, the facilitator HTTP
-wire over a real socket, the oracle projection and freshness arithmetic, and the
-EIP-712 signature check. **What is a fixture**: the payer's on-chain balance, and
-the broadcast. Nothing is broadcast, anywhere, ever.
-
-Spec and package facts were gathered on **2026-09-18** from
-`x402-foundation/x402@main` and from `x402@1.2.0` as published on npm.
-
-One incidental packaging note, true at `x402@1.2.0`: the package's `exports` map
-has no `"."` entry, so `import { … } from "x402"` fails with
-`ERR_PACKAGE_PATH_NOT_EXPORTED` under Node ESM. The subpaths (`x402/types`,
-`x402/facilitator`, `x402/verify`, `x402/schemes`, `x402/client`) are what
-resolve.
+`exact` on EVM is an [EIP-3009](https://eips.ethereum.org/EIPS/eip-3009)
+`transferWithAuthorization`: one fixed amount, one transfer, straight to
+`payTo`. No hold, no conditional release, no partial capture, no reclaim.
+
+Metrik's unit of payment is a **metered stream**: the buyer escrows a budget
+into `StreamEscrowV2` at a per-second rate with an expiry, a verifier probes the
+seller each interval, the seller earns only for intervals that verified
+(claimed against Merkle checkpoints), and whatever was never earned is
+recoverable by the buyer via a withdrawal transaction. Collapsing that into one
+up-front transfer to the seller deletes the product — which is exactly what the
+removed v1 integration did, and why it went. The opener path at the top of this
+document keeps the `exact` payment but points its `payTo` at an opener that
+opens the stream, instead of at the seller.
+
+### `upto`
+
+`upto` (authorize a maximum, settle actual usage) fits a single metered
+_request_, but its spec explicitly puts "multi-settlement / streaming" out of
+scope and requires each authorization to be settled at most once. A Metrik
+stream settles the same authorization repeatedly, once per verified checkpoint.
+
+### `auth-capture`
+
+`auth-capture` in its `escrow` flow is the closest conceptual match —
+`authorize`/`capture`/`void`/`reclaim` map onto `openStream`/`claim`/`close`/
+`reclaim` — but its EVM binding is pinned to the canonical `AuthCaptureEscrow`
+contract (Base's Commerce Payments Protocol), which a conformant facilitator
+must read and whose events it must observe. Metrik settles in `StreamEscrowV2`
+(`0x0f09f36Ccc05A7c9882F438721C08De314dFd46C`), a different contract with a
+different state model, so conformance there would be a contract deployment, not
+a code change in this package.