@absol-labs/agent 0.9.1 → 0.11.0

package/docs/x402.md

@@ -0,0 +1,648 @@
+# 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.
+>
+> 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:
+
+```ts
+VerifyResponse = { isValid: boolean, invalidReason?: ErrorReason, payer?: string }
+```
+
+`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`:
+
+```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..." }
+    }
+  ]
+}
+```
+
+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.
+
+---
+
+## 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:
+
+```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 ..."
+  }
+}
+```
+
+`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.
+
+---
+
+## 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
+```
+
+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
+
+`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.
+
+---
+
+## 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
+
+`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.
+
+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.**
+
+---
+
+## 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.
+
+---
+
+## 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
+
+| 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):
+
+- scheme string **`streamproof-verified-stream`** — deliberately _not_ an x402
+  scheme name, and not registered with x402;
+- a challenge body of `{scheme, requirements}` where `requirements` is
+  Metrik-specific (`operator`, `serviceRef`, `ratePerSecondUsdc`,
+  `maxDurationSeconds`, `maxBudgetUsdc`, `escrow`, `chainId`) — **not** x402
+  `PaymentRequirements`;
+- a payload header of `` `${scheme} ${base64url(JSON)}` `` carrying the challenge
+  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.
+
+### 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.
+
+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`.
+
+---
+
+## 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.
+
+---
+
+## 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.