TWZRD

Pre-spend trust for agents that buy. Before an agent pays an x402 seller or buys a product from a store, TWZRD answers one question from public evidence: should this payment go ahead? The buyer-side gate turns that answer into a refusal before the wallet signs. This repository is the public source of truth for the hosted checks, the npm packages, the receipt and record formats, and the proofs behind them.

Guard an agent's paying fetch: a caller-supplied USDC cap, an explicit recipient allowlist, mandatory free preflight, and a local decision record before signing. createBuyerFetch is the front door (since twzrd-x402-gate@0.12.3); its expectedAmount quote binding needs twzrd-x402-gate@0.12.4 or later. Install the current release, twzrd-x402-gate@0.15.0, and start with the runnable buyer wrapper quickstart. The other toolkit APIs below remain available with their existing defaults.

• 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 USDC, paid by the buyer over x402 (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; TWZRD never holds a key.
• 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 skill twzrd-trust
Spend-control SDK (npm) • twzrd-x402-gate@0.15.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

What is live, what is a pilot, what is not claimed

• Live on mainnet: the hosted checks (https://intel.twzrd.xyz/mcp and the REST routes below), twzrd-x402-gate on npm, the offline twzrd-receipt-verifier, the receipt transparency log with on-chain anchors (one per advanced tree head, hourly cadence), and the no-spend recorded demonstration at /v1/intel/demo-gate.
• Networks: the free checks score x402 sellers on Solana mainnet and Base mainnet (eip155:8453), and the gate runs the scored preflight on both. The paid /quick and /trust endpoints accept the buyer's $0.001 or $0.05 USDC payment on either chain but score a Solana seller wallet only, so signed V7 receipts cover Solana sellers. EVM chains other than Base are recognized but not scored. The examples below use the Solana seat; see the gate's network table for Base.
• Pilot: the product-listing lane runs against a single listing-evidence card (Vuori Kore Short, Ink, US). Vouch-mode calibration (#5) and token-safety previews (#207, #214) are open work, not shipped features.
• Not yet attempted: the seven-day external integration milestone. Every proof in this repository is TWZRD-operated mechanism evidence, not outside adoption.
• Not claimed: identity of a person, company or agent; checkout, purchase completion or delivery; permission to spend (authorizes_spend is always false). See What TWZRD does not claim.

Start here, by what you came to do

Versions, verified 2026-10-26

Registry latest as read on that date. The tree column is what this checkout mirrors; a difference is a pending resync, not a second product.

Run one blocked payment locally

npm ci
npm run build
npm run buyer-demo --workspace=twzrd-x402-gate

This uses the real x402 client against an offline 402 fixture. It prints reason: price_cap_exceeded, signer_invocations: 0 and usdc_spent: 0, and writes .twzrd/demo-decisions.jsonl locally. It makes no network request and needs no wallet. This is internal demonstration evidence, not outside use.

For an installed consumer, pack the gate and install the tarball with its optional @x402/core and @x402/fetch peers; then run npx twzrd-buyer-demo. See the package README for the install and live client wiring. /quick and /trust stay optional seller-score products; the wrapper buys neither and makes no fulfillment claim.

Hosted recorded demonstration

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.

Other integration APIs

1. Install

npm install twzrd-x402-gate@0.15.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.15.0. Free preflight does not enforce; AutoGate on the pay path does.

1. Install the gate — npm i twzrd-x402-gate@0.15.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}'

This example assumes the reference card is current. Each published card carries an expires_at; once it has lapsed, the same call returns result: "expired" with needs_approval: true until a fresh card is published. 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 human to review before they check out. TWZRD never opens or completes a checkout, and it 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

• Document index (what is current, what is history): docs/README.md
• 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
• Supported path and ownership: docs/SUPPORT_MATRIX.md · docs/ACCESS_AND_RECOVERY.md
• Security Policy: SECURITY.md · docs/security-assurance.md

Contributing and change control

Issues and pull requests on this repository. A sample that does not run exactly as shown is a bug. The release policy for twzrd-x402-gate is the manual publish workflow with an expected_version check and npm provenance; the published 0.15.0 carries a provenance attestation from this repository (npm view twzrd-x402-gate@0.15.0 dist.attestations). Earlier releases did not all follow that path; AGENTS.md records the fork history. A change to what the gate allows or refuses ships in a minor release with a CHANGELOG.md entry (policy). Artifact directories are resynced from the published tarball, never hand-edited (AGENTS.md). Tests pin the documentation: the current install pin, the pay-path contract, the refusal-code tables and the generated ecosystem block are all asserted by npm test, so a doc that drifts from the code fails CI.

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.