Twzrd Trust MCP Server

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).

Not a wallet. Not a payment network. The commerce walkthrough lives in 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
Spend-control SDK (npm) • twzrd-x402-gate@0.12.0 + seat x402-solana@3.0.1
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:

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:

{
  "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

Pre-spend trust for AI agents that buy: check x402 services and product listings before paying.

Each piece below works alone. Plugged into the hosted checks, they form one pre-spend path.

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.

More: 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.

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

npm install twzrd-x402-gate@0.12.0 x402-solana@3.0.1

2. Wrap paid fetches with spend controls

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

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.12.0. Free preflight does not enforce; AutoGate on the pay path does.

1. Install the gate — npm i twzrd-x402-gate@0.12.0 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. Paid check ($0.001) — quickCheck (tier and score). Separately, the gate can issue a portable twzrd.payment_decision.v1 record from its decision, signed by your own signer (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

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. Paid check ($0.001) — GET /v1/intel/quick/{pay_to} (wash risk, tier, score). Separately, the gate can issue a locally signed twzrd.payment_decision.v1
5. Pay — sign only when preflight & spend policy allow

# 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"}'

---

Product listings: check the listing before you buy

The second lane is for an agent buying a product from a store, not paying an x402 seller. Before it buys, it calls check_listing(product_url, declared_unit_price) on the hosted MCP, which compares the product URL and the asking price with TWZRD's published listing card. The call is free and read-only: it does not fetch the store page, open a checkout, or move money.

# Declared $79 against a card that advertises $78: refused
curl -sS https://intel.twzrd.xyz/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"check_listing","arguments":{"product_url":"https://checkout.vuoriclothing.com/products/kore-short-ink","declared_unit_price":"79"}}}' \
  | sed -n 's/^data: //p' \
  | jq '.result.structuredContent | {result, reason, price_check, needs_approval, authorizes_spend}'

Expected output while the reference card is current and advertises $78:

{
  "result": "check_failed",
  "reason": "phantom_markup_detected",
  "price_check": "above_advertised",
  "needs_approval": true,
  "authorizes_spend": false
}

• price_check: verified means your declared price equals the price on the captured card. It does not mean TWZRD verified the store, the purchase, or delivery.
• needs_approval: true means a human approves before the agent buys; a card that advertises no price also sets it. needs_approval: false means this check raised no flag. It is not clearance, and with no declared_unit_price the price was not checked at all.
• check_failed also covers a card that cannot be read or verified, and a declared price that is not a valid non-negative number (price_check: invalid).
• authorizes_spend is always false: a matching card is evidence for your own spend policy, not permission to spend.

What a card is, and what it is not:

• One reference card today: Vuori Kore Short, Ink, US. It is an observer card (TWZRD's capture of the store's public pages), not a merchant attestation. Each published card carries an expires_at; after it, check_listing returns expired.

• Advertised means a captured page said it. Purchase completion and delivery are not verified.

• Read the card and its evidence: get_claim and get_evidence. get_shopping_check returns the Agent Shopping Check report, the same one as https://twzrd.xyz/shopping-check/vuori-kore/ and GET https://intel.twzrd.xyz/v1/shopping-check/vuori-kore.

• Check that the card is the one TWZRD published: get_publication returns the publication record as JSON in its text field: verify_key (base64), publication (the digests and a base64 signature) and signed_message (how the signed bytes are built). Base64-decode verify_key to its 32 raw bytes and compare their sha256 with the fingerprint below. This README is the independent pin: skill.md carries the same value but is served by the same host as the key, and a fingerprint taken from the same response proves nothing. Never refresh this value from the live skill.md when re-syncing the mirrors; change it only when the key is deliberately rotated. Then verify the Ed25519 signature over the signed bytes with that key, and check that the sha256 of the text returned by get_claim and get_evidence equals publication.artifact_digest and publication.evidence_digest. A valid signature shows that TWZRD published these bytes; it is not a merchant attestation.

  sha256:903d0d041e2d82fc0dd6f5252b4e904121e113e498d00b7385cad6061b4881af
  

• Paid, optional: GET https://intel.twzrd.xyz/v1/intel/checkout-brief ($0.001 USDC via x402) returns a brief tied to the card, with your cart_hash copied in, for a buyer-approved Shop Pay checkout. TWZRD does not check the hash against any cart. The brief carries needs_approval and authorizes_spend: false, and it does not pay the merchant. A product URL that does not match the card, or an expired card, returns 404 before any 402; a declared price above the advertised one returns 409 before any 402.

---

Packages & References

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

License

MIT. See LICENSE. The hosted checks run on infrastructure TWZRD operates; the server package behind them is published separately as twzrd-agent-intel on PyPI, also MIT.