twzrd-preflight

OpenClaw plugin 0.4.1: install = intercept. Pin twzrd-x402-gate@0.11.4 (exact; same line as other TWZRD seats).

0.4.1 moves the gate pin from 0.11.2, which npm marks deprecated, to 0.11.4. The 0.11.3 and 0.11.4 security fixes are in the gate's paying and policy fetch wrappers and its Base Worker, which this plugin does not use. The 402 wrap here already refused those cases on 0.11.2. Tests T28 and T29 pin that behaviour.

wrapFetchWithTwzrdPreflight runs TWZRD preflight + merchant_card wash refuse on every HTTP 402 before a signer can attach payment. Defaults: enforce, fail-closed, refuseWashFlagged on. Shadow / fail-open / wash-off are opt-in.

Since 0.4.0 it reads a 402 the way the payer does and checks every offer the payer could pick, matching twzrd-x402-gate@0.11.4's own wrapper:

• x402 v2 requirements are read from the PAYMENT-REQUIRED header (base64 JSON) before the body. An undecodable header is refused. 0.3.0 refused every header-only v2 402 as twzrd_unidentifiable_payment_recipient.
• Every distinct accepts[] entry must pass, not just the first. More than 8 distinct entries are refused (too_many_payment_options).
• An offer naming a non-USDC asset on Solana or Base is refused before intel (twzrd_non_usdc_asset). So is an amount that is not an ASCII base-unit integer (amount_malformed) and an offer with two different prices or recipients.
• A seller intel has never evaluated is allowed up to the card's cap (currently $0.10), per the gate's 0.11.0 policy.

Also gates payment-shaped OpenClaw tool calls (before_tool_call).

Check the seller before you pay: free ReadinessCard first, then buy a portable signed V7 trust receipt only when you need deeper evidence.

npx twzrd-preflight <wallet-or-x402-url>

Paid escalation ($0.05 signed V7 receipt)

The free card is a corpus teaser. When the decision is warn and you need the full renorm score plus a portable signed receipt, the card prints the paid route:

• GET https://intel.twzrd.xyz/v1/intel/trust/{wallet} — 0.05 USDC via x402 (Solana mainnet): full intel + signed V7 receipt (V5 and V6 receipts still verify).
• GET https://intel.twzrd.xyz/v1/intel/quick/{wallet} — 0.001 USDC quick tier: score only, no receipt.

Any x402-capable client can settle these; every free card includes the exact paid URL for the wallet it scored.

How this fits with the rest of TWZRD

This table is maintained in twzrd-trust and copied here unchanged, so every TWZRD repository describes the same pieces the same way.

Pre-spend trust for AI agents that buy: check x402 services and product listings before paying.

You are	Free	Paid
an agent about to pay an x402 seller	Readiness card (allow, warn or block), wash flags, seller reputation, offline receipt check.	$0.001 quickCheck (seller wash risk, tier and score, no receipt); optional $0.05 trust receipt, a signed V7 receipt when you pay on Solana.
an agent about to buy a product from a store	check_listing(product_url, declared_unit_price) against a published listing card, and the Agent Shopping Check report.	Optional $0.001 checkout brief for a buyer-approved Shop Pay checkout.

Each piece below works alone. Plugged into the hosted checks, they form one pre-spend path.

Piece	On its own	Plugged in	Install
Hosted checks	Free checks with nothing to install: is this x402 seller safe to pay, and does this store listing match a published card.	The pieces below that screen a payment call it; it is where the decisions and the signed receipts come from. The receipt verifier needs no server.	Add https://intel.twzrd.xyz/mcp to an MCP client
twzrd-x402-gate	Wraps an x402 client's pay path: asks the hosted checks about the seller before your signer runs, refuses a block (the signer is never invoked), enforces a spend cap, and can issue a twzrd.payment_decision.v1 record from its decision, signed with your own signer.	Decisions come from the hosted checks; pairs with x402-solana or @x402/fetch as the payer.	npm install twzrd-x402-gate
twzrd-preflight	OpenClaw plugin: assign its wrapped fetch to the client and every 402 that passes through it is checked before a signer can attach payment (enforce and fail-closed by default).	Matches the gate's wrapper and adds OpenClaw tool-call gating, against the hosted checks. Payments outside the wrapped fetch (a ClawRouter proxy, unparsed exec or curl) are not covered.	npm install twzrd-preflight
twzrd-receipt-verifier	Verifies a TWZRD receipt offline against a published Ed25519 key: no wallet, no API key, no trust in TWZRD's server.	Checks the signed receipts that the hosted checks issue.	npx twzrd-receipt-verifier or pip install twzrd-receipt-verifier
twzrd-mcp-server / twzrd-mcp	A local MCP client with 6 tools that pays the $0.001 and $0.05 calls itself under a spend cap (a wallet only if you enable paid calls).	Calls the hosted checks; use the hosted MCP directly for the free checks.	npx -y twzrd-mcp-server or pip install twzrd-mcp
@wzrd_sol/plugin-trustgate, @wzrd_sol/eliza-plugin	Framework seats: a settle hook for facilitators (see docs), a Faremeter payer chooser, and elizaOS actions.	Each seat calls the hosted checks from inside its framework.	npm install @wzrd_sol/plugin-trustgate
twzrd-agent-intel	The server package behind the hosted checks. Run it yourself behind a firewall; a local run serves a small static snapshot, not live data.	Point a self-hosted instance at live data with its environment variables.	pip install twzrd-agent-intel, then twzrd-agent-intel-mcp
Seller starters: x402-solana-starter, x402-seller-starter	Cloudflare Worker templates for selling a paid API to agents over x402: x402-solana-starter is the production-style Solana storefront (x402 v2), x402-seller-starter a minimal wedge.	Both default to the TWZRD facilitator. x402-solana-starter also runs a settle guard, advisory and fail-open, that screens payers through the hosted checks.	Deploy button in each repo

Put them together

• Refuse before signing: gate (or preflight) + hosted checks. A blocked seller never reaches your signer. Prove it with no wallet and no spend: curl -fsS https://intel.twzrd.xyz/v1/intel/demo-gate.
• Keep proof of what you paid for: paid trust receipt + receipt verifier. A signed receipt you or anyone else can verify offline.
• Check a listing before you buy: check_listing + your human approval step. A price above the card is refused; a price below it, or a card with no price, asks a human. Optionally add the paid checkout brief.
• Screen every settlement you broker: plugin-trustgate settle hook + hosted checks. A facilitator aborts a settle to a blocked seller before the transfer.

What TWZRD does not claim

• TWZRD scores observed wallet and payment behavior. It does not prove a person, company, or agent identity.
• A listing card is an observer card, not a merchant attestation. Advertised means a captured page said it; purchase completion and delivery are not verified.
• authorizes_spend is always false: a check is evidence for your own spend policy, never permission to spend.
• Not a wallet. Not a payment network.

Install

npm install twzrd-preflight
# depends on twzrd-x402-gate@0.11.4 (exact)

Register in your OpenClaw config:

{
  "plugins": ["twzrd-preflight"]
}

HTTP 402 wrap (OpenClaw has no global-fetch hook — assign this on the client's fetch):

import { wrapFetchWithTwzrdPreflight } from "twzrd-preflight";
const fetch = wrapFetchWithTwzrdPreflight(globalThis.fetch);

A wash-flagged payTo throws TwzrdPaymentBlockedError with error.refuse.schema === "twzrd.gate_eval_refuse.v1" (signer_invocation_count: 0, usdc_spent: 0, closes_external_adoption_metric: false). Mechanism / harness proof, not an EXTERNAL_RUN. No invented ALLOW txs.

Configuration

Key	Default	Description
mode	"enforce"	off / shadow (opt-in log-only) / enforce
failMode	"closed"	closed (block on intel outage) or open (opt-in allow)
refuseWashFlagged	true	Refuse when merchant_card.wash_flagged; opt out with false
timeoutMs	5000	Preflight HTTP timeout in ms
maxPriceUsdc	null	Local price ceiling — blocks above this USDC amount without API call
endpoint	"https://intel.twzrd.xyz"	TWZRD intel API base URL
allowWallets	[]	Always-allow seller wallet addresses (no API call)
denyWallets	[]	Always-block seller wallet addresses (no API call)
cacheTtlMs	3600000	TTL for per-seller decision and 402 origin cache (1 hour)
matchers	[]	Custom tool matchers for coverage beyond built-in rails

Example opt-in (legacy shadow / fail-open / wash-off):

{
  "plugins": [
    {
      "name": "twzrd-preflight",
      "config": {
        "mode": "shadow",
        "failMode": "open",
        "refuseWashFlagged": false
      }
    }
  ]
}

Custom matchers

Built-in coverage: AgentCash MCP tools + exec/curl x402 payments. For other payment tools:

{
  "matchers": [
    {
      "tool": "payment_send",
      "walletParam": "recipient",
      "priceParam": "amount_usdc",
      "resourceParam": "memo"
    }
  ]
}

Key	Required	Description
tool	yes	Tool name substring to match (case-insensitive)
walletParam	no	Param key whose value is the seller wallet (Solana base58)
urlParam	no	Param key whose value is a URL; origin used as resource_url
priceParam	no	Param key for payment amount in USDC
resourceParam	no	Param key for a human-readable resource name

What it covers (honest)

• MCP payment tools (AgentCash fetch/bridge style): counterparty = origin/url param, upgraded to the real Solana payTo wallet once a 402 envelope has been observed (after_tool_call cache).
• exec/curl x402 payments: conservative regex extraction of seller_wallet/payTo/ price_usdc/resource_name from the command string. Failed parse = no gate (never blocks on extraction bugs).
• Custom matchers: operator-defined tool + param mappings for any other payment rail.
• NOT covered: ClawRouter proxy settlements (sign inside localhost:8402, invisible to tool hooks — needs ClawRouter's upstream onBeforePayment hook).

Gate rules

• Block iff decision === "block". Never gates on can_spend (unknown wallets score warn/45, which is allowed by default).
• shadow mode: evaluates + logs would-blocks, never blocks.
• Fail-closed by default: trust API unreachable = block (failMode: "open" is opt-in allow).
• Local policy (denylist, allowlist, price cap) runs without any API call.
• Loop guard: calls to the trust API itself are never gated.

Privacy

In shadow and enforce modes, payment-shaped tool metadata is sent to intel.twzrd.xyz: seller wallet, origin, price, resource name, and an agent_intent marker. No payload content or full params are forwarded. The endpoint is configurable.

Test

npm test    # 38 passed (live FREE preflight + injected 402 / 0.11.4 API smoke + conflict, card-outage, v2 header, every-offer, asset cases; no auth, no payments)

Verified against OpenClaw 2026.7.1-2 (openclaw.build.openclawVersion + T10c). Gate pin: twzrd-x402-gate@0.11.4. Refuse-bin spawn without @x402/* peers is a missing-peer fail (exit 2), not a live dogfood EXTERNAL_RUN.

CLI

npx twzrd-preflight <solana-wallet-or-x402-url>
npx twzrd-preflight <wallet> --json
npx twzrd-preflight <url> --strict

Exits 0 on allow/warn, 1 on block. Useful for scripts and one-off checks. Sends the same X-Twzrd-Caller header.

Attribution

All preflight calls (plugin and CLI) now include:

X-Twzrd-Caller: twzrd-preflight/<version>

This lets the intel surface attribute seats and free-card usage back to this integration for scoreboard / distribution tracking.