# TWZRD — default trust + receipt layer for agent payments

Agents should not pay unknown endpoints blindly. TWZRD adds a one-call check
BEFORE an x402 payment (should this counterparty receive money?) and a signed,
offline-verifiable receipt AFTER it. It is a trust + receipt layer, not another
way to pay.

First beachhead: the live Solana x402 payer graph. We observe cross-facilitator
x402 payment behavior across ~100k payers and score it, so an agent can vet a
seller before paying. 95k+ genesis cNFT receipts are independently verifiable
offline; the local auto-pay MCP (`pip install twzrd-mcp` or
`npx -y twzrd-mcp-server`) buys fresh capped paid intel over Solana x402.

## Where TWZRD fits in your payment path

  BEFORE    POST /v1/intel/preflight       allow / warn / block + trust_score (free)
  DURING    ?seller_wallet= on a paid call arms a settle-time gate that refuses to
            broadcast USDC to a below-threshold seller (402, charged:false, no tx)
  AFTER     GET /v1/intel/trust/{pubkey}   signed V6 receipt — verify the paid
            response happened, offline, trusting no TWZRD code
  DISCOVERY GET /v1/intel/get_top_intel_agents  rank/filter by trusted payment history

Infra one-liner: call TWZRD before x402 payment authorization to decide whether an
agent should pay, and after settlement to verify that a paid response happened.

## The happy path: one free call, then pay

1. Free preflight    POST https://intel.twzrd.xyz/v1/intel/preflight
                     body: {"seller_wallet":"<seller>","price_usdc":<amount>}
                     → readiness_card.decision + can_spend
2. decision=allow  → established, clean counterparty. Pay. (can_spend=true; no
                     further calls needed for small spends.)

Secondary branches:
- decision=block → do NOT pay. Wash/fleet-flagged seller. Abort.
- decision=warn  → unknown or thin history (the conservative default). If the spend
  matters (>= $1.00, or you want portable proof), buy the $0.05 trust receipt:
     GET https://intel.twzrd.xyz/v1/intel/trust/{pubkey}?seller_wallet=<seller>
  route on reputation_credential.credentialSubject.effectiveTrustScore
  (< 30 block | 30-60 warn | > 60 allow), then verify the signed receipt offline.

Free `allow` is deliberately conservative (anti-sybil): it fires for established
organic sellers and diversified, cross-facilitator agents, and stays `warn` for
thin/unknown wallets. The precise score + signed receipt are the paid
/v1/intel/trust surface.

Conditional ROI for the $0.05 trust receipt:
  Always buy if   payment_amount >= $1.00  (receipt cost < 5% of spend)
  Always buy if   decision = warn          (unknown/thin — buy the proof)
  Skip if         decision = allow + payment < $0.10
  Cache/share     same seller across agents on same task → buy once, reuse

## Routing table

| Need | Call | Cost | Gate field |
|------|------|------|-----------|
| Pre-spend gate (first step) | POST /v1/intel/preflight | Free | readiness_card.decision (HTTP) |
| Pre-spend gate via MCP | get_readiness_card_tool | Free | decision (top-level, no nesting) |
| Full trust + signed receipt | GET /v1/intel/trust/{pubkey} | 0.05 USDC | reputation_credential.credentialSubject.effectiveTrustScore |
| Market data via MCP | get_solana_market_* tools | Free | - |
| Market data via HTTP | GET /v1/intel/solana_market_* | 0.03 USDC | - |
| Verify receipt | POST /v1/receipts/verify | Free | result.valid |
| Discovery / leaderboard | GET /v1/intel/get_top_intel_agents | Free | - |

## Start here (one command, free) — vet a seller before you pay
curl -s -X POST https://intel.twzrd.xyz/v1/intel/preflight \
  -H 'content-type: application/json' \
  -d '{"seller_wallet":"BJGdsDXJFy63eCAnX3UmGfShp8BuqbtkTfcamyRGr7VQ","price_usdc":0.01}'
# established seller -> readiness_card.decision="allow", can_spend=true -> pay.
# Swap in your own seller_wallet: unknown/thin -> "warn" (buy the $0.05 receipt);
# wash/fleet -> "block" (don't pay). No auth, no payment.

The free preflight already gives you allow / warn / block. The paid trust call
(https://intel.twzrd.xyz/v1/intel/trust/{pubkey}, 0.05 USDC) is where you buy
the PROOF: a portable, Ed25519-signed V6 receipt anchored to your settlement
transaction, offline-verifiable with no trust in TWZRD (plus the renormalized model).
To explore the corpus instead, curl /v1/intel/get_top_intel_agents?limit=1 (leaderboard
+ total_payers_observed + denoised corpus_slices; free).

## What the corpus numbers mean (honest)
total_payers_observed (curl /v1/intel/get_top_intel_agents?limit=1 for the live count)
is the RAW observed payer total and INCLUDES the April-2026 CDP demo/onboarding faucet
wave (the bulk of it: one-shot payers + single-merchant bots; see corpus_slices.one_shot_le1
and .single_merchant_bots_ge100tx). The durable, real graph is in corpus_slices in
that same get_top_intel_agents response: pre_spike_base_last_seen_pre_2026_04 (payers
whose entire footprint predates the April faucet) and multi_merchant_ge2 (agents that
paid 2+ distinct resources -- the real comparison-shoppers). Read the live values from
the response; they drift slowly as the corpus updates. These are
ECOSYSTEM payment behaviors we observe and score - NOT calls or revenue to TWZRD.
TWZRD's own paid usage of this surface is pre-demand (one external settlement
all-time; payer attribution is verified on-chain, never client-declared).

## Paid (x402, USDC on Solana mainnet)
- GET https://intel.twzrd.xyz/v1/intel/trust/{pubkey}?seller_wallet=<seller you are about to pay>  -> 0.05 USDC. Live trust intel + portable V6 receipt. Proven on mainnet.
- GET https://intel.twzrd.xyz/v1/intel/solana_market_visibility_map?merchant=<seller pubkey>        -> 0.03 USDC
- GET https://intel.twzrd.xyz/v1/intel/solana_market_orderbook_depth?ticker=...&merchant=<seller pubkey>   -> 0.03 USDC
- GET https://intel.twzrd.xyz/v1/intel/solana_market_shape?ticker=...&merchant=<seller pubkey>      -> 0.03 USDC
- GET https://intel.twzrd.xyz/v1/intel/solana_market_onchain_trades_summary?merchant=<seller pubkey>      -> 0.03 USDC

Funding: the payer wallet must hold the USDC itself. Gas is sponsored (the 402
challenge advertises a TWZRD feePayer that co-signs the network fee) - the
payment amount is NOT. An unfunded payer gets a machine-readable 402
(reason source_token_account_missing / insufficient_funds) with the exact
token account, mint, and required amount to act on.

Pass the seller counterparty on every paid call: ?merchant= on market routes,
?seller_wallet= (or X-TWZRD-Seller-Wallet header) on the trust route. It is optional,
but it is what arms the settle-time trust gate: if that seller scores below threshold
the server refuses to settle (402, charged:false, NO on-chain tx) before your payment
broadcasts. Omit it and the gate has nothing to evaluate. On the trust route the scored
{pubkey} itself is never gated -- only the seller_wallet counterparty.

## Free (no payment, no auth)
- POST https://intel.twzrd.xyz/v1/intel/preflight   (the one-command demo; BEFORE-path ReadinessCard)
- GET  https://intel.twzrd.xyz/v1/intel/score_wallet_for_intel?wallet=...
- GET  https://intel.twzrd.xyz/v1/intel/get_top_intel_agents?limit=10&min_paid_calls=2&max_days_since_last=14   (leaderboard; filters optional - min_paid_calls suppresses one-shots, max_days_since_last suppresses dormant)
- GET  https://intel.twzrd.xyz/v1/intel/get_facilitator_footprint?wallet=...   (which x402 facilitators a payer settled through)
- GET  https://intel.twzrd.xyz/v1/intel/get_counterparties?wallet=...&limit=10   (capped teaser: top merchants this wallet pays; limit<=25)
- GET  https://intel.twzrd.xyz/v1/intel/compare_wallets?wallet_a=...&wallet_b=...   (side-by-side intel for two wallets)
- POST https://intel.twzrd.xyz/v1/intel/score_wallets_batch   (body: {"wallets":[...]}, up to 25)
- GET  https://intel.twzrd.xyz/v1/receipts/example   (no-wallet SAMPLE signed receipt -> verify offline before you spend)
- POST https://intel.twzrd.xyz/v1/receipts/verify   (recompute + check a portable V6 receipt leaf)
- GET  https://intel.twzrd.xyz/.well-known/twzrd-receipt-pubkey  (canonical issuer key to pin out-of-band)
- GET  https://intel.twzrd.xyz/.well-known/x402      (machine-readable service descriptor)
- GET  https://intel.twzrd.xyz/openapi.json          (OpenAPI 3.1 with x402 annotations)
- GET  https://intel.twzrd.xyz/health

## See the gate return a block (the secondary branch, free)
curl -s -X POST https://intel.twzrd.xyz/v1/intel/preflight \
  -H 'content-type: application/json' \
  -d '{"resource_name":"Jupiter Quote Preview","price_usdc":0.01}'
# a low-quality / flagged resource -> readiness_card.decision="block", can_spend=false.
# This is the gate doing its job, not the happy path — most established sellers -> allow
# (see "Start here" above).

## Receipt (portable + signed, V6)
The signed receipt is a PORTABLE keccak256 leaf (tamper-evidence) PLUS an Ed25519
signature over the leaf bytes (authenticity). As of V6 the leaf binds the full
reputation provenance (reputation_score, score_version, data_quality, ...), so
those surfaced fields are now signed -- editing any of them invalidates the
receipt. Verify it offline: recompute the keccak leaf from the preimage AND check
the signature against the published TWZRD receipt-signing public key (key_id
twzrd-receipt-ed25519-v1, base58 9V6Pn19kiUA5Rn6JpQfNduanvGt2aXGwsarosNfa2Ldf, ed25519) -- pinned at
/.well-known/twzrd-receipt-pubkey (also in /.well-known/x402 and /openapi.json).
Unsigned or wrong-key receipts are rejected. The settlement_tx anchor stays
independently checkable on-chain for ground truth.

## Verify offline (standalone tool, trusts no TWZRD code)
A stranger can verify a signed receipt with only the published key + audited crypto libs.
Use >=1.2.0 (it understands the V6 leaf that now binds the reputation_* fields; older
versions only know the V5 leaf and will report a leaf mismatch on a current receipt):
  pip install 'twzrd-receipt-verifier>=1.2.0'   # then: twzrd-verify-receipt receipt.json --pubkey 9V6Pn19kiUA5Rn6JpQfNduanvGt2aXGwsarosNfa2Ldf
  npx twzrd-receipt-verifier@1.2.0 receipt.json --pubkey 9V6Pn19kiUA5Rn6JpQfNduanvGt2aXGwsarosNfa2Ldf

## Install
- MCP (18 tools, streamable-http): https://intel.twzrd.xyz/mcp  (card: /.well-known/mcp.json)
    openclaw mcp add twzrd --url https://intel.twzrd.xyz/mcp --transport streamable-http
    Note: MCP requires both Accept headers -- Accept: application/json AND
    Accept: text/event-stream. Missing either returns HTTP 406.
- Auto-pay MCP (local, Solana x402):
    pip install twzrd-mcp
    npx -y twzrd-mcp-server --help
    Minimal Node config: {"mcpServers":{"twzrd":{"command":"npx","args":["-y","twzrd-mcp-server"],"env":{"TWZRD_RPC_URL":"<mainnet rpc>","TWZRD_WALLET_SECRET_KEY":"<base58 secret>"}}}}
    Node config: {"mcpServers":{"twzrd":{"command":"npx","args":["-y","twzrd-mcp-server"],"env":{"TWZRD_RPC_URL":"<mainnet rpc>","TWZRD_WALLET_SECRET_KEY":"<base58 secret>","TWZRD_MAX_USDC_PER_CALL":"0.05","TWZRD_MAX_USDC_TOTAL":"1.00"}}}}
- OpenClaw preflight plugin (gates payment-shaped tool calls on the free preflight):
    npm install twzrd-preflight   # shadow mode by default; see its README for enforce/config
- Direct HTTP: every endpoint is in /openapi.json (OpenAPI 3.1 with x402 annotations).
- Receipt verify (offline, no engine): npx twzrd-receipt-verifier@1.2.0 receipt.json --pubkey 9V6Pn19kiUA5Rn6JpQfNduanvGt2aXGwsarosNfa2Ldf

## More
- Full tool reference + per-endpoint details: https://intel.twzrd.xyz/llms-full.txt and /openapi.json
- Machine-readable service descriptor: /.well-known/x402
- MCP registry: https://smithery.ai/servers/wzrd/twzrd-agent-intel
- Public source: https://github.com/twzrd-sol/twzrd-trust
- Live mainnet proof tx: 3aXGtvmNvFhSSDXF8D4DBDntXFczraUABg75MdWtCgchdYAApRwC7KxdGxbCmewYcA6ZNzw6FvdAHcoevMUG44Sc
- Live at https://intel.twzrd.xyz | health: /health (package_version, gate status)

## 0.5.2 trust gate semantics
- Package version: see /health package_version (PyPI: twzrd-agent-intel).
- Free preflight (POST /v1/intel/preflight): advisory ReadinessCard only.
  Preflight does NOT block settlement -- it returns a decision your client chooses
  to honor (see onBeforeSettle hook above). Pass queried_pubkey for consumer
  attribution on the velocity corpus.
- Paid settle gate (GET /v1/intel/trust/* and market paid routes): blocks x402 settlement when
  TWZRD_SETTLE_GATE_ENABLED=true and seller counterparty score is below threshold. Enforce
  mode live as of 2026-06-08; shadow mode off. Supply the counterparty per call:
  ?merchant= (market routes) or ?seller_wallet= / X-TWZRD-Seller-Wallet header (trust
  route). Without it the gate has nothing to evaluate and settlement proceeds ungated.
- Client hook: packages/twzrd-agent-intel/verifier/on_before_settle.py (preflight before pay).
- MCP registry auth key (/mcp-registry-auth) is NOT the receipt-signing key (/.well-known/x402).

## Buyer-side gate (optional, pre-spend enforcement SDK)

If your framework has a payment hook, enforce the preflight decision automatically
rather than checking it yourself. Both packages are dependency-free (no @elizaos/core required
for the gate core) and fail-open by default.

  npm install twzrd-x402-gate          # generic: wraps fetch or MCP onPaymentRequested hook
  npm install @wzrd_sol/plugin-trustgate  # elizaOS plugin + canSpendSafely + facilitator hook

### Wrap any fetch that may receive a 402
  import { wrapFetchWithTwzrdGate } from "twzrd-x402-gate";
  const gated = wrapFetchWithTwzrdGate(fetch);
  // THROWS on block-rated seller before USDC leaves your wallet.

### elizaOS agents (one line)
  import { canSpendSafely, withTwzrdGuard } from "@wzrd_sol/plugin-trustgate";
  if (!(await canSpendSafely(payTo))) throw new Error("TWZRD: blocked seller");
  // or decorator-style:
  await withTwzrdGuard(payTo, () => signAndSendPayment(payTo, amount));

### MCP hook (x402/core onPaymentRequested)
  import { twzrdOnPaymentRequested } from "twzrd-x402-gate";
  const client = createX402MCPClient({ onPaymentRequested: twzrdOnPaymentRequested });

### onWarnUpsell (auto-trigger paid receipt on unknown sellers)
  import { createTwzrdGate } from "twzrd-x402-gate";
  const gate = createTwzrdGate({
    onWarnUpsell: (ctx) => paidFetch(`https://intel.twzrd.xyz${ctx.upsellUrl}`),
  });

### Facilitator operators (screen every brokered settlement)
  import { createOnBeforeSettleHook } from "@wzrd_sol/plugin-trustgate/facilitator";
  const facilitator = createFacilitator({
    hooks: { onBeforeSettle: createOnBeforeSettleHook() },
  });

# 🛡️ Self-Serve Trust Badges (free, no auth, embed in any marketplace)

Drop these in your Smithery or Bazaar listing. Render instantly, auto-update hourly, zero setup.

Wash integrity badge (is this wallet clean?):
  <img src="https://api.twzrd.xyz/v1/wash/badge/YOUR_WALLET">

Provider reputation badge (is this merchant legit?):
  <img src="https://api.twzrd.xyz/v1/reputation/badge/YOUR_MERCHANT">

Intel trust-tier badge (how reputable is this agent?):
  <img src="https://intel.twzrd.xyz/v1/intel/badge/YOUR_PUBKEY">

All: append ?format=json for JSON. Free tier, no API key.
Full API: POST /v1/wash/analyze | POST /v1/reputation/analyze (Pro tier)
Receipts: GET /v1/receipts | GET /v1/receipts/:id (Pro tier)