@devlab.group/agent-commerce 1.4.1 → 1.6.0

package/README.md

@@ -1,7 +1,7 @@
 <h1 align="center">Agent Commerce Gateway</h1>
 
 <p align="center">
-  <strong>One backend. Agent-commerce protocols on the front. No proprietary middleman.</strong>
+  <strong>One backend. Multiple agent-commerce protocols. Self-hosted and non-custodial.</strong>
 </p>
 
 <p align="center">
@@ -10,6 +10,7 @@
   <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-strict-3178c6">
   <img alt="MCP" src="https://img.shields.io/badge/MCP-supported-6b4fbb">
   <img alt="x402" src="https://img.shields.io/badge/x402-supported-0052ff">
+  <img alt="MPP" src="https://img.shields.io/badge/MPP-experimental-f0a30a">
   <img alt="A2A" src="https://img.shields.io/badge/A2A-experimental-f0a30a">
   <img alt="ACP" src="https://img.shields.io/badge/ACP-experimental-f0a30a">
   <img alt="AP2" src="https://img.shields.io/badge/AP2-experimental-f0a30a">
@@ -17,48 +18,48 @@
 
 ## What it is, in ten seconds
 
-You already have an HTTP API. AI agents want to **discover** it, **call** it and
-**pay** for it - over protocols you did not write and do not want to maintain.
+You already have an HTTP API. Agent Commerce Gateway lets AI agents discover,
+call and pay for it without adding those protocols to your backend.
 
-Agent Commerce Gateway sits in front of your existing API, in **your**
-infrastructure, and does that for you. You describe an endpoint in a YAML file -
-or generate that description from an OpenAPI document you already have - and
-agents get an MCP tool and an x402 paywall. Switch on the experimental adapters
-and the same resource is also an A2A skill, or an ACP checkout session. Switch
-on AP2 and a paid resource can also demand a signed mandate: proof the human
-behind the agent approved that exact purchase. The money goes straight to your
-wallet - the gateway never holds it, and never holds your keys.
+Run the gateway in your infrastructure and describe each endpoint in YAML, or
+generate draft resource definitions from OpenAPI. Resources can be exposed over
+HTTP, MCP or experimental A2A; dedicated resources can implement experimental
+ACP checkout operations. Paid resources use x402 or experimental MPP and can
+also require an AP2 mandate proving that the buyer approved the purchase. Funds
+go directly to the merchant wallet, and the gateway needs neither the buyer's
+nor the merchant's private key.
 
 ```text
 Your existing API → Agent Commerce Gateway → AI Agent
-      MCP · A2A · ACP · x402 · AP2 · receipts · doctor
+    MCP · A2A · ACP · x402 · MPP · AP2 · receipts · doctor
 ```
 
 ## Demo
 
 ```text
-[agent] Discovering resources over MCP...
-[agent] Found: market_report - Premium Market Report (0.01 USDC)
-[agent] Requesting resource...
-
-[gateway] Payment required: 0.01 USDC → 0x7099…79C8
-[buyer] Signing x402 authorisation...
-[gateway] Payment verified
-[gateway] Payment settled tx 0x4f2c…9ab1
-[gateway] Calling merchant backend...
-[gateway] Resource delivered
-
-[receipt] payment: settled
-[receipt] amount: 0.01 USDC
-[receipt] merchant: 0x7099…79C8
-[receipt] buyer balance 100.00 → 99.99 mUSDC
-[receipt] merchant balance 0.00 → 0.01 mUSDC
+[agent] Agent Commerce Gateway: deterministic buyer demo
+[buyer] balance before  100 MockUSDC
+[agent] merchant balance before 0 MockUSDC
+[gateway] connected to http://localhost:8080/mcp
+[agent] discovered 2 tool(s): weather_basic, market_report
+[agent] paid tool: "market_report", free tool: "weather_basic"
+[gateway] 402 payment required: 0.01 USDC to 0x7099…79C8
+[buyer] challenge checked before signing: pays 10000 units of 0x5fbd…0aa3 to 0x7099…79C8
+[buyer] signed x402 payment proof (LOCAL DEVELOPMENT ONLY - DO NOT FUND)
+[gateway] delivered "market_report"
+[receipt] id=receipt_484b…1eba requestId=mcp_4292…c930 status=settled settlementTx=0x0b19…1c7f
+[buyer] balance after   99.99 MockUSDC  (Δ -0.01)
+[agent] merchant balance after  0.01 MockUSDC  (Δ 0.01)
+[agent] on-chain balance changes match the expected payment amount
+[gateway] delivered free tool "weather_basic": {"city":"Paris","temperatureC":-4,…}
+[agent] demo complete: free and paid delivery both verified
 ```
 
-The dashboard at <http://localhost:5173> shows the same request as it happens.
-It polls the authenticated events route rather than streaming, because a browser
-cannot send the admin token over `EventSource`; see
-[why the stream is polled](SECURITY.md#the-live-event-stream-is-polled-not-streamed).
+This excerpt of `npm run demo:agent` omits the address lines and shortens long
+values. Balances, IDs and hashes differ from run to run.
+
+The dashboard at <http://localhost:5173> polls the gateway's events route and
+shows the same request within a few seconds.
 
 ## Install
 
@@ -68,21 +69,19 @@ npm install -g @devlab.group/agent-commerce # or install the `agent-commerce` bi
 agent-commerce doctor
 ```
 
-Requires **Node >= 22**. One package ships two things: the `agent-commerce`
-CLI (`init`, `validate`, `doctor`, `demo`) and a library for embedding the
-gateway in your own process. A default install is ~65 MB and pulls no
-blockchain or wallet dependencies at all - ~17 MB of that is the OpenAPI
-parser behind `import openapi`, which is a normal dependency because
-onboarding an existing API is the CLI's main job.
+Requires **Node >= 22**. The package includes the `agent-commerce` CLI
+(`init`, `validate`, `doctor`, `demo`, `import openapi`, `version`) and a library
+for embedding the gateway.
+The default install excludes optional protocol, payment and authorization
+peers. The OpenAPI parser is a regular dependency because import is part of the
+CLI.
 
 ```ts
 import { createGateway, loadConfig, receipts } from '@devlab.group/agent-commerce';
 
 const config = await loadConfig({ path: 'config.yaml' });
 const store = receipts({ path: './receipts.sqlite' });
-// Every ReceiptStore must be initialised before anything else touches it -
-// for the SQLite one this is where a schema written by a newer version is
-// caught, at boot rather than at the first query
+// Initialize before use so an incompatible SQLite schema fails at startup
 await store.init();
 
 const gateway = await createGateway({
@@ -94,21 +93,23 @@ const gateway = await createGateway({
 const { url } = await gateway.listen();
 ```
 
-### Optional peers - install only the rails you use
+### Optional peers
 
-The MCP adapter, the x402 provider and AP2 verification live on their own
-subpaths, because each needs a dependency the rest of the package does not -
-the x402 rail brings the whole EVM signing and RPC stack, which a gateway
-serving a free HTTP resource has no business installing.
+Components with extra dependencies use separate subpaths, so a gateway serving
+free HTTP resources does not install MCP, EVM, JOSE or SD-JWT packages.
 
 | You want                                | Install                            | Import                                     |
 | --------------------------------------- | ---------------------------------- | ------------------------------------------ |
-| gateway, config, receipts, CLI          | `@devlab.group/agent-commerce`     | `from '@devlab.group/agent-commerce'`      |
+| gateway, config, receipts, A2A/ACP, CLI | `@devlab.group/agent-commerce`     | `from '@devlab.group/agent-commerce'`      |
 | expose resources as MCP tools           | `+ @modelcontextprotocol/sdk`      | `from '@devlab.group/agent-commerce/mcp'`  |
 | accept x402 payments                    | `+ @x402/core @x402/evm viem`      | `from '@devlab.group/agent-commerce/x402'` |
+| accept MPP payments                     | `+ mppx viem @x402/core @x402/evm` | `from '@devlab.group/agent-commerce/mpp'`  |
 | verify AP2 mandates, sign checkout JWTs | `+ jose @sd-jwt/core canonicalize` | `from '@devlab.group/agent-commerce/ap2'`  |
 | authenticate to a CDP facilitator       | `+ @coinbase/x402`                 | (no import - loaded on demand)             |
 
+MPP settles through an x402 facilitator, so its entry also needs the x402
+peers.
+
 ```bash
 npm install @devlab.group/agent-commerce @modelcontextprotocol/sdk @x402/core @x402/evm viem
 ```
@@ -119,23 +120,17 @@ import { x402 } from '@devlab.group/agent-commerce/x402';
 import { ap2 } from '@devlab.group/agent-commerce/ap2';
 ```
 
-The AP2 three are small - about 1.3 MB installed between them, against roughly
-63 MB for the x402 stack - but they stay optional on the same principle: a
-deployment that gates nothing on a mandate should not carry a JOSE stack and an
-SD-JWT parser to serve a resource.
+AP2 peers remain optional because a deployment without mandate-gated resources
+does not need JOSE or SD-JWT support.
 
 Peers are pinned exactly: x402's schemas and EIP-712 domains cross this
 boundary, so a version skew is a correctness problem rather than a convenience
-one. Import a subpath without its
-peer installed and Node fails at load naming the missing package - deliberately,
-rather than starting a gateway that silently serves nothing.
+one. Importing a subpath without its peer fails at load time and names the
+missing package.
 
-`@coinbase/x402` is the odd one out: it has no import of its own and is loaded
-dynamically, only when `facilitator.auth.type: cdp` is configured. It is worth
-avoiding if you can - it brings `@coinbase/cdp-sdk` and `axios`, which carry
-high-severity advisories, while the package itself and the other three peers
-audit clean. `auth.type: bearer` covers any facilitator with a static token and
-installs nothing.
+`@coinbase/x402` has no subpath import. It is loaded dynamically only for
+`facilitator.auth.type: cdp` and brings the larger CDP dependency tree. A
+facilitator with a static token can use `auth.type: bearer` without it.
 
 ## Quickstart
 
@@ -155,15 +150,13 @@ npm run agent-commerce -- doctor --config config-demo.yaml # verify the whole st
 npm run demo:agent # watch an agent buy something
 ```
 
-<sub><b>Linux only</b>, and only if your user is not UID/GID 1000 (check with
-<code>id -u && id -g</code>): export <code>DOCKER_UID=$(id -u) DOCKER_GID=$(id -g)</code>
-before <code>docker compose up</code>. The chain-deploy step runs as that user so the
-deployment manifest it writes stays host-writable rather than root-owned. Docker
-Desktop on macOS and Windows translates permissions through its VM and does not
-need this.</sub>
+<sub><b>Linux:</b> if your UID/GID is not 1000, export
+<code>DOCKER_UID=$(id -u) DOCKER_GID=$(id -g)</code> before
+<code>docker compose up</code>. This keeps the generated deployment manifest
+host-writable. Docker Desktop does not need this.</sub>
 
-That is the whole thing. The stack is a private Anvil chain, a mock USDC token,
-a demo merchant API, the gateway and a dashboard - all local and disposable.
+The disposable local stack includes Anvil, MockUSDC, a demo merchant API, the
+gateway and a dashboard.
 
 To stop and wipe state: `docker compose down -v`.
 
@@ -174,7 +167,7 @@ To stop and wipe state: `docker compose down -v`.
 │                                   AI Agent                                   │
 └───────────────────────────────────────┬──────────────────────────────────────┘
                                         │  MCP · A2A · ACP · HTTP
-                                        │  PAYMENT-SIGNATURE
+                                        │  payment proof
                                         │  Agent-Authorization
 ┌───────────────────────────────────────▼──────────────────────────────────────┐
 │                        Agent Commerce Gateway (yours)                        │
@@ -184,7 +177,7 @@ To stop and wipe state: `docker compose down -v`.
 │             ┌────────────────────┬──────────────┴──┬────────────────┐        │
 │             ▼                    ▼                 ▼                ▼        │
 │   AuthorizationProvider   PaymentProvider   BackendExecutor   ReceiptStore   │
-│           (ap2)               (x402)        (bounded HTTP)      (SQLite)     │
+│           (ap2)             (x402, mpp)     (bounded HTTP)      (SQLite)     │
 └───────────────────────────────────────┬──────────────────────────────────────┘
                                         │
                              ┌──────────▼─────────┐
@@ -192,11 +185,8 @@ To stop and wipe state: `docker compose down -v`.
                              └────────────────────┘
 ```
 
-Every protocol adapter converges on **one execution pipeline**. That is what
-makes payment enforcement a property of the system rather than something each
-adapter has to remember. Money never passes through the box: the buyer pays the
-merchant directly on chain, and the gateway holds neither the funds nor a key.
-Full detail in [docs/architecture.md](docs/architecture.md).
+Every protocol adapter uses one execution pipeline, so payment enforcement does
+not depend on the adapter. See [Architecture](docs/architecture.md).
 
 ## Configure a resource
 
@@ -217,7 +207,7 @@ resources:
     payments: [x402]
 ```
 
-That is the integration. No SDK in your backend, no rewrite.
+The gateway calls your existing backend, which needs no SDK or changes.
 
 ```bash
 npm run agent-commerce -- init # generate a config interactively
@@ -231,57 +221,58 @@ Already have an OpenAPI description? Generate the resources from it
 agent-commerce import openapi ./openapi.yaml
 ```
 
-It writes a reviewable `resources:` fragment - path, query and JSON body
-mapped, schemas converted to what the gateway actually enforces - and
-deliberately leaves `pricing` and `expose` out, because an OpenAPI document has
-no opinion on what an operation costs or who may see it. Credentials are never
-imported. See [OpenAPI import](docs/openapi-import.md) for the exact supported subset.
+It writes a reviewable `resources:` fragment with path, query and JSON body
+bindings and supported schemas. The source document never decides price or
+exposure: `pricing` appears only with `--free` and `expose` only with
+`--expose`, and credentials are never imported. See
+[OpenAPI import](docs/openapi-import.md) for the supported subset.
 
 See [docs/configuration.md](docs/configuration.md).
 
 ## Protocol support
 
-| Protocol  | Status       | Pinned revision                                          |
-| --------- | ------------ | -------------------------------------------------------- |
-| **MCP**   | Supported    | `@modelcontextprotocol/sdk@1.30.0`                       |
-| **x402**  | Supported    | x402 v2 (`@x402/core`, `@x402/evm`), scheme `exact`, EVM |
-| **HTTP**  | Supported    | native routes                                            |
-| **A2A**   | Experimental | A2A v1.0.0, binding `JSONRPC`, method `SendMessage`      |
-| **ACP**   | Experimental | ACP `2026-04-17`, REST checkout + discovery              |
-| **AP2**   | Experimental | AP2 `v0.2.0`, Direct Checkout Mandate verification       |
-| UCP · MPP | Planned      | -                                                        |
-
-[AP2](docs/ap2.md) is in that table because people look there, but it is an **authorization**
-method rather than a transport: it gates settlement on a resource that still
-takes a real payment, and it is the verifying half only - the gateway holds no
-signing key and issues no Checkout Receipt.
-
-"Planned" means **no code ships for it**. "Experimental" means the code ships,
-is tested against the protocol's own official artifacts, and serves a narrow
-named subset: [A2A](docs/protocols.md#a2a) and [ACP](docs/protocols.md#acp) are
-both off by default and documented in full there, as are
-[MCP](docs/protocols.md#mcp) and [x402](docs/protocols.md#x402). ACP serves the
-five stable checkout operations and advertises `services: ["checkout"]` and
-nothing more; its `payment_data` stays with the merchant's own checkout and is
-never turned into an x402 payment.
-
-Each adapter reports its own `supportedSpec`, `capabilities` and `unsupported`
-list at runtime through `GET /.well-known/agent-commerce` and
-`agent-commerce doctor`, so the claim is checkable rather than marketing.
+| Protocol | Status       | Pinned revision                                                           |
+| -------- | ------------ | ------------------------------------------------------------------------- |
+| **HTTP** | Supported    | native routes                                                             |
+| **MCP**  | Supported    | `@modelcontextprotocol/sdk@1.30.0`                                        |
+| **x402** | Supported    | x402 v2 (`@x402/core`, `@x402/evm`), scheme `exact`, EVM                  |
+| **MPP**  | Experimental | `mppx@0.10.1`, `charge` + `evm` + EIP-3009, USDC on Base Sepolia and Base |
+| **A2A**  | Experimental | A2A v1.0.0, binding `JSONRPC`, method `SendMessage`                       |
+| **ACP**  | Experimental | ACP `2026-04-17`, REST checkout + discovery                               |
+| **AP2**  | Experimental | AP2 `v0.2.0`, Direct Checkout Mandate verification                        |
+| UCP      | Planned      | no implementation                                                         |
+
+[AP2](docs/ap2.md) is an authorization method, not a transport. It verifies a
+mandate before a paid resource settles; the gateway does not issue the mandate
+or its Checkout Receipt.
+
+The experimental entries above ship off by default with documented subsets:
+[A2A](docs/protocols.md#a2a), [ACP](docs/protocols.md#acp),
+[AP2](docs/ap2.md#not-implemented) and [MPP](docs/protocols.md#mpp). Supported
+[MCP](docs/protocols.md#mcp) and [x402](docs/protocols.md#x402) are also scoped.
+ACP exposes only its five checkout operations; merchant `payment_data` is never
+converted into a gateway payment proof.
+
+`GET /.well-known/agent-commerce` reports `supportedSpec`, `capabilities` and
+`unsupported` for registered adapters and providers. `agent-commerce doctor`
+prints the `unsupported` lists for A2A, ACP and AP2 when they are enabled.
 
 ## Payment model
 
-- **Non-custodial.** The gateway never holds funds, and never asks for a
-  merchant or buyer private key. `payTo` is your address.
+- **Non-custodial.** Buyer payments go directly to the merchant address in
+  `payTo` (`recipient` for MPP). The gateway does not require buyer or merchant
+  private keys. Local facilitator mode does hold a separate gas-paying signer.
 - **Fail closed.** Missing, malformed, expired, replayed, wrong-amount,
-  wrong-recipient, wrong-network and wrong-asset payments all fail - each with a
-  test.
+  wrong-recipient, wrong-network and wrong-asset payments are rejected.
 - **Replay-safe twice over.** EIP-3009 stops a double spend on-chain; the
-  gateway additionally reserves a `replayKey` derived from the authorisation
+  gateway additionally reserves a `replayKey` derived from the authorization
   before it settles anything.
-- **Real settlement in CI.** The end-to-end test asserts the buyer's balance
+- **On-chain settlement in CI.** The end-to-end test asserts the buyer's balance
   falls and the merchant's rises by exactly the price, with a real transaction
   hash in the receipt. A log line saying "payment successful" would not count.
+- **One selected rail per resource.** A resource can name several rails, such as
+  `payments: [x402, mpp]`; the first enabled one serves it, and nothing selects
+  or falls back between rails per request.
 - **Authorization is separate from payment.** A resource can also require an
   AP2 mandate, verified before settlement and spendable exactly once. It never
   moves money and never unlocks a resource on its own - the payment still has
@@ -289,50 +280,48 @@ list at runtime through `GET /.well-known/agent-commerce` and
 
 ## Public networks
 
-Same gateway, same pipeline - a different `network` and a facilitator that is
-not this process. No code changes, and no "live mode" to switch on.
+Public networks use the same execution pipeline with a remote facilitator.
+Choose the network in config; Base mainnet also requires `allowMainnet: true`.
 
 ### It has actually settled
 
-Not a roadmap entry. Both of these moved 0.01 USDC from a buyer to a merchant
-through a remote facilitator:
+These transactions each moved 0.01 USDC from a buyer to a merchant through a
+remote facilitator:
 
-| Network      | Transaction                                                                                                           |
-| ------------ | --------------------------------------------------------------------------------------------------------------------- |
-| Base Sepolia | [`0xea41b234c4…`](https://sepolia.basescan.org/tx/0xea41b234c4645a4d335589ec9753646aa7cccd1b97e9e15823b88bff7b54a247) |
-| Base         | [`0x57ec81c2a3…`](https://basescan.org/tx/0x57ec81c2a360d14d59a43cf4e24be09a6bd75cbe6185016372895bda73e42763)         |
+| Rail | Network      | Transaction                                                                                                           |
+| ---- | ------------ | --------------------------------------------------------------------------------------------------------------------- |
+| x402 | Base Sepolia | [`0xea41b234c4…`](https://sepolia.basescan.org/tx/0xea41b234c4645a4d335589ec9753646aa7cccd1b97e9e15823b88bff7b54a247) |
+| x402 | Base         | [`0x57ec81c2a3…`](https://basescan.org/tx/0x57ec81c2a360d14d59a43cf4e24be09a6bd75cbe6185016372895bda73e42763)         |
+| MPP  | Base Sepolia | [`0x5d9fcd111b…`](https://sepolia.basescan.org/tx/0x5d9fcd111b615bb8fc9e56d55096f119fc81c3c72c334f813cfaecee402d0ac3) |
+| MPP  | Base         | [`0xf4255bd7ec…`](https://basescan.org/tx/0xf4255bd7ec46ed06505dedfb5f9537924bd2633816e7952ec6f2b468395b1087)         |
 
-In both, the gateway held no key, signed nothing and paid no gas - the buyer
-signed an EIP-3009 authorisation offline holding no ETH, and the facilitator
-broadcast it. Each run reads the buyer and merchant balances and the
-transaction receipt back off the chain afterwards; the gateway's own report of
-success is not the proof.
+The buyer signed each EIP-3009 authorization without ETH; the remote facilitator
+paid gas and broadcast it. The gateway path received no buyer or merchant key.
+The public-network smoke suites verify balance changes and fetch the transaction
+receipt from the chain instead of trusting the gateway's response.
 
-Reproduce with `npm run test:testnet` / `npm run test:mainnet` - both spend
-real funds, skip themselves without credentials, and never run in CI.
+Reproduce with `npm run test:testnet`, which spends test USDC, or
+`npm run test:mainnet`, which spends real USDC. Both run only by hand; see
+[Base mainnet](#base-mainnet).
 
 ### The facilitator model
 
-A **facilitator** verifies the buyer's authorisation and broadcasts the
-transfer. It is the only component that needs gas, and it is never this
-gateway on a public network.
+A **facilitator** verifies the buyer's authorization and broadcasts the
+transfer. It is the only component that needs gas.
 
-| `facilitator.mode` | Who signs                           | Where it is allowed      |
-| ------------------ | ----------------------------------- | ------------------------ |
-| `local`            | this process, with an Anvil dev key | the local dev chain only |
-| `remote`           | an HTTP facilitator you point at    | anywhere                 |
+| `facilitator.mode` | Who signs                              | Where it is allowed                                                |
+| ------------------ | -------------------------------------- | ------------------------------------------------------------------ |
+| `local`            | this process, with a key you configure | a local Anvil chain; refused on mainnet, fails readiness elsewhere |
+| `remote`           | an HTTP facilitator you point at       | anywhere                                                           |
 
-With `remote`, the gateway holds **no signing key at all**. The buyer signs an
-EIP-3009 authorisation offline - no ETH required - and the facilitator pays the
-gas. A facilitator cannot redirect your money: the authorisation names its
-recipient, amount and chain, so it can broadcast exactly that transfer or
-nothing. What it can do is see every authorisation you handle, and stop
-answering.
+With `remote`, the gateway holds no facilitator signing key. The buyer signs an
+EIP-3009 authorization without ETH, and the facilitator pays gas. Because the
+authorization fixes the recipient, amount and chain, the facilitator cannot
+redirect the transfer. It can see authorizations and refuse service.
 
-Three auth types: `none`, `bearer` (a static token, installs nothing) and `cdp`
-(Coinbase Developer Platform, which signs a fresh JWT per request). Anything
-else is refused at config load rather than sent nothing. You can also run your
-own - `remote` does not care who operates the endpoint.
+Remote facilitator auth supports `none`, `bearer` and `cdp`. `cdp` loads the
+optional peer `@coinbase/x402`, which signs a fresh JWT per request; bearer auth
+needs no extra peer. Other types are rejected at config load.
 
 ### Base Sepolia
 
@@ -366,55 +355,51 @@ together, and reported by `doctor`, `health()` and `/.well-known`.
 
 ### Base mainnet
 
-Real funds, so nothing is defaulted. Every one of these is checked at config
-load, and the gateway will not start without them:
+Mainnet moves real funds. Config validation requires:
 
-| Required                                        |                                                                                                                |
-| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| `allowMainnet: true`                            | mainnet is never a default                                                                                     |
-| `facilitator.mode: remote`                      | `local` needs a funded gas key inside this process                                                             |
-| an HTTPS `facilitator.url`                      |                                                                                                                |
-| `allowUnauthenticatedFacilitator: true`         | only if that facilitator takes no credential                                                                   |
-| a non-development `payTo`                       |                                                                                                                |
-| `asset` = USDC on Base, `assetName: "USD Coin"` | **not** `"USDC"` - that deployment predates the rename, and the buyer signs the name into their EIP-712 domain |
+| Required                                                       |                                                                |
+| -------------------------------------------------------------- | -------------------------------------------------------------- |
+| `allowMainnet: true`                                           | mainnet is never a default                                     |
+| `facilitator.mode: remote`                                     | `local` needs a funded gas key inside this process             |
+| an HTTPS `facilitator.url`                                     |                                                                |
+| `allowUnauthenticatedFacilitator: true`                        | required when `facilitator.auth.type` is `none`                |
+| a non-development destination (`payTo` or `recipient`)         |                                                                |
+| Base USDC with `assetName: "USD Coin"` and `assetVersion: "2"` | the buyer signs this EIP-712 domain; `"USDC"` is wrong on Base |
 
 Full config in [`examples/base-mainnet/`](examples/base-mainnet/), and
 [`examples/base-mainnet-payai/`](examples/base-mainnet-payai/) for an
-unauthenticated facilitator. `npm run test:mainnet` proves it end to end and
-spends real USDC on every run.
+unauthenticated facilitator. The mainnet smoke suites cover x402 and MPP and
+spend real USDC when their opt-ins and credentials are present.
 
 `agent-commerce validate` reports any of the above before anything starts, and
 `doctor` prints `LIVE MAINNET MODE - REAL FUNDS`.
 
-> Neither public-network suite runs in CI - there is no workflow and there must
-> not be one. A workflow means a funded key in repository secrets, spendable by
-> anyone with write access. Both suites run from the machine that holds the
-> wallet, and skip themselves without credentials.
+> The public-network suites never run in CI, because a workflow would need a
+> funded buyer key in repository secrets. Run them from the machine that holds
+> the wallet. A test whose required settings are missing skips itself.
 
 ## Diagnostics
 
 ```console
 $ npm run agent-commerce -- doctor --config config-demo.yaml
 
-PASS  Config               valid - 2 resource(s), merchant "Demo Data Store" (using local chain manifest .deploy/local.json for X402_ASSET, X402_ASSET_NAME, X402_ASSET_VERSION, X402_ASSET_DECIMALS, MERCHANT_WALLET, X402_FACILITATOR_PRIVATE_KEY)
+PASS  Config               valid: 2 resource(s), merchant "Demo Data Store" (using local chain manifest .deploy/local.json for X402_ASSET, X402_ASSET_NAME, X402_ASSET_VERSION, X402_ASSET_DECIMALS, MERCHANT_WALLET, X402_FACILITATOR_PRIVATE_KEY)
 PASS  Gateway              healthy and ready at http://127.0.0.1:8080
 PASS  Backend              2/2 backend host(s) reachable
 PASS  Protocols            http=on mcp=on (/mcp) a2a=off acp=off
 INFO  A2A                  disabled
 INFO  ACP                  disabled
 INFO  AP2                  disabled
-PASS  Payments             x402 v2 (scheme=exact) enabled - LOCAL dev chain (eip155:84532, chain id shared with Base Sepolia), destination=0x7099…79C8, facilitator=local
-INFO  Payments (MPP)       planned - not implemented in this release
-PASS  Storage              sqlite schema v1 writable; receipts=2
+PASS  Payments             x402 v2 (scheme=exact) enabled - LOCAL dev chain (eip155:84532, chain id shared with Base Sepolia), destination=0x7099…79C8, facilitator=local (in-process)
+INFO  Payments (MPP)       MPP not configured
+PASS  Storage              sqlite schema v2 writable; receipts=2
 PASS  Protocol versions    reported by gateway /.well-known/agent-commerce
 
 Score: 7/7 checks passed
 ```
 
-That is real output, not an illustration. `doctor` also cross-checks the
-gateway's *live* settlement configuration against what your local config
-resolves to, and fails if they disagree - a diagnostic that passes while the
-system is misconfigured is worse than none.
+`doctor` cross-checks the gateway's live settlement configuration against the
+resolved local config and fails if they differ.
 
 Exits non-zero if anything fails. `--json` for machines.
 
@@ -426,8 +411,8 @@ reachable by anyone else, know the split:
 - **Agent routes** (`/api/resources/:id/invoke`, `/mcp`, the A2A mount) are
   unauthenticated by design - paid resources are protected by payment, not by a
   password. ACP is the exception: its checkout routes require a bearer token.
-- **Operator routes** (`/api/receipts`, `/api/events`, `/api/events/stream`) are
-  the merchant's commerce ledger: payer addresses, amounts, settlement hashes.
+- **Operator routes** (`/api/receipts`, `/api/events`) are the merchant's
+  commerce ledger: payer addresses, amounts, settlement hashes.
   They require `server.adminToken`, and return **404** if none is configured.
 - **Browsers** are governed by `server.allowedOrigins`, an explicit allowlist
   that defaults to empty.
@@ -452,30 +437,30 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
 **Now** - MCP, x402 v2, settlement on the local chain, Base Sepolia and Base
 mainnet, receipts, doctor, deterministic demo, experimental A2A v1.0.0 and ACP
 `2026-04-17` checkout adapters, experimental AP2 v0.2.0 mandate verification,
-and experimental OpenAPI import.
+experimental MPP `charge` payments, and experimental OpenAPI import.
 
-**Next** - a `doctor` GitHub Action · UCP · MPP · autonomous-mode AP2 (open
-mandates, agent key binding, constraint evaluation) · more of ACP (carts, feed,
-delegated payment) · Shopify and WooCommerce examples · PostgreSQL · richer
-observability · multi-file and remote OpenAPI sources.
+**Next** - a `doctor` GitHub Action · UCP ·
+autonomous-mode AP2 (open mandates, agent key binding, constraint evaluation) ·
+more of ACP (carts, feed, delegated payment) · Shopify and WooCommerce examples ·
+PostgreSQL · richer observability · multi-file and remote OpenAPI sources.
 
-New protocols land only after the adapter model survives real use. Scope
-discipline is a release requirement, not a mood.
+New protocols need evidence that the adapter model works in real use before
+they are added to a release.
 
 ## Documentation
 
 |                                                |                                             |
 | ---------------------------------------------- | ------------------------------------------- |
 | [Architecture](docs/architecture.md)           | how the pieces fit                          |
-| [Payment flow](docs/payment-flow.md)           | the paid round trip, and every way it fails |
-| [Protocols](docs/protocols.md)                 | exactly what is and is not supported        |
+| [Payment flow](docs/payment-flow.md)           | the paid round trip and failure paths       |
+| [Protocols](docs/protocols.md)                 | supported and unsupported protocol features |
 | [AP2](docs/ap2.md)                             | mandate verification and the trust model    |
 | [Configuration](docs/configuration.md)         | `config.yaml` reference                     |
 | [OpenAPI import](docs/openapi-import.md)       | generate resources from an existing API     |
 | [Security model](docs/security.md)             | trust boundaries, and what we do not defend |
-| [Contracts](docs/contracts.md)                 | the frozen cross-package contract           |
+| [Contracts](docs/contracts.md)                 | the frozen cross-area contract              |
 | [Adapter guide](docs/contributing-adapters.md) | add a protocol or a payment rail            |
 
-## Licence
+## License
 
 [Apache-2.0](LICENSE).