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

TWZRD evaluates the seller + resource before an agent pays, then returns optional
portable V6 proof after a paid trust call. It reports reputation evidence from
observed x402 settlement behavior; it does not verify a person's or agent's identity.

Primary seller-first workflow — run this BEFORE paying:
1. `evaluate_x402_resource` when you have a URL, or `get_x402_directory` to discover services.
2. `get_merchant_card`; refuse `wash_flagged=true` and inspect `payable_conformance`.
3. `get_readiness_card_tool` / `POST /v1/intel/preflight`; honor `allow|warn|block`.
4. Optionally buy paid trust, persist `twzrd_receipt`, and verify it offline.

The payer leaderboard is secondary corpus research. Observed payer wallets are not
TWZRD customers, revenue, or proof that every wallet is an autonomous agent.

## Buyer gate (core product — canonical install path)

Install before any x402 client signs:

```bash
npm install twzrd-x402-gate@0.8.2 @x402/core @x402/fetch @x402/svm
```

```ts
import { x402Client } from "@x402/core/client";
import { wrapFetchWithPayment } from "@x402/fetch";
import { ExactSvmScheme } from "@x402/svm/exact/client";
import { installTwzrdX402ClientHook } from "twzrd-x402-gate";

const client = new x402Client();
client.register("solana:*", new ExactSvmScheme(svmSigner));
installTwzrdX402ClientHook(client, {
  gateOnCanSpend: false,
  refuseWashFlagged: true,
});
// Official onBeforePaymentCreation seat; block aborts before signing.
const payingFetch = wrapFetchWithPayment(fetch, client);
```

Optional paid V6 receipts buy portable proof. Free preflight is advisory unless
your client installs a gate and honors the decision.

### Agent skill (one URL, save + self-update)

Tell your agent: "set up https://intel.twzrd.xyz/skill.md". Canonical twzrd-trust skill
(versioned frontmatter; saved copies self-update by comparing metadata.version).
Also on ClawHub: npx clawhub install twzrd-trust

### Zero-install MCP (recommended)

Hosted Streamable HTTP endpoint: `https://intel.twzrd.xyz/mcp`.
It exposes 24 free MCP tools and requires both response types in 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.

`twzrd_demo_gate` is a deterministic no-spend proof: its block path aborts before
any signer; its allow path would proceed but still spends nothing. Caller-supplied
attribution is an `external_candidate`, never proof of an external run.

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"}}}}
```

## Start free: seller-first happy path

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

- `block`: do not pay.
- `warn`: thin/unknown history; proceed deliberately or buy portable proof.
- `allow`: evidence supports a small spend; this is not a guarantee or identity claim.

Free merchant card: `GET /v1/intel/merchant_card/{wallet}`.
Operator repro: `python packages/twzrd-agent-intel/scripts/seller_first_flywheel_dogfood.py`.

## 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` | block aborts before wallet signing |
| After | `GET /v1/intel/trust/{pubkey}` | 0.05 USDC, signed V6 receipt |
| After | `POST /v1/receipts/verify` | free receipt verification |

## Paid HTTP (x402 v2, Solana mainnet USDC)

- `GET /v1/intel/trust/{pubkey}?seller_wallet=SELLER_PUBKEY` — 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.
- `GET /v1/intel/solana_market_visibility_map?merchant=SELLER_PUBKEY` — 0.03 USDC.
- `GET /v1/intel/solana_market_orderbook_depth?ticker=TICKER&merchant=SELLER_PUBKEY` — 0.03 USDC.
- `GET /v1/intel/solana_market_shape?ticker=TICKER&merchant=SELLER_PUBKEY` — 0.03 USDC.
- `GET /v1/intel/solana_market_onchain_trades_summary?merchant=SELLER_PUBKEY` — 0.03 USDC.

For the trust route, `seller_wallet=` or `X-TWZRD-Seller-Wallet` identifies the
counterparty the settle gate should evaluate. For market routes, use `merchant=`.
Omitting the counterparty leaves the gate nothing to evaluate.

x402 v2 flow: unpaid response returns `payment-required`; choose an `accepts`
entry, sign it, and retry with `payment-signature`. A successful paid trust
response contains `twzrd_receipt` in JSON. The payer must hold USDC; an advertised
fee payer can sponsor network gas, not the payment amount.

`GET /supported` describes TWZRD's own optional facilitator and its signer. It is
not required to equal the fee payer on every accepted requirement for TWZRD's paid
resources, which can name an external primary facilitator and opt-in alternates.

## Free HTTP (no payment, no auth)

- `POST /v1/intel/preflight`
- `GET /v1/intel/x402-directory`
- `GET /v1/intel/merchant_card/{wallet}`
- `GET /v1/intel/score_wallet_for_intel?wallet=PUBKEY`
- `GET /v1/intel/get_top_intel_agents?limit=10` (secondary payer-corpus research)
- `GET /v1/receipts/example` (sample only; no wallet or settlement)
- `POST /v1/receipts/verify`
- `GET /.well-known/x402`, `GET /openapi.json`, `GET /health`

## Receipt and re-call contract

A V6 receipt is a keccak256 leaf plus an Ed25519 signature over the raw leaf
bytes. V6 binds the reputation provenance fields into the signed preimage.
Verify offline with `npx twzrd-receipt-verifier@1.2.2 receipt.json --pubkey
9V6Pn19kiUA5Rn6JpQfNduanvGt2aXGwsarosNfa2Ldf` or `POST /v1/receipts/verify`.

Paid receipts carry `twzrd_receipt.preimage.recheck_after_unix`,
`staleness_days`, and `score_decay_model`. Once due, re-call paid trust or treat
the cached score as decayed; expiry makes evidence stale, not cryptographically 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/{watch_id}?payer_wallet=...
  MCP       twzrd_watch_add / twzrd_watch_list / twzrd_watch_remove.

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

- This service package, the npm buyer gate, and framework plugins are versioned independently.
- Preflight does NOT block settlement; an installed client hook must honor the decision.
- With `TWZRD_SETTLE_GATE_ENABLED=true`, paid routes can refuse settlement before
  broadcast when an explicit seller counterparty scores below policy threshold.
- 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 and server adapters

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

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

- [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/{wallet}): observed seller graph, wash and payable conformance
- [Trust receipt](https://intel.twzrd.xyz/v1/intel/trust/{pubkey}): paid live intel plus signed V6 receipt
- [x402 directory](https://intel.twzrd.xyz/v1/intel/x402-directory): multi-bazaar services indexed by payTo
- [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