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

package/docs/autonomous-privy-wallet.md

@@ -131,3 +131,191 @@ capability typed-data requests only. It does not claim ERC-4337, EIP-1271,
 smart-account, or gas-sponsorship support. The broker deployment and its real
 Privy policy remain integration dependencies and must be health-checked before
 use.
+
+## Escrow cutover (V2 → V3): what the broker allows, and the Privy policy change it needs
+
+The broker (both the agent-owned and the session paths) sends transactions to
+exactly two kinds of escrow, read from the registries rather than hardcoded
+(`src/wallet/broker-escrows.ts`):
+
+| Target                                                                                                      | Allowed calls                                                                                                                     |
+| ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| **Current escrow** (the SDK network registry's escrow for the broker's network)                             | `openStream`, `close`, `reclaim`, `reclaimUnverified`                                                                             |
+| **Legacy escrow(s)** (`@absol-labs/shared` deployments with `status: "legacy"`, other than the current one) | `close`, `reclaim`, `reclaimUnverified` **only** — no `openStream`                                                                |
+| **USDC**                                                                                                    | `approve(spender, amount)` with `spender` = the **current** escrow only (never a legacy escrow), `amount` within the existing cap |
+
+Everything else is unchanged: chain id, zero `value`, `from` = the wallet, the
+mandate/spend-cap checks on `openStream`, `stream.buyer == wallet` on every exit
+(read from the escrow the exit targets), and invocation-capability typed data
+bound to the current escrow. V2 and V3 share the selectors of every allowed
+method, so one decoder (the union of the V2/V3 ABIs) serves both.
+
+While the SDK default is still `StreamEscrowV2` (`@absol-labs/sdk@0.10.0-rc.1`),
+V2 is current and nothing is legacy: behaviour is identical to before. With
+`0.10.0-rc.2` the default becomes `StreamEscrowV3` and V2 becomes exit-only, so
+agents holding open V2 streams can still close and reclaim them.
+
+### Privy policy rules to apply at cutover
+
+The broker's checks are a second line; the Privy policy is what Privy itself
+enforces. At the V3 cutover, the policy (`PRIVY_POLICY_ID`) must change as
+follows. Base Sepolia addresses (from `@absol-labs/shared` `escrowDeployments`
+and the SDK registry):
+
+- current escrow (V3): `0x0643ba482C6A7aF31a1f8225e7e7e79Cfc467b13`
+- legacy escrow (V2): `0x0f09f36Ccc05A7c9882F438721C08De314dFd46C`
+- USDC: `0x036CbD53842c5426634e7929541eC2318f3dCF7e`
+
+Keep every existing numeric bound exactly as it is (`openStream`
+`deposit <= 1000000`, `ratePerSecond <= 1000`, `maxDuration <= 3600`; USDC
+`approve` `amount <= 1000000`; chain `eip155:84532`; `value == 0`).
+
+1. **Contract allowlist, escrow — `openStream`**: change the target from the V2
+   escrow to the **V3** escrow only. The legacy V2 escrow must NOT be allowed
+   `openStream`.
+2. **Contract allowlist, escrow — exits** (`close(bytes32)` `0x39c79e0c`,
+   `reclaim(bytes32,uint256,bytes32[])` `0x2c307c9c`,
+   `reclaimUnverified(bytes32)` `0x5fcdce22`): allow them on **both** the V3
+   escrow and the V2 escrow (`to` IN [V3, V2]).
+3. **USDC `approve`** (`0x095ea7b3`): change the allowed `spender` from the V2
+   escrow to the **V3** escrow only. No approval to V2.
+4. Remove any rule that allows the V2 escrow for a method other than the three
+   exits above.
+
+The same, as Privy policy rules (ALLOW rules, `eth_sendTransaction`,
+`chain_type: "ethereum"`; DENY is the default):
+
+```json
+[
+  {
+    "name": "metrik-open-stream-current-escrow",
+    "method": "eth_sendTransaction",
+    "action": "ALLOW",
+    "conditions": [
+      {
+        "field_source": "ethereum_transaction",
+        "field": "chain_id",
+        "operator": "eq",
+        "value": "84532"
+      },
+      {
+        "field_source": "ethereum_transaction",
+        "field": "to",
+        "operator": "eq",
+        "value": "0x0643ba482C6A7aF31a1f8225e7e7e79Cfc467b13"
+      },
+      {
+        "field_source": "ethereum_transaction",
+        "field": "value",
+        "operator": "eq",
+        "value": "0"
+      },
+      {
+        "field_source": "ethereum_calldata",
+        "field": "openStream.deposit",
+        "operator": "lte",
+        "value": "1000000",
+        "abi": "<StreamEscrowV3 openStream ABI>"
+      },
+      {
+        "field_source": "ethereum_calldata",
+        "field": "openStream.ratePerSecond",
+        "operator": "lte",
+        "value": "1000",
+        "abi": "<StreamEscrowV3 openStream ABI>"
+      },
+      {
+        "field_source": "ethereum_calldata",
+        "field": "openStream.maxDuration",
+        "operator": "lte",
+        "value": "3600",
+        "abi": "<StreamEscrowV3 openStream ABI>"
+      }
+    ]
+  },
+  {
+    "name": "metrik-exits-current-and-legacy-escrow",
+    "method": "eth_sendTransaction",
+    "action": "ALLOW",
+    "conditions": [
+      {
+        "field_source": "ethereum_transaction",
+        "field": "chain_id",
+        "operator": "eq",
+        "value": "84532"
+      },
+      {
+        "field_source": "ethereum_transaction",
+        "field": "to",
+        "operator": "in",
+        "value": [
+          "0x0643ba482C6A7aF31a1f8225e7e7e79Cfc467b13",
+          "0x0f09f36Ccc05A7c9882F438721C08De314dFd46C"
+        ]
+      },
+      {
+        "field_source": "ethereum_transaction",
+        "field": "value",
+        "operator": "eq",
+        "value": "0"
+      },
+      {
+        "field_source": "ethereum_calldata",
+        "field": "function_selector",
+        "operator": "in",
+        "value": ["0x39c79e0c", "0x2c307c9c", "0x5fcdce22"]
+      }
+    ]
+  },
+  {
+    "name": "metrik-usdc-approve-current-escrow",
+    "method": "eth_sendTransaction",
+    "action": "ALLOW",
+    "conditions": [
+      {
+        "field_source": "ethereum_transaction",
+        "field": "chain_id",
+        "operator": "eq",
+        "value": "84532"
+      },
+      {
+        "field_source": "ethereum_transaction",
+        "field": "to",
+        "operator": "eq",
+        "value": "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
+      },
+      {
+        "field_source": "ethereum_transaction",
+        "field": "value",
+        "operator": "eq",
+        "value": "0"
+      },
+      {
+        "field_source": "ethereum_calldata",
+        "field": "approve.spender",
+        "operator": "eq",
+        "value": "0x0643ba482C6A7aF31a1f8225e7e7e79Cfc467b13",
+        "abi": "<ERC-20 approve ABI>"
+      },
+      {
+        "field_source": "ethereum_calldata",
+        "field": "approve.amount",
+        "operator": "lte",
+        "value": "1000000",
+        "abi": "<ERC-20 approve ABI>"
+      }
+    ]
+  }
+]
+```
+
+Express the selector restriction in whatever form the live policy already uses
+(a `function_selector` condition, or one calldata-field rule per exit method
+with its ABI). What matters is the set: `openStream` → V3 only; the three exits
+→ V3 and V2; `approve.spender` → V3 only. The existing invocation-capability
+typed-data rule must change its `verifyingContract` to the V3 escrow at the
+same time (the broker already binds it to the current escrow).
+
+Apply the policy change and the `@absol-labs/sdk@0.10.0-rc.2` bump together: the
+broker refuses a V2 `openStream` as soon as the registry default is V3, and the
+policy should too.

package/docs/cli.md

@@ -46,7 +46,8 @@ consumer who installed the package could not run at all. `metrik mcp
 ## Testnet only
 
 The CLI signs with a raw private key and moves USDC, so the chain is an **allowlist**,
-not a default: only Base Sepolia (`84532`) is accepted. There is deliberately **no
+not a default: only networks the `@absol-labs/sdk` network registry knows **and marks as
+a testnet** are accepted (today: Base Sepolia, `84532`). There is deliberately **no
 override flag** — an escape hatch that re-enabled real funds would defeat the guarantee,
 and there is no mainnet deployment for it to reach anyway.
 
@@ -104,6 +105,17 @@ A Privy wallet differs from the other two in one structural way: its account has
 client's transport** instead of the plain `http(--rpc-url)` a local signer uses. That is
 the whole of the wiring. Private-key and CDP runs are unchanged, byte for byte.
 
+**`metrik claim` does not work on a Privy wallet.** The broker's transaction allowlist
+carries the BUYER actions only (`openStream`, `close`, `reclaim`, `reclaimUnverified`), so
+an operator claim is refused server-side and the client cannot raise that ceiling. Claim
+with the operator's own `METRIK_AGENT_PRIVATE_KEY`. Every other command works. The CLI
+warns when you try it, and `metrik --help` / `metrik claim --help` say so up front.
+
+**`metrik mcp` does not carry a Privy wallet either.** The MCP server resolves its wallet
+with `parseAgentWalletEnv()`, which reads `METRIK_AGENT_PRIVATE_KEY` or the CDP variables
+and has no Privy branch — so `metrik mcp --print-config` prints a key placeholder and says
+why on stderr rather than emitting Privy variables the server would ignore.
+
 There are two shapes. Set one; setting both uses the agent-owned wallet and says so.
 
 **Agent-owned (`privy-autonomous`)** — headless, no browser, no user login:
@@ -245,19 +257,21 @@ that needs no key at all — it builds and prints the intended call and says whi
 
 ## Commands
 
-| Command              | Needs a wallet?                | Broadcasts a tx? | What it does                                     |
-| -------------------- | ------------------------------ | ---------------- | ------------------------------------------------ |
-| `discover`           | no                             | no               | Lists verified registry listings                 |
-| `open`               | **yes** (not with `--dry-run`) | **yes**          | Escrows USDC into a metered stream               |
-| `status`             | no                             | no               | One stream's on-chain state + verified accrual   |
-| `streams`            | no (with `--address`)          | no               | Lists a wallet's streams from the escrow's logs  |
-| `watch`              | no                             | no               | Polls that until the stream closes               |
-| `invoke`             | **yes** (off-chain capability) | no               | Calls the paid service, authorized by the stream |
-| `close`              | **yes**                        | **yes**          | Stops the clock                                  |
-| `reclaim`            | **yes**                        | **yes**          | Takes back what was never earned                 |
-| `reclaim-unverified` | **yes**                        | **yes**          | Buyer escape hatch: reclaim with no proof        |
-| `claim`              | **yes** (the operator's)       | **yes**          | Operator: redeem what verified                   |
-| `mcp`                | no                             | no               | Prints the MCP client config for `metrik-mcp`    |
+| Command              | Needs a wallet?                | Broadcasts a tx?  | What it does                                     |
+| -------------------- | ------------------------------ | ----------------- | ------------------------------------------------ |
+| `discover`           | no                             | no                | Lists verified registry listings                 |
+| `open`               | **yes** (not with `--dry-run`) | **yes**           | Escrows USDC into a metered stream               |
+| `status`             | no                             | no                | One stream's on-chain state + verified accrual   |
+| `streams`            | no (with `--address`)          | no                | Lists a wallet's streams from the escrow's logs  |
+| `watch`              | no                             | no                | Polls that until the stream closes               |
+| `invoke`             | **yes** (off-chain capability) | no                | Calls the paid service, authorized by the stream |
+| `pay`                | **yes** (EIP-3009 signature)   | no (relayer does) | Pays an x402 endpoint into an escrow stream      |
+| `refund`             | only for `--close`             | no (relay does)   | Gasless close/reclaim of an x402 stream          |
+| `close`              | **yes**                        | **yes**           | Stops the clock                                  |
+| `reclaim`            | **yes**                        | **yes**           | Takes back what was never earned                 |
+| `reclaim-unverified` | **yes**                        | **yes**           | Buyer escape hatch: reclaim with no proof        |
+| `claim`              | **yes** (the operator's)       | **yes**           | Operator: redeem what verified                   |
+| `mcp`                | no                             | no                | Prints the MCP client config for `metrik-mcp`    |
 
 ### `metrik discover`
 
@@ -358,6 +372,21 @@ as `simulationPendingApproval: true`, with no `simulationError` — a script bra
 that field no longer sees the expected path as a failure. An allowance-shaped revert when
 the allowance IS already sufficient, and every other revert, are still surfaced as errors.
 
+**The operator-signed rate band.** Before anything is signed or broadcast — `--dry-run`
+included — `open` re-verifies the listing's operator-signed descriptor (the same check the
+seller's gateway runs) and refuses at exit `2` when `--rate` is outside its
+`minRatePerSecond`..`maxRatePerSecond` band, e.g. `the operator signed rates 100..10000
+atomic/s (0.0001..0.01 USDC/s); --rate 20000 (0.02 USDC/s) would be refused by the
+service's gateway`. The escrow accepts any non-zero rate, but the gateway answers every
+request on an out-of-band stream with `403 stream-rate-out-of-bounds`, so the deposit
+would sit in a stream that can never be served. Bounds are inclusive; a bound the operator
+did not sign is not enforced, and a legacy binding signs none. A descriptor that does not
+verify is a refusal (exit `4`), never "no band". Without `--operator`, an unreachable
+registry already fails `open` (exit `4`). With `--operator` — the existing escape hatch for
+a service the registry cannot vouch for — the band cannot be read, so the open proceeds
+with a warning saying the rate was **not** checked. There is no flag to override a band
+the CLI can read.
+
 **Amounts.** `--budget` and `--rate` are decimal USDC by default; `--units atomic`
 switches both to raw 6-decimal base units (what the escrow, the oracle and every
 `METRIK_E2E_*` fixture use). The unit is explicit rather than inferred from magnitude,
@@ -520,7 +549,10 @@ Configured mandate ceilings are carried through verbatim — they are policy, no
 and re-typing four caps from memory is where a wrong ceiling comes from. **Credentials are
 always placeholders.** This command never reads a key out of your environment and prints
 it back; the wallet block is simply shaped like the environment it ran in (the CDP
-variables if those are what you have set, `METRIK_AGENT_PRIVATE_KEY` otherwise).
+variables if those are what you have set, `METRIK_AGENT_PRIVATE_KEY` otherwise). A Privy
+wallet is **not** an option here — `parseAgentWalletEnv()` has no Privy branch — so when
+the environment carries one the command says so on stderr and prints a key placeholder
+instead of a config the server could not start from.
 
 ### `metrik invoke`
 
@@ -550,6 +582,96 @@ listings ("consumer-attested T2 invocation is not supported for gated listings")
 live listings are gated — so a `metrik prove` would be a command that fails for almost
 everyone who ran it. It is left out until that constraint lifts.
 
+### `metrik pay` (x402)
+
+```bash
+metrik pay https://x402.example/transform --json '{"text":"# hi"}' --max-amount 0.1
+metrik pay <url> [--json <body> | --data <body>] [--method POST] [--header "K: V"] \
+  --max-amount <usdc> [--max-rate <usdc/s>] [--max-duration <s>] [--min-duration <s>] \
+  [--operator <address>] [--units atomic]
+```
+
+Pays any **x402 v2 `exact`** endpoint through `@absol-labs/sdk/x402`'s `payWithX402`,
+with every SDK protection intact (network and USDC from the registry, EIP-3009 only,
+registered opener factory, `payTo == factory.predict(terms)` read on-chain, bounded
+authorization lifetime, a plain transfer to the seller refused). A Metrik seller's
+payment opens an escrow stream with `deposit = price`; the seller earns
+`ratePerSecond x verified seconds`, capped at the deposit.
+
+The payer needs **USDC only, no gas** (the facilitator's relayer submits the
+authorization). A Privy wallet cannot pay: its broker does not sign EIP-3009.
+
+**How the spend mandate bounds an x402 payment.** No spend without a mandate: a
+payment IS a stream open, so its opener terms are checked by `checkMandate()` exactly
+like `metrik open`, inside the SDK's `onQuote` hook, after the SDK's own checks and
+**before anything is signed**:
+
+| Mandate cap            | Checked against                                |
+| ---------------------- | ---------------------------------------------- |
+| `maxPerStreamUsdc`     | the quote's `amount` (= the deposit)           |
+| `maxTotalUsdc`         | spent so far + `amount`                        |
+| `maxRatePerSecondUsdc` | `ratePerSecond` (how fast the seller can earn) |
+| `maxDurationSeconds`   | `maxDuration` (the stream window)              |
+| `allowedOperators`     | `operator` (who the stream pays)               |
+
+The caps are also handed to the SDK as `maxAmount` / `maxRatePerSecond`, so the price is
+enforced twice. A quote with no opener terms is refused. The mandate comes from
+`METRIK_AGENT_MANDATE_*` when set, otherwise it is sized to this command:
+`--max-amount` (required then) is the per-stream and total cap, `--max-rate` the rate cap
+(default: no tighter than the price), `--max-duration` the window cap (default 1 day),
+`--operator` the only allowed operator. With a standing mandate, every flag
+**intersects** it (the most restrictive value wins; an `--operator` outside
+`METRIK_AGENT_MANDATE_ALLOWED_OPERATORS` is refused): a flag can tighten the
+standing ceiling, never loosen or bypass it. Like every CLI mandate it covers one
+invocation.
+
+If anything fails after the authorization was handed to the seller, `metrik pay`
+establishes the outcome on-chain (USDC `authorizationState`, the opener's
+`StreamOpenedFor` log for that nonce), exits `4`, and says whether the money left
+the payer — with the `streamId` and the recovery command when the stream is found.
+It never reports "nothing moved" unless the authorization was unused and expired.
+
+A quote naming a **legacy** deployment's factory (for example a seller still on
+StreamEscrowV2 after the default moved to V3) is refused by the SDK unless you pass
+`--allow-legacy-factory`; that stream is then closed and reclaimed on the legacy
+escrow, and the printed recovery command carries `--escrow <legacy escrow>`.
+
+`--json <body>` is the request body (curl-style, sets `content-type: application/json`);
+a bare `--json` still selects JSON output, and both can be combined. The output is the
+response, the `streamId`, the opener, the deposit and rate, `minEarnSeconds` (after how
+many verified seconds nothing is left to reclaim) and the **refund URL**.
+**Refunds are not automatic** — see `metrik refund`.
+
+Exit codes: `2` usage (including no ceiling), `3` refused by the mandate or the SDK
+(nothing signed), `4` the settlement failed after signing (the error says whether the
+authorization was used and how to cancel it; see [x402.md](./x402.md)).
+
+### `metrik refund`
+
+```bash
+metrik refund <streamId> --refund-url <url> [--close] [--reclaim] [--attempts 5] [--max-wait 60]
+```
+
+Drives the seller's **gasless refund relay** through the SDK's `refundClient`, bound to
+the stream and to the opener read **from chain** (`factory.isOpener`), never from the
+relay. With no action flag it prints the status and the next step. `--close` signs the
+opener's EIP-712 `Close` as the payer (the relay pays the gas; authorized on the mandate
+owner's signature only, like `metrik close`). `--reclaim` sends the permissionless
+`opener.reclaim` (no wallet needed; the refund always goes to `payerOf(streamId)`) and
+retries a bounded number of times while the settlement window is open, honouring
+`Retry-After`; a longer wait exits `3` with the time to retry. Every relay "success" is
+checked against the transaction receipt on the configured chain. `--refund-url` accepts
+the full URL `metrik pay` printed, a `{streamId}` template or the relay's origin; it can
+also come from `METRIK_AGENT_REFUND_URL`.
+
+Nothing is refunded automatically, and the relay is a convenience: a payer can always
+recover on-chain without it (`metrik close` as the payer, with gas; `metrik reclaim` by
+anyone).
+
+`status`, `close` and `reclaim` understand opener-bought streams: they show the opener and the
+payer, `close` routes through the opener (payer only), and `reclaim` sends the
+permissionless opener reclaim and reports the refund to the payer.
+
 ### `metrik close` and `metrik reclaim`
 
 ```bash
@@ -563,12 +685,32 @@ returns the unspent budget, and the buyer sends it. `close` now points at
 `--close-first` for next time, rather than leaving the one-shot form visible only in
 `metrik reclaim --help`.
 
+**`reclaim` names the condition before it spends anything.** Three different on-chain
+states stop a reclaim, and they have three completely different answers: the stream was
+already reclaimed (you have the money), the stream is still running (close it first), or
+its stop time is not checkpointed yet (wait ~20 seconds). The CLI reads `getStream`,
+`latestCheckpointCheckedAt` and the chain clock up front and says which one it is, rather
+than sending a simulation and repeating whatever the endpoint's revert data decoded to —
+on the public Base Sepolia RPC all three came back as `Execution reverted for an unknown
+reason`. The pre-flight **fails open**: a read that does not answer never blocks the
+reclaim, because refusing to return a buyer's deposit over a dropped view call is worse
+than a wasted simulation.
+
 **`reclaim` waits, by design.** `reclaimWithProof` reverts with `SettlementWindowOpen`
 until a checkpoint whose `checkedAt` is at or after the stream's stop time has posted.
 That is the normal ordering of a checkpoint rail, not a fault — in practice the first
-attempt fails and one roughly 30 seconds later succeeds. The CLI retries **that one
-condition** on a bounded schedule and narrates the wait on stderr; every other failure is
-surfaced immediately and unretried.
+attempt fails and one roughly 30 seconds later succeeds. The CLI retries on a bounded
+schedule and narrates the wait on stderr; every other failure is surfaced immediately and
+unretried.
+
+The wait shows up in three shapes, and all three retry: the escrow's decoded
+`SettlementWindowOpen`; the **oracle** refusing a proof for a stream it has not
+checkpointed yet (the SDK fetches the proof before it simulates, so the escrow's revert
+never happens and the error is `StreamNotInCheckpointError` / `CheckpointNotReadyError`);
+and a reclaim revert the ABI could not decode, where the chain's state is read to decide.
+Only recognising the first of those is what made `--close-first` die on its first attempt
+against a stream closed before its first covering checkpoint — the ordinary result of a
+short trial run.
 
 If it is still blocked when the budget runs out, the message does **not** just say "retry
 later" — every attempt this command makes needs a proof from the oracle, so when the
@@ -584,8 +726,10 @@ lands on another that has not imported the block.) If the stream is **already**
 the close is skipped and the command goes straight to reclaim — so re-running it is always
 safe and never dead-ends on `StreamClosedAlready()`.
 
-`reclaim` on a stream that is still running reports that in words, with the command that
-fixes it, rather than surfacing the `StreamNotReclaimable()` selector.
+`--close-first` is also the one caller allowed past the still-running refusal, since
+clearing that state is the whole point of the flag. Once the close has landed it reports
+what the following retries are waiting for — the stop time, and how far the oracle has
+published — so the wait reads as the advertised wait rather than as a stalled command.
 
 Close and reclaim are buyer-recovery actions: `VerifiedStreamAgentClient` authorizes them
 on the mandate owner's signature alone, never on caps or expiry, so a lapsed mandate can
@@ -682,17 +826,26 @@ that wait legible.
 
 ## Settlement configuration
 
-Everything defaults to Metrik's live Base Sepolia deployment, and every value is
-overridable per command or through the environment:
-
-| Flag             | Env                         | Default                               |
-| ---------------- | --------------------------- | ------------------------------------- |
-| `--chain-id`     | `METRIK_AGENT_CHAIN_ID`     | `84532`                               |
-| `--rpc-url`      | `METRIK_AGENT_RPC_URL`      | Base Sepolia public RPC               |
-| `--escrow`       | `METRIK_AGENT_ESCROW`       | `BASE_SEPOLIA_ESCROW_V2`              |
-| `--usdc`         | `METRIK_AGENT_USDC`         | `BASE_SEPOLIA_USDC`                   |
-| `--oracle-url`   | `METRIK_AGENT_ORACLE_URL`   | `https://oracle.metrik.live`          |
-| `--registry-url` | `METRIK_AGENT_REGISTRY_URL` | the oracle's public listings endpoint |
+Everything defaults to the selected network's entry in the `@absol-labs/sdk` network
+registry (the default network is Base Sepolia), and every value is overridable per
+command or through the environment. Nothing chain-specific is hardcoded in the CLI.
+
+| Flag                  | Env                              | Default                                                                |
+| --------------------- | -------------------------------- | ---------------------------------------------------------------------- |
+| `--network`           | `METRIK_NETWORK`                 | the registry default (id, chain id or CAIP-2)                          |
+| `--chain-id`          | `METRIK_AGENT_CHAIN_ID`          | the network's chain id (must agree if both set)                        |
+| `--rpc-url`           | `METRIK_AGENT_RPC_URL`           | the network's first registered RPC                                     |
+| `--escrow`            | `METRIK_AGENT_ESCROW`            | the network's current escrow (V3); a `legacy` one (V2) for its streams |
+| `--escrow-generation` | `METRIK_AGENT_ESCROW_GENERATION` | the registry's; REQUIRED only for an unregistered escrow               |
+| `--usdc`              | `METRIK_AGENT_USDC`              | the network's registered USDC                                          |
+| `--oracle-url`        | `METRIK_AGENT_ORACLE_URL`        | the network's oracle                                                   |
+| `--registry-url`      | `METRIK_AGENT_REGISTRY_URL`      | the network's public listings endpoint                                 |
+
+The gas preflight names the network's gas token and faucet (from its gas-token
+metadata) instead of assuming ETH; on a network whose gas IS the settlement USDC it
+checks the one USDC balance and requires the deposit to leave room for gas. An
+`--escrow` the registry does not record has no log-scan anchor, so `metrik streams`
+needs `--from-block` for it.
 
 ## Embedding it
 

package/docs/langchain.md

@@ -12,6 +12,11 @@ Create them with [`createLangChainVerifiedStreamTools()`](../src/frameworks/lang
 ## Safety model
 
 - `hire_verified_service` checks the signed mandate before any stream open.
+- It then refuses a `ratePerSecondUsdc` outside the listing's operator-signed rate
+  band (the seller's gateway would refuse every request on that stream), and fails
+  closed when the registry cannot be read. An unlisted `serviceRef` has no signed
+  band and is not constrained. The same check runs in the ElizaOS and AgentKit
+  adapters.
 - `reclaim_unspent` passes the same signed-mandate context into the agent client,
   which re-checks authorization before the SDK can write.
 - `check_stream_status` is read-only and also returns `shouldStop` for a closed

package/docs/mcp-reference.md

@@ -36,11 +36,16 @@ an economic question, not a cryptographic one.
 | `reclaim_unspent`       | **yes**     | Closes the stream (**stops the meter**) and returns unspent USDC to the buyer.  |
 | `list_streams`          | no          | Lists the streams this server opened.                                           |
 | `prove_https_response`  | no          | Buyer-side zkTLS proof of a response. Registered only with Reclaim credentials. |
+| `x402_pay`              | **yes**     | Pays an x402 endpoint (opener path, docs/x402.md) under the spend mandate.      |
+| `refund_status`         | no          | Refund state of an x402 stream, from the seller's gasless refund relay.         |
+| `refund`                | **yes**     | Gasless close (payer-signed) and reclaim of an opener stream via the relay.     |
 
 ### `discover_services`
 
 `category?`, `limit?`. Returns `serviceRef`, `operator`, `publicUrl`, `access`,
-`accessUrl` per listing.
+`accessUrl` per listing, plus `ratePerSecondBand` (`minRatePerSecondUsdc` /
+`maxRatePerSecondUsdc`, atomic units, `null` for an unsigned side) when the
+operator's signed descriptor carries one.
 
 The registry is an **untrusted transport**: every `serviceRef` is re-derived
 from the signed record and the operator's signature recovered, so a compromised
@@ -80,6 +85,16 @@ warning on the result. It is operator-set input only — never a tool argument,
 because the caller being asked to relax a fund-safety check is the LLM the check
 exists to constrain — and it never overrides a positive contradiction.
 
+`ratePerSecondUsdc` must sit inside the listing's operator-signed rate band
+(inclusive). The descriptor is re-verified with the gateway's own check, and an
+out-of-band rate is refused before any approval or open is sent: the escrow
+accepts any non-zero rate, but the seller's gateway answers every request on
+such a stream with `403 stream-rate-out-of-bounds`. A descriptor that does not
+verify is a refusal. Under `METRIK_AGENT_ALLOW_UNVERIFIED_OPERATOR=true` an
+unverifiable pairing has no listing to read a band from, and the result's
+warning says the rate was not checked; the override never widens a band the
+server can read.
+
 The result carries a `metering` block: the rate, the budget, the maximum this
 stream can ever spend, and what starts and stops the clock.
 
@@ -151,6 +166,56 @@ evidence of a delivery that did not happen here.
 This is an L2 signal to be cross-checked with oracle/L1 evidence — not a
 substitute for it.
 
+### `x402_pay`
+
+Arguments: `url` (https; http only for localhost), optional `method`, `headers`,
+`body`, `maxAmountUsdc`, `maxRatePerSecondUsdc` (base units; these can only TIGHTEN
+the server mandate) and `minDurationSeconds`. Pays through `@absol-labs/sdk/x402`'s
+`payWithX402` with every SDK protection intact, and is gated exactly like
+`hire_verified_service`: the same server mandate, the same cumulative spend, the
+same per-owner serialization. The payment's opener terms are checked by
+`checkMandate()` before anything is signed — `amount` (the deposit) against the
+per-stream and total caps, `ratePerSecond`, `maxDuration` and `operator` against
+theirs — and the stream it opens is recorded, so it counts against `maxTotalUsdc`.
+A caller-supplied `PAYMENT-SIGNATURE` / `X-PAYMENT` header is refused. The result
+carries the response (bounded), `streamId`, `opener`, `refundUrl`, the deposit and
+rate, and `refundIsAutomatic: false`.
+
+### `refund_status` / `refund`
+
+Arguments: `streamId`, optional `refundUrl` (not needed for a stream this server
+paid for — it was recorded); `refund` also takes `close` (stop the stream first;
+this wallet signs the opener's `Close`, authorized on the mandate owner's signature
+alone like `reclaim_unspent`) and `reclaim` (default `true`; the permissionless
+reclaim, the refund always goes to the payer). Every relay success is verified
+against the transaction receipt. A settlement window that is still open is reported
+with when to retry. Nothing is refunded automatically.
+
+The three x402 tools are **opt-in**: set `METRIK_AGENT_X402=1` to register them
+(any other value, or none, leaves them off).
+
+**Spend is reserved before anything is signed.** When the mandate approves a
+quote, `x402_pay` records a reservation for its amount in the stream registry
+— inside the same per-owner queue as `hire_verified_service` — before the SDK
+signs the EIP-3009 authorization. If anything fails after the signature has
+been handed out (a malformed or missing `PAYMENT-RESPONSE`, an unconfirmed
+settlement, a dropped connection), the outcome is established from the chain,
+never from the seller: USDC `authorizationState(from, nonce)` and the opener's
+`StreamOpenedFor(streamId, payer, authorizationNonce, …)` log. The reservation
+is released only if the authorization was never used AND has expired; a stream
+found on-chain replaces it under its real `streamId`; otherwise it stays
+counted, and the tool says the money may have moved — never "not settled".
+
+**Outbound requests are guarded.** The URLs the payment tool, `refund` and
+`refund_status` contact come from the model, so every request must be `https:`
+to a host whose every resolved address is public (loopback, private,
+link-local, unique-local, CGNAT, multicast and reserved ranges are refused),
+redirects are never followed, and `METRIK_AGENT_X402_ALLOWED_HOSTS`
+(comma-separated, exact or `*.domain`) restricts it further — list the seller
+AND its refund relay. A response that did not ask for payment is not returned
+(status only). The address is checked at lookup time; use the allowlist where
+DNS rebinding matters.
+
 ## Configuration
 
 `metrik mcp --print-config` prints the `mcpServers` block to paste into an MCP
@@ -159,11 +224,15 @@ in it are placeholders by design.
 
 | Variable                                 | Required | Meaning                                                                                         |
 | ---------------------------------------- | -------- | ----------------------------------------------------------------------------------------------- |
-| `METRIK_AGENT_RPC_URL`                   | **yes**  | Base Sepolia RPC.                                                                               |
-| `METRIK_AGENT_ESCROW`                    | **yes**  | The **StreamEscrowV2** address. The retired V1 escrow is refused.                               |
+| `METRIK_AGENT_RPC_URL`                   | **yes**  | RPC of the selected network.                                                                    |
+| `METRIK_AGENT_ESCROW`                    | **yes**  | The network's registered **StreamEscrowV2**. Anything else is refused (see below).              |
 | `METRIK_AGENT_USDC`                      | **yes**  | Settlement token.                                                                               |
 | `METRIK_AGENT_ESCROW_GENERATION`         | no       | `v2` (default, and the only supported value). Declared, not probed.                             |
-| `METRIK_AGENT_CHAIN_ID`                  | no       | Defaults to `84532`; nothing else is accepted.                                                  |
+| `METRIK_NETWORK`                         | no       | Registry id, chain id or CAIP-2 id; default the registry's default network. Testnets only.      |
+| `METRIK_AGENT_CHAIN_ID`                  | no       | Alternative selector; must agree with `METRIK_NETWORK` when both are set.                       |
+| `METRIK_AGENT_ALLOW_UNREGISTERED_ESCROW` | no       | `true` accepts an escrow the registry does not record (a deliberate private deployment).        |
+| `METRIK_AGENT_X402`                      | no       | `1` registers `x402_pay`, `refund_status`, `refund`. **Off by default.**                        |
+| `METRIK_AGENT_X402_ALLOWED_HOSTS`        | no       | Comma-separated hosts (`*.domain` allowed) the x402 tools may contact. Unset = any public host. |
 | `METRIK_AGENT_REGISTRY_URL`              | no       | Registry the invocation origin is verified against.                                             |
 | `METRIK_AGENT_ALLOW_UNVERIFIED_OPERATOR` | no       | `true` downgrades an unverifiable operator pairing from a refusal to a warning. Off by default. |
 | `METRIK_AGENT_MCP_STATE_FILE`            | no       | Persists the stream registry across restarts.                                                   |
@@ -171,5 +240,6 @@ in it are placeholders by design.
 | wallet vars                              | **yes**  | `METRIK_AGENT_PRIVATE_KEY`, or the CDP/Privy set.                                               |
 
 The escrow generation is a **declared fact, not an inference**: the server
-refuses the retired V1 address by name, because a wrong-generation read does not
+refuses any escrow that is not the network's registered `StreamEscrowV2` (the
+retired V1 escrow included) unless `METRIK_AGENT_ALLOW_UNREGISTERED_ESCROW=true`, because a wrong-generation read does not
 revert — it returns confident nonsense about someone's money.