twzrd-x402-gate 0.9.2 → 0.9.4

package/QUICKSTART.md

@@ -1,17 +1,15 @@
 # twzrd-x402-gate — Quickstart (15 minutes, 0 USDC)
 
-Refuses payment to a wash-flagged merchant **before your wallet signs**. Free intel, no
-API key, no signup, no config — every `TWZRD_*` env var is an optional override. If intel
-is unreachable the gate never *invents* a wash flag (the wash check fails open); a failed
-preflight blocks the payment by default (`TWZRD_FAIL_OPEN=true` to allow).
+**Product:** replace naked `createX402Client({ wallet })` with a client that
+**refuses wash before sign**. Free `merchant_card`, no API key. Intel down →
+**fail-open** (never invents wash). No Path A in the default path.
 
-**Pin:** `twzrd-x402-gate@0.8.18` + stock PayAI client `x402-solana@2.1.0` (official
-`beforePayment` seat). `@x402/core` Path E remains supported; refuse script is fallback.
+**Pin:** `twzrd-x402-gate@0.9.3` + `x402-solana@3.0.0`.
 
 ## 1. Stock PayAI client (default seat — copy-paste)
 
 ```bash
-npm install twzrd-x402-gate@0.8.18 x402-solana@2.1.0
+npm install twzrd-x402-gate@0.9.3 x402-solana@3.0.0
 ```
 
 > **ESM-only.** The package ships `import` conditions only — a CommonJS
@@ -19,6 +17,16 @@ npm install twzrd-x402-gate@0.8.18 x402-solana@2.1.0
 > fails with `ERR_PACKAGE_PATH_NOT_EXPORTED`. Set `"type": "module"` in your
 > package.json, use `.mjs`, or bundle ESM.
 
+```typescript
+import { createX402Client } from "x402-solana";
+import { createTwzrdPayingClient } from "twzrd-x402-gate";
+
+// was: createX402Client({ wallet })
+const client = createX402Client(createTwzrdPayingClient({ wallet }));
+```
+
+Or hook-only:
+
 ```typescript
 import { createX402Client } from "x402-solana";
 import { createTwzrdBeforePaymentHook } from "twzrd-x402-gate";
@@ -26,17 +34,18 @@ import { createTwzrdBeforePaymentHook } from "twzrd-x402-gate";
 const client = createX402Client({
   wallet,
   network: "solana",
-  beforePayment: createTwzrdBeforePaymentHook({ refuseWashFlagged: true }),
+  beforePayment: createTwzrdBeforePaymentHook(),
 });
 ```
 
-Equivalent: `beforePayment: installTwzrdAutoGate("x402-solana", { refuseWashFlagged: true })`.
+Default engine = wash only. Full 0.8 preflight/Path A: `{ engine: "full" }`.
+
 Then: `await client.fetch("https://merchant.example/paid");`
 
 ## 1b. Official `@x402/core` client (Path E)
 
 ```bash
-npm install twzrd-x402-gate@0.8.18 @x402/core @x402/fetch @x402/svm
+npm install twzrd-x402-gate@0.9.3 @x402/core @x402/fetch @x402/svm
 ```
 
 ```typescript
@@ -53,7 +62,7 @@ installTwzrdAutoGate(client, { refuseWashFlagged: true });
 
 ```bash
 # Stock-client seat proof (beforePayment, signer_invocation_count=0)
-# needs x402-solana@2.1.0 installed - the harness fallback runs but does not
+# needs x402-solana@3.0.0 installed - the harness fallback runs but does not
 # clear closure (its negative arm counts a would-be sign)
 npm run x402-solana-before-payment-proof
 # writes block-proof-<run_id>.json — hook: beforePayment
@@ -124,3 +133,38 @@ Everything else (thresholds, wash caps, fail posture, settle guard): [README](./
   allowed, observed) unless you set `TWZRD_UNSUPPORTED_NETWORK_MODE=strict`.
 - **No delivery guarantee.** It screens the merchant before you pay, nothing after.
 - **Not a wallet.** It never holds keys or signs — it only decides if your signer runs.
+
+
+## Pay Kit before-payment hook (upstream PR pending)
+
+`solana-foundation/pay-kit#303` is open as of 2026-09-07. This adapter targets
+that PR's `onBeforeX402PaymentCreation` option; a released Pay Kit client must
+expose that option before this integration can enforce policy.
+
+```ts
+import { createPayKitClient } from "@solana/pay-kit";
+import { installTwzrdAutoGate } from "twzrd-x402-gate";
+
+const client = await createPayKitClient({
+  accept: ["x402"],
+  rpcUrl,
+  signer,
+  onBeforeX402PaymentCreation: installTwzrdAutoGate("pay-kit", {
+    refuseWashFlagged: true,
+  }),
+});
+```
+
+The adapter returns the official x402 context hook and reuses the shared
+before-payment evaluator. It adds no Pay Kit dependency. Supply it at client
+construction; passing the constructed Pay Kit client to AutoGate is unsupported.
+This hook covers x402 payment creation, not Pay Kit's MPP path.
+
+`createTwzrdPayKitBeforePaymentHook(options)` exposes the same evaluator directly.
+The AutoGate form reads environment kill switches on every call; the direct
+factory does not. Calling AutoGate installs protection by default, whereas
+ClawRouter's integration loads AutoGate only after explicit opt-in.
+
+Source-checkout verification: `npx tsx test/pay-kit-before-payment.test.ts`.
+The test covers a fake Pay Kit host and the real x402 client with a fake scheme;
+it does not establish released Pay Kit compatibility or external use.

package/README.md

@@ -1,35 +1,72 @@
 # twzrd-x402-gate
 
-**TWZRD is the spend-control SDK for agents paying over x402** — and the default
-`onBeforePaymentCreation` policy engine for official x402 clients.
+**Product: the paying client that already has the brake.**
 
-### One call (named export `twzrd`)
+Agents pay other machines unsupervised. Most 402s are junk or wash. Something has
+to say **no** before the signature. TWZRD is that no — inside `beforePayment` /
+fetch+sign, not inside PayAI’s SDK defaults, not as a shop at intel.twzrd.xyz.
 
-```js
-import { twzrd } from "twzrd-x402-gate";
+The other reason the no must live at the signature: **attaching a funded wallet
+to an agent that reads untrusted web content is a drain vector** — indirect
+prompt injection can spend anything the agent can sign. The gate closes it by
+attaching the wallet to a policy runtime the injected content cannot
+renegotiate: per-request cap, rolling daily ceiling, wash brake, endpoint
+mandates, and a tamper-evident spend ledger that survives restarts. A fully
+compromised agent spends at most what policy allows, to whom it allows, with
+every decision signed.
 
-const result = await twzrd.safeFetch(url, {
-  maxSpend: "0.10",              // per-call cap AND cumulative budget
-  allowNetworks: ["solana", "base"],
-  requireOfferBinding: true,     // demand a chain-verifiable bind-v1 receipt
-  pay,                           // your wallet signs — this SDK never holds keys
+### Replace naked `createX402Client({ wallet })` (5 lines)
+
+```bash
+npm install twzrd-x402-gate@0.9.3 x402-solana@3.0.0
+```
+
+```typescript
+import { createX402Client } from "x402-solana";
+import { createTwzrdPayingClient } from "twzrd-x402-gate";
+
+// was: createX402Client({ wallet })
+const client = createX402Client(createTwzrdPayingClient({ wallet }));
+```
+
+Equivalent one-hook form:
+
+```typescript
+import { createX402Client } from "x402-solana";
+import { createTwzrdBeforePaymentHook } from "twzrd-x402-gate";
+
+const client = createX402Client({
+  wallet,
+  network: "solana",
+  beforePayment: createTwzrdBeforePaymentHook(), // wash default
 });
-// result.verdict: "allow" | "warn" | "block" — blocks have signerInvocations === 0
-// result.receipt: { strength: "hard"|"soft"|"refuse", leaf_hash, fact_type: "resource_bound" }
 ```
 
-Full walkthrough: [QUICKSTART.md](https://github.com/twzrd-sol/twzrd-trust/blob/main/QUICKSTART.md) ·
-verify receipts yourself: [REVIEW.md](https://github.com/twzrd-sol/twzrd-trust/blob/main/REVIEW.md)
+**Default path (engine `"wash"`):**  
+`GET /v1/intel/merchant_card/{payTo}` → abort **iff** `wash_flagged === true` →  
+**fail-open** on timeout / non-2xx / throw (never invent wash).  
+No Path A, no requireReceipt, no second 402, no payment-control tokens.
 
-**Core product (buyer gate):** after the client selects the exact payment requirement and
-**before** payment payload creation / wallet signing — free preflight + merchant_card wash
-refuse. Protects the **payer** from a risky **merchant** (`payTo`). Chain-neutral envelope;
-**Solana-deep** reputation only (Base/EVM = explicit `unknown`).
+**Full 0.8.x engine (named opt-in):** preflight + optional Path A / escalate /
+paymentControl:
 
-### Default-on AutoGate (5 lines)
+```typescript
+createTwzrdBeforePaymentHook({ engine: "full", /* … */ })
+// or createTwzrdFullBeforePaymentHook({ … })
+```
+
+Customer = whoever ships `createX402Client({ wallet })` with no hook (Eliza, MCP
+hosts, agent wallets). Crawlers will never `npm install`.
+
+> **ESM-only:** CommonJS `require()` fails with `ERR_PACKAGE_PATH_NOT_EXPORTED`
+> — set `"type": "module"` (or use `.mjs` / an ESM bundler).
+
+### Default-on AutoGate (alternate seats)
 
 ```bash
-npm install twzrd-x402-gate @x402/core @x402/fetch @x402/svm
+npm install twzrd-x402-gate@0.9.3 x402-solana@3.0.0
+# official @x402/* path (alternate seat):
+# npm install twzrd-x402-gate@0.9.3 @x402/core @x402/fetch @x402/svm
 ```
 
 ```typescript
@@ -37,26 +74,28 @@ import { x402Client } from "@x402/core/client";
 import { installTwzrdAutoGate } from "twzrd-x402-gate";
 
 const client = new x402Client();
-// refuseWashFlagged defaults true; gateOnCanSpend stays false unless you opt in
+// stock solana seat still defaults to wash via createTwzrdBeforePaymentHook()
 installTwzrdAutoGate(client, { refuseWashFlagged: true });
 // then register schemes + wrapFetchWithPayment as usual
 ```
 
-**Intercept proof (0 USDC, wash seller never reaches signer):**
+**Intercept proof (0 USDC, bad seller never reaches signer):**
 
 ```bash
 cd packages/twzrd-x402-gate && npm run autogate-block-proof
 # writes block-proof-<run_id>.json  (schema twzrd.autogate_block_proof.v1)
-# public reason: TWZRD_TRUST_GATE_BLOCK: wash_flagged
+# public reason: "TWZRD_TRUST_GATE_BLOCK: wash_flagged"    (wash basis)
+#            or  "TWZRD_TRUST_GATE_BLOCK: decision_block"  (readiness block basis)
+# fixture resolves live: wash_flagged seller if available, else decision=block
 ```
 
-`gateOnCanSpend` remains **opt-in** (`false` by default; set `true` or `TWZRD_GATE_ON_CAN_SPEND=1` only when you want hard cap enforcement).
+`gateOnCanSpend` remains **opt-in** (`false` by default; set `true` or `TWZRD_GATE_ON_CAN_SPEND=1` only when you want hard cap enforcement). Full-engine preflight outage default stays fail-closed unless `failOpen: true` / `TWZRD_FAIL_OPEN=1`. The **product wash path always fail-opens** on intel outage.
 
-**Optional (0.8.1):** a resource-server settle hook so merchants can apply **customer policy**
+**Optional:** a resource-server settle hook so merchants can apply **customer policy**
 before they settle and serve (abuse, sanctions, bots, “don’t serve this payer”). Not an equal
 mirror of the buyer problem — settled USDC is final; wash resistance is mainly TWZRD scoring.
 
-## Seller settle guard (`onBeforeSettle`) — optional 0.8.1
+## Seller settle guard (`onBeforeSettle`) — optional
 
 Resource servers can screen the **payer** before *they* settle an inbound payment and serve
 the resource. Use for merchant policy (abuse / sanctions / bots / customer selection). TWZRD is
@@ -68,7 +107,7 @@ transfer on-chain. Wash/sybil edges are primarily discounted in TWZRD scoring, n
 revenue refusal.
 
 ```bash
-npm install twzrd-x402-gate@0.8.18
+npm install twzrd-x402-gate@0.9.3
 ```
 
 ```typescript
@@ -100,7 +139,23 @@ Offline demo: `npx tsx examples/seller-settle-guard.ts`
 Fixture-backed SVM extract tests live in `test/seller-hook.test.ts` +
 `test/fixtures/exact-svm-transfer-checked.ts`.
 
-**PayAI agentic-payments** (the active PayAI SDK, not the dormant x402-solana):
+**PayAI x402-solana@2.1.0+** (stock client - primary Solana seat via `beforePayment`).
+Both 2.1.0 and 3.0.0 are supported and produce an identical refuse transcript; 3.0.0
+is the current release and what the install lines pin. The hook absorbs the one
+breaking change between them (`declaredResource` is a string on 2.1.0, `{ url }` on
+3.0.0) - see `src/x402-client-hook.ts` and `test/x402-solana-before-payment.test.ts`.
+
+```typescript
+import { createX402Client } from "x402-solana";
+import { createTwzrdPayingClient } from "twzrd-x402-gate";
+
+const client = createX402Client(createTwzrdPayingClient({ wallet }));
+```
+
+Also: `installTwzrdAutoGate("x402-solana", opts)` returns the same wash-default hook.
+Prove refuse-before-sign: `npm run x402-solana-before-payment-proof`.
+
+**PayAI agentic-payments** (alternate PayAI surface; prefer x402-solana@3.0.0 when available):
 `npx tsx examples/payai-agentic-onPaymentVerified.ts` — wire `onPaymentVerified`
 → `toPayaiVerifyResult` to screen payers before serving. Fail-open by default.
 
@@ -112,7 +167,7 @@ Fixture-backed SVM extract tests live in `test/seller-hook.test.ts` +
 Install the published gate and run against wash fixtures:
 
 ```bash
-npm install twzrd-x402-gate@0.8.18
+npm install twzrd-x402-gate@0.9.3
 # from package root after install, or from a checkout:
 npm run wash-dogfood
 ```
@@ -132,7 +187,7 @@ Gate dogfood: `approved=false` `reason=twzrd_decision_block`, **USDC spent = 0**
 
 **Accurate paste line:**
 
-> Preflight returned decision=block on wash seller 7G73PL… / HuSiSpc… (preflight_id 378468 / 378469, wash_flagged=true). Gate approved=false reason=twzrd_decision_block. No USDC spent. No tx broadcast. Repro: `npm i twzrd-x402-gate@0.8.5 && npm run wash-dogfood` or gist above.
+> Preflight returned decision=block on wash seller 7G73PL… / HuSiSpc… (preflight_id 378468 / 378469, wash_flagged=true). Gate approved=false reason=twzrd_decision_block. No USDC spent. No tx broadcast. Repro: `npm i twzrd-x402-gate@0.9.1 && npm run wash-dogfood` or gist above.
 
 This is a **reproducible demonstration** that the free gate blocks known wash sellers with stamped `preflight_id`s and zero spend. It is **not** proof that external agents already default to this path at scale.
 
@@ -210,11 +265,61 @@ No AgentCash. No marketplace. No second probe. No TWZRD custody.
 Wire `twzrdOnPaymentRequested` / prefer `onPaymentRequired` + `onBeforePayment` per
 [lifecycle hooks](https://docs.x402.org/advanced-concepts/lifecycle-hooks). Same policy core.
 
+### Cloudflare Agents x402 (Base)
+
+Cloudflare's `withX402Client` takes an `onPaymentRequired` callback before its
+automatic payment retry. Use the adapter below at that boundary:
+
+```ts
+import { createTwzrdCloudflareX402Approval } from "twzrd-x402-gate";
+
+const approvePayment = createTwzrdCloudflareX402Approval({
+  // Base/EVM has no TWZRD behavioral reputation yet. Refuse it rather than
+  // presenting a policy allow as a trust verdict.
+  unsupportedNetworkMode: "strict",
+});
+
+await this.x402Client.callTool(approvePayment, {
+  name: "paid_tool",
+  arguments: {},
+});
+```
+
+`observe` is available for an agent that intentionally permits unscored Base
+payments, but it returns policy allow with `decision=unknown`; it is never a
+TWZRD reputation approval. This adapter protects the Cloudflare x402 path only.
+MPP is a separate protocol and belongs on its own `onChallenge` /
+`onPaymentRequired` control path.
+
+### Cloudflare Worker / Base x402 (edge-safe preflight)
+
+For a Worker, import the dedicated subpath rather than the package root. It has
+no Node-native imports and sends the exact Base `payTo` plus `chain_id: 8453` to
+`/v1/intel/preflight` before a Viem account signs:
+
+```ts
+import { withTwzrdBasePreflight } from "twzrd-x402-gate/cloudflare-base";
+
+const signature = await withTwzrdBasePreflight(
+  paymentRequirements, // accepts: [{ network: "eip155:8453", payTo: "0x..." }]
+  { intelBase: "https://intel.twzrd.xyz" },
+  () => account.signTypedData(eip3009Authorization),
+);
+```
+
+`block` throws `TwzrdBasePaymentBlockedError` and never invokes the signing
+callback. `allow` and `warn` both proceed; enforce any additional amount or
+mandate policy in the caller. Base is not presented as reputation-scored.
+Checksummed and lowercase EVM addresses are accepted unchanged. The fixture in
+[`test/cloudflare-base-edge.test.ts`](./test/cloudflare-base-edge.test.ts) proves
+`block → zero signTypedData calls` and the compiled subpath is checked for Node
+runtime leaks.
+
 ### Raw-fetch composition (injectible pay client only)
 
 ```typescript
 import { installTwzrdAutoGate } from "twzrd-x402-gate";
-import { wrapFetchWithPayment } from "@x402/fetch";
+import { wrapFetchWithPayment } from "@x402/fetch"; // or @x402/svm helper
 
 // Guard RAW fetch, then hand to a client that still surfaces 402 to the guard layer
 // — OR installTwzrdAutoGate(x402Client) (canonical) / installTwzrdX402ClientHook alias.
@@ -236,15 +341,16 @@ Canonical path for every agent that spends USDC on Solana x402:
 
 **Fail-open (no invent):**
 - Preflight HTTP/network error → default fail-closed in gate 0.2+ (`TWZRD_FAIL_OPEN=true` restores legacy allow-on-outage).
-- Merchant card unreachable / non-2xx / missing `wash_flagged` → `washFlagged=null` → **do not refuse on wash** (preflight decision stands).
-- Only a successful card with `wash_flagged: true` triggers wash refuse or soft cap.
+- Merchant card unreachable / non-2xx / timeout → fail-open (do not invent wash).
+- A *returned* card with `wash_flagged: null`, missing coverage, `wash_confidence` other than `full`, `ring_evaluated: false`, or `wash_stale: true` is **unknown ≠ clean**: refuse (or configured cap). Reason `twzrd_wash_unknown` / `twzrd_wash_unknown_capped_*` — never `twzrd_wash_ok`.
 
 **Wash policy (exact):**
 - Prior preflight deny → unchanged (wash never loosens a block).
-- `refuseWashFlagged=false` or wash not true → keep preflight approval.
+- `refuseWashFlagged=false` → keep prior approval (opt out).
 - `wash_flagged=true` + no cap → `approved=false`, `reason=twzrd_wash_flagged`, `verdict=block`.
 - `wash_flagged=true` + `washMaxUsdc` set + `priceUsdc <= cap` → allow, `washCapped=true`, reason `twzrd_wash_capped_{price}_le_{cap}`.
 - `wash_flagged=true` + price above cap (or price unknown) → refuse with `twzrd_wash_flagged_above_cap_*`.
+- Adequately measured no-signal (`wash_flagged=false` and `wash_confidence=full`, with no stale or unevaluated-ring flag) → keep prior allow (`twzrd_wash_ok` on the default hook).
 
 **Order note:** `onWarnUpsell` (points at paid `/trust`) fires on preflight `warn` **before** the merchant_card wash check. A wash-flagged seller that preflighted as `warn` may still get the upsell hook, then be refused on step 2.
 
@@ -257,11 +363,13 @@ Dogfood (one public live proof path):
 ## Install
 
 ```bash
-npm install twzrd-x402-gate@0.8.18
+npm install twzrd-x402-gate@0.9.3 x402-solana@3.0.0
 ```
 
-Do not hardcode a version in this doc — every past pin here (**0.5.4**, **0.7.1**, **0.8.5**,
-**0.8.6**) has gone stale. Check `npm view twzrd-x402-gate version` if in doubt.
+Install pin is the published version (`GATE_PACKAGE_PIN` in
+`packages/twzrd-agent-intel/src/twzrd_agent_intel/pins.py`). Repo `package.json`
+may be one patch ahead until that release is on npm. Confirm with
+`npm view twzrd-x402-gate version`.
 
 Optional settle guard (resource-server **payer** policy): see **Seller settle guard
 (`onBeforeSettle`) — optional 0.8.1** above. Do not confuse with facilitator
@@ -355,15 +463,16 @@ installTwzrdX402ClientHook(client, {
 - Hook binding test:
   [`test/intent-binding.test.ts`](./test/intent-binding.test.ts).
 
-### On MPP (Machine Payments Protocol) — Solana charge only
+### On MPP (Machine Payments Protocol) — Solana and narrow Base EVM charge
 
-`createTwzrdMppOnChallenge` guards `Mppx.create({ onChallenge })`. The mppx
-Solana method signs AND broadcasts the transaction inside `createCredential()`,
-so `onChallenge` is the last deterministic checkpoint before money moves - and
-mppx re-throws `onChallenge` errors, so a TWZRD block is an exception that means
-**`createCredential()` never runs and nothing signs**. On allow, the guard
-creates the credential for the exact challenge it evaluated; non-`solana/charge`
-challenges fail closed (`allowUnevaluated: true` to opt out).
+`createTwzrdMppOnChallenge` guards `Mppx.create({ onChallenge })`. It supports
+`solana/charge` and the published native MPP `evm/charge` shape only for
+Base-mainnet native USDC (EIP-3009 authorization). `onChallenge` is the last
+deterministic checkpoint before `createCredential()` makes the credential, so a
+TWZRD block is an exception that means **`createCredential()` never runs and
+nothing signs**. On allow, the guard creates the credential for the exact
+challenge it evaluated; other methods/intents fail closed
+(`allowUnevaluated: true` is an explicit ungated opt-out).
 
 ```typescript
 import { Mppx } from "mppx/client";
@@ -379,6 +488,30 @@ const mppx = Mppx.create({
 });
 ```
 
+For Base, use mppx's EVM client with explicit local spend policy:
+
+```typescript
+import { Mppx } from "mppx/client";
+import { evm } from "mppx/evm/client";
+import { createTwzrdMppOnChallenge, createLocalDecisionSigner } from "twzrd-x402-gate";
+
+const mppx = Mppx.create({
+  methods: [evm({ account: wallet })],
+  onChallenge: createTwzrdMppOnChallenge({
+    signer: createLocalDecisionSigner(),
+    policy: {
+      allowedNetworks: ["eip155:8453"],
+      allowedAssets: ["0x833589fCD6EDb6E08f4c7C32D4f71b54bdA02913"],
+      maxAmountUsd: "1.00",
+    },
+  }),
+});
+```
+
+Base is **not reputation-scored**. The EVM path provides an actual pre-credential
+local control point for Base USDC; it does not call a Solana-derived score or
+present a local policy allow as a TWZRD trust verdict.
+
 **Scope limit (honest):** the guard is authoritative only when no
 `onChallengeReceived` event handler supplies a credential. mppx resolves
 `eventCredential ?? onChallenge(...)`, so an event handler returning a credential
@@ -394,6 +527,8 @@ fails closed rather than approve a payment it cannot bind:
 | Non-USD-pegged asset | `UNPRICED_ASSET` | Policy ceilings are USD; the wire amount is base-unit tokens. Pricing SOL would store `asset: solana:native` beside a **dollar** `amount` and lose the token quantity actually transferred. (A 1.5 SOL charge of `1500000000` at 9 decimals would otherwise evaluate as "$1.50" and sail under a $5 ceiling while moving ~$270.) USDC/USDT only until an intent version carries token amount + quote. |
 | Unknown cluster | `UNKNOWN_CLUSTER` | mppx-solana's `resolveEndpoint` returns an unrecognized `cluster` **verbatim as the RPC endpoint URL**, and a network string containing "solana" is otherwise scored as mainnet - so `solana:https://seller-rpc.example` would inherit mainnet reputation for a chain never observed. Known cluster names only. |
 | Misdeclared decimals | `MALFORMED_CHALLENGE` | A known stablecoin declaring the wrong decimals is a discount attempt, not a rounding error. |
+| Non-Base EVM chain | `UNSUPPORTED_EVM_NETWORK` | EVM MPP is narrow: Base mainnet only. A testnet or another EVM network cannot inherit a Base USDC valuation. |
+| EVM split recipients | `MULTI_LEG_CHARGE` | mppx EVM permits `splits`; each is an additional recipient. PaymentIntent v1 binds one amount to one payTo, so the guard refuses rather than approve transfers it cannot represent. |
 
 The intent binds a **digest of the entire normalized challenge**, not just
 `realm:id` - swapping `recipient` or `amount` under the same challenge id changes
@@ -446,8 +581,10 @@ Canonical entry point (design: `docs/strategy/install-autogate-design.md`). One
 | Call | Adapter |
 |------|---------|
 | `installTwzrdAutoGate(payWrap, opts?)` | Fetch: guard raw fetch → pay client |
-| `installTwzrdAutoGate(x402Client, opts?)` | Official x402 `onBeforePaymentCreation` |
+| `installTwzrdAutoGate(x402Client, opts?)` | Official `@x402/core` `onBeforePaymentCreation` |
+| `installTwzrdAutoGate("x402-solana", opts?)` | PayAI stock client `beforePayment` (2.1.0+) |
 | `installTwzrdAutoGate("mpp", opts)` | MPP `onChallenge` (returns handler) |
+| `createTwzrdBeforePaymentHook(opts?)` | Same as `"x402-solana"` — pass to `createX402Client` |
 
 Aliases: `installTwzrdX402ClientHook`, `createTwzrdMppOnChallenge` remain; docs prefer AutoGate.
 Kill switch: `TWZRD_GATE_ENABLED=false` or `TWZRD_AUTO_GATE=0`. Uninstall x402 installs with `uninstallTwzrdAutoGate(client)`.
@@ -460,7 +597,7 @@ ever gets a chance to sign.
 
 ```typescript
 import { installTwzrdAutoGate } from "twzrd-x402-gate";
-import { wrapFetchWithPayment } from "@x402/fetch";
+import { wrapFetchWithPayment } from "@x402/svm";
 
 const payingFetch = installTwzrdAutoGate((guarded) => wrapFetchWithPayment(guarded, buyerWallet));
 
@@ -511,7 +648,7 @@ manage the raw/paying composition yourself:
 
 ```typescript
 import { withTwzrdGuard } from "twzrd-x402-gate";
-import { wrapFetchWithPayment } from "@x402/fetch";
+import { wrapFetchWithPayment } from "@x402/svm";
 
 const raw = globalThis.fetch;               // MUST still surface HTTP 402
 const guarded = withTwzrdGuard(raw);        // guard sits upstream
@@ -546,15 +683,49 @@ const safeFetch = withTwzrdGuard(x402Fetch, {
 });
 ```
 
-`autoReceipt` is **off by default** — it spends the **buyer's** USDC, so you opt in. When on,
-every warn/allow verdict settles $0.05 USDC to TWZRD and returns a signed V6 trust credential
-for the counterparty before you pay the resource.
+### Path A — default on the buyer seat when a paying fetch is wired
+
+Free preflight still decides `allow|warn|block`. **Facilitator `onBeforeSettle`
+stays free** (abort on `block` only — we do not tax their rail).
+
+On the **buyer** install, if you pass `x402Fetch` (or use
+`installTwzrdAutoGate(payWrap)`, which auto-wires `payWrap(raw)`), Path A
+defaults on:
+
+| Free decision | Resource price | What fires |
+|---------------|----------------|------------|
+| `block` | any | free refuse |
+| `warn` | ≥ $2.50 | $0.05 V6 (`requireReceipt`) |
+| `warn` | < $2.50 | $0.001 quick re-decide (`escalateOnWarn`) |
+| `allow` | > $2.50 | $0.05 V6 |
+| `allow` | ≤ $2.50 | free proceed |
+
+```typescript
+import { wrapFetchWithPayment } from "@x402/svm";
+import { createTwzrdBeforePaymentHook } from "twzrd-x402-gate";
+
+const x402Fetch = wrapFetchWithPayment(fetch, buyerWallet);
+const client = createX402Client({
+  wallet: buyerWallet,
+  network: "solana",
+  beforePayment: createTwzrdBeforePaymentHook({
+    refuseWashFlagged: true,
+    x402Fetch, // turns Path A defaults on
+  }),
+});
+```
+
+Opt out: `requireReceipt: false` and/or `escalateOnWarn: false`.
+Refuse-only seats (no `x402Fetch`) stay free.
+
+`evaluate_x402_resource` itself stays opt-in. `autoReceipt: true` still buys
+$0.05 on every non-block (broader than the default ladder).
 
 **`x402Fetch` is yours to supply** (this package is dependency-free). Wire the proven
 `@x402/svm` sponsored-feePayer client — the same one `twzrd-mcp-server` uses:
 
 ```typescript
-import { wrapFetchWithPayment } from "@x402/fetch";
+import { wrapFetchWithPayment } from "@x402/svm";
 const x402Fetch = wrapFetchWithPayment(fetch, buyerWallet); // settles 402 challenges
 ```
 
@@ -746,17 +917,32 @@ const gatedFetch = wrapFetchWithTwzrdGate(fetch, resolveConfig());
 
 A payment is **blocked** when:
 1. `decision ∈ blockDecisions` (default: `["block"]`)
-2. `trust_score < preflightMinScore` (default: `40`)
+2. `trust_score < preflightMinScore` (default: `40`) — note a card with **no**
+   `trust_score` is scored `0` (`policy.ts`: `card.trust_score ?? 0`), so a
+   missing score blocks under the default floor
 3. `can_spend === false` — **only** when `gateOnCanSpend: true` (default `false`, opt-in)
+4. `merchant_card.wash_flagged === true` — **on by default**
+   (`refuseWashFlagged`, `TWZRD_REFUSE_WASH_FLAGGED`); forces `verdict: "block"`
+   with `reason: twzrd_wash_flagged`. A *returned* card with `wash_flagged: null`,
+   missing/`base_2cycle` coverage, or `ring_evaluated: false` is unknown ≠ clean
+   (`twzrd_wash_unknown`). Unreachable card still fail-opens (no invent).
+   Soft-cap instead of hard refuse with `washMaxUsdc` / `TWZRD_WASH_MAX_USDC`.
 
 `warn` is allowed unless overridden. Preflight network failure **fails closed** by default (a preflight outage blocks the payment, so an intel hiccup never silently approves a spend); set `failOpen: true` / `TWZRD_FAIL_OPEN=true` to opt into legacy allow-on-outage.
 
 A 402 whose payment requirements yield **no identifiable seller wallet** (missing/empty `payTo`, or an unparseable `accepts[]`) is a different case from "unknown seller" — it always **blocks** with `reason: twzrd_unidentifiable_payment_recipient`, without ever calling the preflight network. This is unconditional (not affected by `failOpen`): `failOpen` governs what happens when the TWZRD *service* is unreachable, not what happens when the caller can't say who they're paying.
 
 > **`can_spend` note:** the free preflight returns `can_spend=false` for most sellers
-> not yet in the TWZRD corpus, including legitimate ones. The default is decision-only
-> gating so unknown sellers on platforms like Agentic.Market are not blocked by default.
-> Set `gateOnCanSpend: true` for strict mode.
+> not yet in the TWZRD corpus, including legitimate ones. That **`can_spend` leg
+> alone** is opt-in — it is ignored unless you set `gateOnCanSpend: true` — so an
+> unknown seller on a platform like Agentic.Market is not blocked *on that basis*.
+>
+> This is **not** a blanket "unknown sellers are allowed by default". Conditions 1,
+> 2 and 4 above are all active by default, and condition 2 is the one that catches
+> unknown sellers: a card carrying no `trust_score` evaluates as `0` and blocks
+> under the default `preflightMinScore: 40` with `twzrd_score_0_below_40`. To
+> actually let unscored sellers through, lower or disable `preflightMinScore` —
+> setting `gateOnCanSpend` does not govern it.
 
 ## Config
 
@@ -767,11 +953,24 @@ A 402 whose payment requirements yield **no identifiable seller wallet** (missin
 | `blockDecisions` | `TWZRD_BLOCK_DECISIONS` | `block` | Decisions that throw |
 | `failOpen` | `TWZRD_FAIL_OPEN` | `false` | `true` opts into legacy allow-on-outage; default blocks (fail-closed) |
 | `gateOnCanSpend` | `TWZRD_GATE_ON_CAN_SPEND` | `false` | Also block when `can_spend=false` |
+| `refuseWashFlagged` | `TWZRD_REFUSE_WASH_FLAGGED` | **`true`** | Refuse when `merchant_card.wash_flagged === true` (Policy 4). Set `false` / `0` to opt out |
+| `washMaxUsdc` | `TWZRD_WASH_MAX_USDC` | — | Soft cap instead of hard refuse on wash: allow up to this USDC amount |
+| `unsupportedNetworkMode` | `TWZRD_UNSUPPORTED_NETWORK_MODE` | `observe` | Behavior on a non-Solana / unrecognized network |
+| `fetch` | — | global `fetch` | Injected fetch used for preflight + merchant card (testing / custom agents) |
+| `onWarnUpsell` | — | — | Callback fired on a `warn` verdict (Path A upsell hook) |
+| `attribution` | `TWZRD_ATTRIBUTION_INTEGRATION` + `TWZRD_ATTRIBUTION_RUN_ID` | — | Opt-in run attribution (see below) |
+
+The four options below are **not** `TwzrdGateConfig` fields — they belong to
+`TwzrdGuardOptions` / `InstallAutoGateOptions` (`withTwzrdGuard` /
+`installTwzrdAutoGate`). Passing them to `createTwzrdGate({...})` is a type error
+and is silently dropped at runtime:
+
+| Option | Env | Default | Description |
+|---|---|---|---|
 | `autoReceipt` | — | `false` | Auto-buy $0.05 TWZRD receipt on warn/allow |
 | `x402Fetch` | — | — | x402-capable fetch for `autoReceipt` |
 | `onReceipt` | — | — | Callback after receipt is captured |
 | `disabled` (`installTwzrdAutoGate` only) | `TWZRD_AUTO_GATE=0`/`false` | `false` | Bypass the guard entirely — `payWrap` gets the raw, unguarded fetch |
-| `attribution` | `TWZRD_ATTRIBUTION_INTEGRATION` + `TWZRD_ATTRIBUTION_RUN_ID` | — | Opt-in run attribution (see below) |
 
 ## Gate adoption proof (no-spend harness)
 
@@ -831,3 +1030,38 @@ whether to proceed before any USDC leaves your wallet.
 ## License
 
 MIT
+
+
+## Pay Kit before-payment hook (upstream PR pending)
+
+`solana-foundation/pay-kit#303` is open as of 2026-09-07. This adapter targets
+that PR's `onBeforeX402PaymentCreation` option; a released Pay Kit client must
+expose that option before this integration can enforce policy.
+
+```ts
+import { createPayKitClient } from "@solana/pay-kit";
+import { installTwzrdAutoGate } from "twzrd-x402-gate";
+
+const client = await createPayKitClient({
+  accept: ["x402"],
+  rpcUrl,
+  signer,
+  onBeforeX402PaymentCreation: installTwzrdAutoGate("pay-kit", {
+    refuseWashFlagged: true,
+  }),
+});
+```
+
+The adapter returns the official x402 context hook and reuses the shared
+before-payment evaluator. It adds no Pay Kit dependency. Supply it at client
+construction; passing the constructed Pay Kit client to AutoGate is unsupported.
+This hook covers x402 payment creation, not Pay Kit's MPP path.
+
+`createTwzrdPayKitBeforePaymentHook(options)` exposes the same evaluator directly.
+The AutoGate form reads environment kill switches on every call; the direct
+factory does not. Calling AutoGate installs protection by default, whereas
+ClawRouter's integration loads AutoGate only after explicit opt-in.
+
+Source-checkout verification: `npx tsx test/pay-kit-before-payment.test.ts`.
+The test covers a fake Pay Kit host and the real x402 client with a fake scheme;
+it does not establish released Pay Kit compatibility or external use.