twzrd-trust

# TWZRD

**Don't let your agent sign blind.**  
Pre-spend trust for agents that buy: the x402 service they are about to pay (Solana, and Base) and the product listing they are about to buy from.

- **x402 services:** vet the seller **before** USDC leaves the wallet, cap and ledger every spend, and bind each settled payment to the exact offer it paid for (**bind-v1** — verifiable from public chain data). Advisory preflight is free ($0). The paid `quickCheck` is **$0.001** (seller wash risk, tier and score; no receipt). Separately, the gate can issue a portable `twzrd.payment_decision.v1` record from its own decision, signed locally with your own signer.
- **Product listings:** a free check of a store product URL and its asking price against a card TWZRD published from the store's public pages. The card is an observer card, not a merchant attestation, and a match is never permission to spend ([details](#product-listings-check-the-listing-before-you-buy)).

Not a wallet. Not a payment network. Not Catena's Agent Commerce Kit — the walkthrough lives in [docs/COMMERCE-KIT.md](./docs/COMMERCE-KIT.md).

**Canonical skill (always refresh)** • https://intel.twzrd.xyz/skill.md (skill `twzrd-trust`; the live copy carries its version) · [ClawHub `twzrd-trust`](https://clawhub.ai)  
**Spend-control SDK (npm)** • [`twzrd-x402-gate@0.11.2`](https://www.npmjs.com/package/twzrd-x402-gate) + seat [`x402-solana@3.0.0`](https://www.npmjs.com/package/x402-solana)  
**Live MCP** • https://intel.twzrd.xyz/mcp (streamable HTTP; free tools for x402 service checks and product-listing checks)  
**Shopping check** • free `check_listing` on the hosted MCP · report: https://twzrd.xyz/shopping-check/vuori-kore/  
**Agent contract** • https://intel.twzrd.xyz/llms.txt · https://intel.twzrd.xyz/.well-known/agent.json

---

## 60-second deterministic free demo

Run this one-line command with **no wallet, no API key, and no configuration**:

```bash
curl -fsS https://intel.twzrd.xyz/v1/intel/demo-gate | jq '{verdict: (.steps[] | select(.name == "block_path") | .verdict), approved: (.steps[] | select(.name == "block_path") | .approved), signerInvocations: (.steps[] | select(.name == "block_path") | .signer_invocations), mode, ok}'
```

Without `jq`, run: `curl -fsS https://intel.twzrd.xyz/v1/intel/demo-gate`

Expected output:
```json
{
  "verdict": "block",
  "approved": false,
  "signerInvocations": 0,
  "mode": "no_spend",
  "ok": true
}
```

*Blocks happen before your signer is invoked (`signerInvocations: 0`) — zero USDC at risk.*

---

## How the pieces fit

<!-- twzrd:ecosystem:begin (generated by scripts/render-ecosystem.mjs from docs/ecosystem.json; edit that file) -->
**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](https://intel.twzrd.xyz/llms.txt) | 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`](https://www.npmjs.com/package/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`](https://github.com/twzrd-sol/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`](https://github.com/twzrd-sol/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`](https://www.npmjs.com/package/twzrd-mcp-server) / [`twzrd-mcp`](https://pypi.org/project/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`](https://www.npmjs.com/package/@wzrd_sol/plugin-trustgate), [`@wzrd_sol/eliza-plugin`](https://www.npmjs.com/package/@wzrd_sol/eliza-plugin) | Framework seats: a settle hook for facilitators (see [docs](https://github.com/twzrd-sol/twzrd-trust/blob/main/docs/facilitator-trust-in-3-lines.md)), 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`](https://pypi.org/project/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`](https://github.com/twzrd-sol/x402-solana-starter), [`x402-seller-starter`](https://github.com/twzrd-sol/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.
<!-- twzrd:ecosystem:end -->

More: [docs/ECOSYSTEM.md](./docs/ECOSYSTEM.md).

---

## From this repo

This checkout is a public monorepo, not `npm install twzrd-x402-gate`. CI is
root `npm ci` then `npm run ci` (Node 20). Do **not** `npm ci` inside
`twzrd-x402-gate/` — gate typecheck needs sibling `twzrd-log-verifier` deps
from the root lockfile.

```bash
npm ci
npm run build
npm run typecheck
npm test --workspace=twzrd-x402-gate
npm run gate-eval-refuse --workspace=twzrd-x402-gate
```

`gate-eval-refuse` is the hello-world that closes (0 USDC, `signer_invocation_count: 0`).
It needs egress to `https://intel.twzrd.xyz`. Artifact dirs (`eliza-plugin/`,
`plugin-trustgate/`, `twzrd-mcp-server/`) are `dist/` mirrors — do not try to
build or demo them locally. Hosted MCP: `https://intel.twzrd.xyz/mcp`.

---

## Quickstart

### 1. Install

```bash
npm install twzrd-x402-gate@0.11.2 x402-solana@3.0.0
```

### 2. Wrap paid fetches with spend controls

```ts
import { twzrd } from "twzrd-x402-gate";

const result = await twzrd.safeFetch("https://merchant.example/paid-endpoint", {
  maxSpend: "0.10",            // per-call cap AND cumulative budget in USD
  allowNetworks: ["solana"],   // allowed settlement networks
  requireOfferBinding: true,   // demand an on-chain verifiable bind-v1 receipt
  pay: async ({ url, paymentRequired, selected }) => {
    // Your existing x402 client signs here — e.g. @x402/fetch + your signer
    return await myWallet.payX402(url, paymentRequired, selected);
  },
});

// On block: result.verdict === "block", result.signerInvocations === 0
```

### 3. Or hook an existing client

```ts
import { createX402Client } from "x402-solana";
import { createTwzrdBeforePaymentHook } from "twzrd-x402-gate";

const client = createX402Client({
  wallet,
  network: "solana",
  beforePayment: createTwzrdBeforePaymentHook({ refuseWashFlagge