# TWZRD is the pre-spend trust gate + receipt layer for agents that buy: x402 services and product listings

> Two lanes, one rule: check before you spend. Nothing here authorizes spending.
> - **x402 services** (the seller + resource you are about to pay): preflight,
>   `get_merchant_card`, `evaluate_x402_resource`, signed V7 receipts. Detail below.
> - **Product listings** (the product you are about to buy from a store): the free MCP
>   tool `check_listing(product_url, declared_unit_price?)` checks it against TWZRD's
>   only listing-claim card, Vuori Kore Short: a price above the advertised one is refused, one below
>   it or no advertised price sets `needs_approval`. Verify offline with `get_claim`,
>   `get_evidence`, `get_publication` (Ed25519-signed publication record). Report: `get_shopping_check` / https://twzrd.xyz/shopping-check/vuori-kore/.
>   Paid `GET /v1/intel/checkout-brief` ($0.001) binds your cart_hash. Purchase completion and delivery are not verified.

> Primary settlement rail: **Solana**. Free read-only scoring also covers **Base**
> (EIP-3009 USDC). /quick (no receipt) and /trust take a Solana subject wallet only;
> both settle on Solana or Base and /trust issues its V7 receipt on either rail.
> Each 402 challenge is authoritative for network, asset, amount and payTo; select a
> complete accepts[] entry.

> TWZRD is a pre-sign risk-policy layer for x402 payments: observed settlement
> reputation feeds `allow | warn | block` before the wallet signs.
> First paid hop is /quick at 0.001 USDC; optional V7 /trust at 0.05.
> It does not verify identity, and it is not a payment gateway or a way to move funds.
>
> TWZRD answers: should this agent pay this seller? It does not fight
> CAPTCHAs. Access friction is a different product. Free preflight is
> advisory. Cryptography is the signed receipt, not the HTTP card.

## Core product: buyer gate (install before any x402 client signs)

Install the gate in your x402 client so a `block` verdict refuses the payment
before your wallet ever signs - the refusal itself is the product working.
Primary seat: `twzrd-x402-gate@0.12.5` + `x402-solana@3.0.1`. Hook runs after
requirement selection, before `signTransaction`. Path B success = refuse
transcript (`signer_invocation_count=0`), not `day0.gate_evals` or free_card_hits.

```bash
npm install twzrd-x402-gate@0.12.5 x402-solana@3.0.1
# Prove refuse-before-sign. The gate's OPTIONAL peers are not auto-installed by
# npm, so on a cold machine run the full line first:
#   npm install twzrd-x402-gate@0.12.5 x402-solana@3.0.1 @x402/core @x402/fetch @x402/svm @solana/kit @scure/base
# node node_modules/twzrd-x402-gate/bin/twzrd-gate-eval-refuse.js
```

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

const client = createX402Client({
  wallet,
  network: "solana",
  beforePayment: createTwzrdBeforePaymentHook({ refuseWashFlagged: true }),
});
// Alt: installTwzrdAutoGate("x402-solana", opts) or twzrd.safeFetch(url, opts).
// One-call: npm install twzrd-x402-gate then
// twzrd.safeFetch("https://intel.twzrd.xyz/v1/intel/refuse-fixture", { maxSpend: "0.05" })
// policy block -> signerInvocations: 0. Path A defaults ON only when x402Fetch is wired (payWrap):
//   warn >= $2.50 or allow > $2.50 -> $0.05 V7 (requireReceipt)
//   sub-material warn -> $0.001 (escalateOnWarn). Refuse-only seats stay free.
```

Free HTTP/MCP preflight is **advisory** until this gate (or equivalent) is
installed and the host honors the decision. Optional paid V7 receipts buy
portable proof only — they do not enforce. Preflight does NOT block settlement
by itself.

### Decision semantics (allow | warn | block)

```bash
curl -sS -X POST https://intel.twzrd.xyz/v1/intel/preflight \
  -H 'content-type: application/json' \
  -d '{"seller_wallet":"GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs","price_usdc":0.01,"agent_intent":"preflight"}'
```

- `block`: do not pay. (Verdict is at `readiness_card.decision`.)
- `warn`: thin/unknown history; proceed deliberately or buy portable proof.
- `allow`: evidence supports a small spend; not a guarantee or identity claim.
- `wash_flagged=true` hard-stops: preflight `block`, merchant_card `refuse`.
  Never warn / allow / quick. `null` = never evaluated, not clean.

Refuse / preflight honesty (match live code):
- `price_kind` with price (`exact` | `upto_cap` | `unknown`) + `max_price_usdc`.
  `upto_cap` is a cap, not a unit price. Read `price_kind` or
  `quotedUnitPriceFromCard`. Unlabeled leftover `0.05` is not a unit price;
  omit leftover `price_usdc` on replay curl. Caller-supplied / `exact` 0.05 stays.
- Milestone status: `proven` | `held` | `needs_human`. Surfaces cannot claim proven when held or needs_human.

`twzrd_demo_gate` is a deterministic no-spend transcript, a recorded example,
not a live run: block aborts before any signer; allow proceeds but still spends
nothing. Caller-supplied attribution is
an `external_candidate`, never proof of an external run.

### Fixtures (do not confuse roles)

| Role | Fixture |
|------|---------|
| REFUSE dogfood (owned) | `GET /v1/intel/refuse-fixture` · payTo `CnTmHDXV…` (owned) (synthetic hard refuse; not a third-party brand) |
| WARN control | minifetch `https://minifetch.com/api/v1/x402/extract/url-preview?url=https://github.com` · `46vMcwuC…` |
| Wash education only (not hero allow) | `BJGdsDXJFy63eCAnX3UmGfShp8BuqbtkTfcamyRGr7VQ` |

### Live paid inference (api.twzrd.xyz)

`POST https://api.twzrd.xyz/v1/chat/completions` is the live OpenAI-compatible x402 SKU
(0.01 USDC on Solana, payTo `DB2s5PeotN1zwb9WpLQMAYqdHnf86SfjYUhbe1Nm8D1e`).
This intel origin lists it on `/.well-known/x402` and `/openapi.json` (servers
override). `POST /v1/compute/inference` here is receipt-gated and is not that SKU.

## Where TWZRD fits in your payment path

| Stage | Call | Result |
|---|---|---|
| Before | `POST /v1/intel/preflight` | free advisory ReadinessCard |
| Before | `get_readiness_card_tool` | free MCP `decision` at top level |
| Before | `GET /v1/intel/merchant_card/GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs` | seller graph, wash, catalog, payable conformance |
| During | buyer gate at `onBeforePaymentCreation` / `beforePayment` | block aborts before wallet signing |
| First paid hop | `GET /v1/intel/quick/GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs` | 0.001 USDC, score-only teaser (Path A) |
| After (optional) | `GET /v1/intel/trust/GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs` | 0.05 USDC, signed V7 receipt (Path A) |
| After | `POST /v1/receipts/verify` | free offline verification of V7 receipts (earlier V5 and V6 receipts still verify) |

Refuse-receipt: caller's own local deny, not a TWZRD wash verdict. Replay 90 days.

A pasted `:pubkey`/`{pubkey}` now 402s the example wallet. That example is
TWZRD own-wallet smoke. Substitute a real seller payTo to score someone else:
`GET https://intel.twzrd.xyz/v1/intel/merchant_card/GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs`

## Supporting surfaces

Optional / secondary. Buyer-gate install is the wedge; these feed preflight,
attach proof, or expose discovery.

### Discovery inputs (BEFORE paying, optional)

Seller-first path when you need more than a wallet string:
1. `GET /v1/intel/resources` — resource join SOT (listed|live_402 ≠ settlement trust).
2. URL: `evaluate_x402_resource`. Ingested overlay: `get_x402_directory` / `GET /v1/intel/x402-directory`.
3. `get_merchant_card` — wash_flagged=true hard-stop (refuse); inspect `payable_conformance` + `next_action`.
4. Preflight (above) → honor decision → gate on pay path → optional Path A V7.

Discovery entry points (drive free preflights):
- Skill: https://intel.twzrd.xyz/skill.md
- Resources SOT: GET https://intel.twzrd.xyz/v1/intel/resources
- TWZRD Bazaar catalog: GET https://intel.twzrd.xyz/v1/intel/bazaar/offers (seller-published callables; unpaid preflight)
- Overlay (not a bazaar): GET https://intel.twzrd.xyz/v1/intel/marketplace · /v1/intel/x402-directory
- 402 `extensions.bazaar` is routeTemplate metadata, not the catalog.

The settlement graph is not a service catalog. Payer leaderboards are secondary
research. Polygon wash=unknown (no corpus ingest).
Free merchant card: `GET /v1/intel/merchant_card/GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs`.

### Zero-install MCP (recommended)

Skill: "set up https://intel.twzrd.xyz/skill.md" (or `npx clawhub install twzrd-trust`).
Hosted MCP: `https://intel.twzrd.xyz/mcp` (28 free tools; dual Accept).

```json
{"mcpServers":{"twzrd-agent-intel":{"url":"https://intel.twzrd.xyz/mcp"}}}
```

```bash
openclaw mcp add twzrd --url https://intel.twzrd.xyz/mcp --transport streamable-http
```

Local auto-pay MCP is optional: `npx -y twzrd-mcp-server`. Payments stay off
unless the operator sets explicit opt-in and caps:

```json
{"mcpServers":{"twzrd":{"command":"npx","args":["-y","twzrd-mcp-server"],"env":{"TWZRD_MCP_PAYMENTS_ENABLED":"1","TWZRD_RPC_URL":"<mainnet rpc>","TWZRD_WALLET_SECRET_KEY":"<base58 secret>","TWZRD_MAX_USDC_PER_CALL":"0.05","TWZRD_MAX_USDC_TOTAL":"1.00"}}}}
```

### Path A paid proof (not enforcement)

Optional paid V7 receipts buy portable proof only — they do not enforce.
The paste-ready `GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs` path is TWZRD's own payTo (own-wallet smoke).
Before a real pay, put the seller's accepts[].payTo in the path and inspect the
selected entry's network, asset, amount, and payTo before signing.

Unpaid GET on a paid route returns HTTP 402 with `next_action` in the JSON body.
Optional Path A curl examples: /llms-full.txt.

- `GET https://intel.twzrd.xyz/v1/intel/quick/GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs` — 0.001 USDC. First paid hop. No V7 receipt.
- `GET https://intel.twzrd.xyz/v1/intel/trust/GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs?seller_wallet=GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs` — 0.05 USDC. Optional portable V7.
- `GET https://intel.twzrd.xyz/v1/intel/merchant/GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs` — 0.05 USDC.
- `GET /v1/intel/reality-check` — 0.05 USDC Reality Check PDF.
- `POST /v1/intel/verify-endpoint` — 0.05 USDC. Body `{"url"}`. not_a_trust_vouch; not_ready still charged. Free unsigned: `POST /v1/agent-readiness`.
- `POST /v1/intel/read-page` - 0.005 USDC, provider observation.
- `POST /v1/intel/delivery-watch` - records a watch. Does not pay your resource.
- `GET /v1/intel/checkout-brief?product=&cart_hash=&declared_unit_price=` - 0.001 USDC. Does not open checkout.

`seller_wallet=` or `X-TWZRD-Seller-Wallet` identifies the settle-gate counterparty
on trust routes; market routes use `merchant=`. Omit them and the gate cannot evaluate. x402 v2: unpaid → `payment-required`; sign an `accepts` entry; retry
with `payment-signature`. Payer holds USDC; fee payer sponsors gas only.

### Market-data discovery

Temporarily unlisted: no market-data upstream is configured. The market
routes answer HTTP 410 Gone, 404 for not_found (never cached fake data),
and the `get_solana_market_status` MCP tool reports `available: false`.

### Settle rail (opt-in facilitator — not Path B)

`GET /supported` → pin `kinds[].extra.feePayer` (currently `GWRLgRB6diC2zG9BaoGJsan9T8JvJCk7usFruiefnfMP`).
Do not copy a card pubkey. `/health.fee_payer` is Path A. Then `POST /verify` +
`/settle` (gas cosign + V7). Read `settle_gate_enforcing` on `/health` (shadow
logs a would-block and still settles). Path B = buyer AutoGate refuse.

### Free HTTP catalog

- `GET /v1/intel/resources` · `GET /v1/intel/bazaar/offers` · `GET /v1/intel/x402-directory` · `GET /v1/intel/marketplace`
- `POST /v1/intel/preflight` · `GET /v1/intel/merchant_card/GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs` · `GET /v1/intel/score_wallet_for_intel?wallet=GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs`
- Free graph: `GET /v1/intel/sellers` · `get_counterparties` · `get_facilitator_footprint` · `compare_wallets` · `GET /v1/intel/badge/GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs`

### Receipt and re-call contract

V7 (current issuance; V5/V6 still verify) = keccak256 leaf + Ed25519 over the
leaf bytes. Verify offline with
`npx twzrd-receipt-verifier@^1.4.0 receipt.json --pubkey Ak5SQwHpuQAqU7ty7ZWX7qgF39A9yi72c22KNn8sHzvS` or
`POST /v1/receipts/verify`. Freshness
(`recheck_after_unix`, `staleness_days`, `score_decay_model`): leaf-bound on V7
(edits fail verification, `unauthenticated_fields` empty); unbound and listed
there on V5/V6. `evaluateRecall` gates re-calls (`untrusted-recheck` on V5/V6).
Never treat `recheck_after_unix` / `due` as a trusted allow. Stale ≠ invalid.
Watch lane: `twzrd_watch_add` / `POST /v1/intel/watch` (twzrd-watch/v1 control proof) re-check when due and POST `twzrd.watch.recheck_due` on change; detail on /llms-full.txt.

### Trust gate semantics (twzrd-agent-intel service v0.5.13)

- Service package, npm buyer gate, and framework plugins version independently.
- Preflight does NOT block settlement; an installed client hook must honor the decision.
- With `TWZRD_SETTLE_GATE_ENABLED=true` and not shadow (`settle_gate_enforcing`
  on `GET /health`), paid routes can refuse settlement before broadcast if the
  explicit seller scores below policy; shadow mode logs only.
- MCP tools are free. Paid prices above apply to direct HTTP routes.
- Registry ownership key `/.well-known/mcp-registry-auth` is NOT the receipt-signing key.

### Framework adapters (secondary to buyer gate)

```bash
npm install @wzrd_sol/plugin-trustgate@^0.3.7
```

For elizaOS or facilitator operators, use the package's `onBeforeSettle` adapter.
For resource servers, the optional merchant policy screens the payer before
settlement and service; it is secondary to the buyer-side gate:

```ts
import { createTwzrdSettleGuard, twzrdPayerScreen } from "twzrd-x402-gate";
server.onBeforeSettle(createTwzrdSettleGuard({ screen: twzrdPayerScreen() }));
```

## Docs

- [Resource join SOT](https://intel.twzrd.xyz/v1/intel/resources): free inventory of callables (listed|live_402; settlement overlay separate)
- [Preflight](https://intel.twzrd.xyz/v1/intel/preflight): free allow/warn/block check before payment
- [Merchant card](https://intel.twzrd.xyz/v1/intel/merchant_card/GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs): observed seller graph, wash and payable conformance
- [Trust receipt](https://intel.twzrd.xyz/v1/intel/trust/GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs): paid live intel plus signed V7 receipt
- [TWZRD Bazaar](https://intel.twzrd.xyz/v1/intel/bazaar/offers): seller-published callables (not marketplace, not 402 extensions.bazaar)
- [x402 directory](https://intel.twzrd.xyz/v1/intel/x402-directory): wash overlay on ingested listings (not the settlement graph as catalog)
- [Receipt example](https://intel.twzrd.xyz/v1/receipts/example): explicitly sample-only signed receipt
- [Receipt verify](https://intel.twzrd.xyz/v1/receipts/verify): recompute leaf and verify Ed25519 signature
- [OpenAPI](https://intel.twzrd.xyz/openapi.json): canonical HTTP schemas and x402 annotations
- free `get_claim`, `get_evidence`, `get_publication`, no payment: `twzrd://claims/vuori-kore`
- [MCP](https://intel.twzrd.xyz/mcp): hosted Streamable HTTP server with 28 tools
- [Muse connector](https://intel.twzrd.xyz/muse/mcp): six read-only tools, separate from /mcp.
- [MCP card](https://intel.twzrd.xyz/.well-known/mcp.json): transport, install and exact declared tools
- [Full reference](https://intel.twzrd.xyz/llms-full.txt): complete tool catalog, policies and examples
- [Smithery](https://smithery.ai/servers/wzrd/twzrd-agent-intel): existing hosted marketplace listing
- [Public source](https://github.com/twzrd-sol/twzrd-trust): public packages and integration source

## Optional

- [Health](https://intel.twzrd.xyz/health): current package version, network and catalog counts
- [Agent card](https://intel.twzrd.xyz/.well-known/agent-card.json): A2A and MCP discovery
- [x402 descriptor](https://intel.twzrd.xyz/.well-known/x402): current paid/free resource metadata