# TWZRD is the pre-spend trust gate + receipt layer for agents paying over x402

> Primary settlement rail: **Solana**. Free read-only scoring also covers **Base**
> (EIP-3009 USDC settlements, high-confidence bucket). Paid V6 receipts remain
> Solana-settlement only.

> TWZRD is a pre-sign risk-policy layer for x402 payments: observed settlement
> reputation feeds `allow | warn | block` before the wallet signs; optional signed
> V6 proof is available after a paid trust call. It does not verify identity, and
> it is not a payment gateway or a way to move funds.

## 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.8.14` + `x402-solana@2.1.0`. 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.8.14 x402-solana@2.1.0
# 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.8.14 x402-solana@2.1.0 @x402/core @x402/fetch @x402/svm @solana/kit @scure/base
# node node_modules/twzrd-x402-gate/bin/twzrd-gate-eval-refuse.js
#
# (There is no examples/ directory inside the published package - its `files`
# array ships only dist, bin, README and QUICKSTART. bin/ is the proof path.)
```

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

const client = createX402Client({
  wallet,
  network: "solana",
  beforePayment: createTwzrdBeforePaymentHook({ refuseWashFlagged: true }),
});
// Alt: installTwzrdAutoGate("x402-solana", opts) — same hook.
// Path E: installTwzrdAutoGate(x402CoreClient) for @x402/core onBeforePaymentCreation.
// Also: installTwzrdAutoGate(payWrap) / installTwzrdAutoGate("mpp", opts)
```

Free HTTP/MCP preflight is **advisory** until this gate (or equivalent) is
installed and the host honors the decision. Optional paid V6 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.

`twzrd_demo_gate` is a deterministic no-spend proof: 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` |

## 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/{wallet}` | seller graph, wash, catalog, payable conformance |
| During | buyer gate at `onBeforePaymentCreation` / `beforePayment` | block aborts before wallet signing |
| After (optional) | `GET /v1/intel/trust/{pubkey}` | 0.05 USDC, signed V6 receipt (Path A) |
| After | `POST /v1/receipts/verify` | free offline receipt verification |

## Supporting surfaces

Everything below is optional or secondary. Agents that only install the buyer
gate already have the core product. These surfaces feed preflight, attach proof,
or expose discovery — they are not the wedge.

### 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`. Multi-bazaar: `get_x402_directory` / `GET /v1/intel/x402-directory`.
3. `get_merchant_card` — refuse hard wash; inspect `payable_conformance` + `next_action`.
4. Preflight (above) → honor decision → gate on pay path → optional Path A V6.

Discovery entry points (drive free preflights):
- Skill: https://intel.twzrd.xyz/skill.md
- Resources SOT: GET https://intel.twzrd.xyz/v1/intel/resources
- Marketplace: GET https://intel.twzrd.xyz/v1/intel/marketplace

Services come from bazaar / resource-join discovery; settlement trust enriches
`pay_to`. The settlement graph is not a service catalog. Payer leaderboards are
secondary research. Observed payer wallets are not TWZRD customers, revenue, or
proof every wallet is an autonomous agent. Polygon rows are wash=unknown (no
corpus ingest). Free merchant card: `GET /v1/intel/merchant_card/{wallet}`.

### 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` (24 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
```

No wallet • No signup • Free preflight • Pay only for signed V6 trust receipt.

Local auto-pay MCP is optional: `pip install twzrd-mcp` or
`npx -y twzrd-mcp-server`. Payments are disabled unless the operator explicitly
sets `TWZRD_MCP_PAYMENTS_ENABLED=1` and local 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 V6 receipts buy portable proof only — they do not enforce.

```bash
curl -sS -X POST https://intel.twzrd.xyz/v1/intel/preflight \
  -H 'content-type: application/json' \
  -d '{"seller_wallet":"46vMcwuC4sK11sB3gkLhyA7J7GEwfkhn5rFyDtihBwqe","price_usdc":0.002}'
# Optional portable receipt (0.05 USDC) — does not install a gate
npx agentcash@latest fetch \
  'https://intel.twzrd.xyz/v1/intel/trust/46vMcwuC4sK11sB3gkLhyA7J7GEwfkhn5rFyDtihBwqe?seller_wallet=46vMcwuC4sK11sB3gkLhyA7J7GEwfkhn5rFyDtihBwqe'
```

Unpaid GET on a paid route returns HTTP 402 with `next_action` in the JSON body.

- `GET /v1/intel/trust/GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs?seller_wallet=GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs` — 0.05 USDC.
- `GET /v1/intel/merchant/{pubkey}` — 0.05 USDC merchant track-record receipt.
- `GET /v1/intel/quick/{pubkey}` — 0.001 USDC teaser, no full receipt.
- `POST /v1/intel/verify-endpoint` — 0.05 USDC. Seller-side signed endpoint verification. Body `{"url": "https://your-api.example"}`. Returns readiness card + Ed25519 AgentReadinessReceipt (basis=endpoint_conformance, not_a_trust_vouch=true). A `not_ready` verdict is still charged. Free unsigned: `POST /v1/agent-readiness`.

`seller_wallet=` or `X-TWZRD-Seller-Wallet` identifies the settle-gate counterparty
on trust routes; market routes use `merchant=`. Omit them and the gate has nothing
to 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 (free HTTP; not the trust wedge)

- `GET /v1/intel/solana_market_visibility_map?merchant=GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs`
- `GET /v1/intel/solana_market_orderbook_depth?ticker=BTC&merchant=GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs`
- `GET /v1/intel/solana_market_shape?ticker=BTC&merchant=GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs`
- `GET /v1/intel/solana_market_onchain_trades_summary?merchant=GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs`

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

`GET /supported` (feePayer `4LkEFjJdXARkKx8FBx4LBFa2SvJNmjQpgGDLoJcypZUE`) →
`POST /verify` + `/settle`: gas cosign + best-effort V6 attach (not settle_gate
firewall). Self-facilitated settle on Solana when `/health` shows
`self_facilitate: true`. Path B = buyer AutoGate refuse. Path A paid 402s may
still list external feePayers (CDP / PayAI / Dexter). Pin `extra.feePayer` from
`/supported` for settle + trust memory in one hop.

### Free HTTP catalog

- `GET /v1/intel/resources` · `GET /v1/intel/x402-directory` · `GET /v1/intel/marketplace`
- `POST /v1/intel/preflight` · `GET /v1/intel/merchant_card/{wallet}` · `GET /v1/intel/score_wallet_for_intel?wallet={wallet}`
- Wallet-graph discovery (free): `GET /v1/intel/sellers` · `GET /v1/intel/get_counterparties?wallet={wallet}` · `GET /v1/intel/get_facilitator_footprint?wallet={wallet}` · `GET /v1/intel/compare_wallets?wallet_a={wallet}&wallet_b={wallet}` · `GET /v1/intel/badge/{pubkey}`
- `GET /v1/intel/cohort_stats` · `GET /v1/intel/verdict-history/{wallet}` · `GET /v1/intel/get_top_intel_agents?limit=10` (secondary research)
- `GET /v1/receipts/example` · `POST /v1/receipts/verify` · `GET /.well-known/x402` · `GET /openapi.json` · `GET /health`

### Receipt and re-call contract

V6 = keccak256 leaf + Ed25519 over raw leaf bytes. Verify offline with
`npx twzrd-receipt-verifier@^1.3.0 receipt.json --pubkey 9V6Pn19kiUA5Rn6JpQfNduanvGt2aXGwsarosNfa2Ldf` or
`POST /v1/receipts/verify`. Paid receipts carry `recheck_after_unix`,
`staleness_days`, `score_decay_model` under `twzrd_receipt.preimage`. Once due,
re-call paid trust or treat the cached score as decayed (stale ≠ invalid).

Watch lane (push side of the re-call contract):
  Instead of polling recheck_after_unix yourself, register a watch and TWZRD
  re-checks the seller for you (polled every ~120s once due).
  Register  POST https://intel.twzrd.xyz/v1/intel/watch
            body: {"payer_wallet":"...","seller_wallet":"...","webhook_url":"https://..."}
            webhook_url is optional - omit it for poll-only watches.
  Notify    when a re-check is due AND the intel materially changed (decision
            change, score moves > 5 points, or first check after registration),
            TWZRD POSTs event twzrd.watch.recheck_due to your webhook with
            fresh_intel: {trust_score, decision, recheck_after_unix,
            staleness_days, seller_wallet}.
  Webhooks  public HTTPS only - private/reserved IPs are rejected at
            registration and redirects are never followed on delivery.
  Limits    max 25 active watches per payer_wallet.
  List      GET https://intel.twzrd.xyz/v1/intel/watch?payer_wallet=...  (webhook URLs masked to host)
  Remove    DELETE https://intel.twzrd.xyz/v1/intel/watch/123?payer_wallet=GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs
  MCP       twzrd_watch_add / twzrd_watch_list / twzrd_watch_remove.

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

- 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.4
```

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 V6 receipt
- [x402 directory](https://intel.twzrd.xyz/v1/intel/x402-directory): multi-bazaar overlay by payTo (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
- [MCP](https://intel.twzrd.xyz/mcp): hosted Streamable HTTP server with 24 tools
- [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