# TWZRD

**Don't let your agent sign blind.**  
Spend control and counterparty trust for agents paying over x402 on Solana (and Base).
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). Signed execution clearance is **$0.001** (`twzrd.payment_decision.v1` / `quickCheck`). 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 (twzrd-trust **1.13.24**) · [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 — 22 tools)  
**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.*

---

## 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({ refuseWashFlagged: true }),
});
```

---

## Commerce loop

One path. Install `twzrd-x402-gate@0.11.2`. Free preflight does not enforce; AutoGate on the pay path does.

1. **Install the gate** — `npm i twzrd-x402-gate@0.11.2` then `installTwzrdAutoGate`
2. **Cold-start (optional)** — `npx twzrd-cold-start` writes a default-deny `policy.json` from a pinned foreign 402 diet (0 USDC; not a TWZRD bazaar)
3. **Directory** — `GET /v1/intel/resources` (or `listDirectoryCallables`) — bazaars list; TWZRD sits beside
4. **Preflight** — free ReadinessCard + merchant_card wash refuse
5. **Pay only when policy allows** — blocks have `signerInvocations === 0`
6. **Clearance ($0.001)** — `quickCheck` + portable `twzrd.payment_decision.v1` (`npx twzrd-payment-decision --verify`)
7. **Evidence bundle** — `exportEvidenceBundle` / `npx twzrd-evidence-bundle`
8. **Optional Path A** — $0.05 V7 intel receipt. Not the primary SKU.

Refuse-first demo (0 USDC): `npx tsx twzrd-x402-gate/examples/commerce-kit.ts`  
Cold-start diet (0 USDC): `npx twzrd-cold-start`  
Walkthrough: [docs/COMMERCE-KIT.md](./docs/COMMERCE-KIT.md)

## Default Protection Sequence

1. **Discover** — `GET /v1/intel/resources` (resource catalog)
2. **Merchant card** — `GET /v1/intel/merchant_card/{pay_to}` (refuse if `wash_flagged: true`)
3. **Preflight** — `POST /v1/intel/preflight` → ReadinessCard (allow / warn / block)
4. **Clearance ($0.001)** — `GET /v1/intel/quick/{pay_to}` + `twzrd.payment_decision.v1`
5. **Pay** — sign only when preflight & spend policy allow

```bash
# Free preflight (no signup, no wallet)
curl -s -X POST https://intel.twzrd.xyz/v1/intel/preflight \
  -H 'content-type: application/json' \
  -d '{"seller_wallet":"46vMcwuC4sK11sB3gkLhyA7J7GEwfkhn5rFyDtihBwqe","price_usdc":0.01,"agent_intent":"preflight"}'
```

---

## Packages & References

| Package | Pin | Description |
|---|---|---|
| `twzrd-x402-gate` | **@0.11.2** | Spend-control SDK (`twzrd.safeFetch`) + pre-sign gate hooks |
| `x402-solana` | **@3.0.0** | Compatible Solana client seat for the pre-payment gate |
| `twzrd-receipt-verifier` | **@^1.4.0** | Standalone offline verifier for Ed25519 V5/V6/V7 receipts |
| `twzrd-mcp-server` | **@0.5.4** (this tree) | Local spend-capped auto-pay client (6 tools); prefer hosted MCP |
| `@wzrd_sol/plugin-trustgate` | **@^0.3.7** | Eliza / facilitator adapter |

- **Commerce loop (don't sign blind):** [docs/COMMERCE-KIT.md](./docs/COMMERCE-KIT.md)
- **Step-by-step Guide:** [QUICKSTART.md](./QUICKSTART.md)
- **Concepts & Architecture:** [docs/taxonomy.md](./docs/taxonomy.md)
- **V6/V7 Receipt Specification:** [docs/receipt-v6-spec.md](./docs/receipt-v6-spec.md)
- **Receipt Transparency Log:** [docs/transparency-log.md](./docs/transparency-log.md) (in-repo `twzrd-log-verifier` — not on npm)
- **Receipt Verification & Ground Truth:** [REVIEW.md](./REVIEW.md)
- **Security Policy:** [SECURITY.md](./SECURITY.md) · [docs/security-assurance.md](./docs/security-assurance.md)