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

Agents should not pay unknown x402 endpoints blindly. TWZRD adds a one-call
pre-spend check BEFORE paying (should this counterparty receive money?) plus a
signed, offline-verifiable V6 receipt after settlement. No wallet or signup is
required for free preflight; pay only 0.05 USDC when you want the
portable proof. It is a trust + receipt layer, not another way to pay.

First beachhead: live x402 services (seller + resource). PRIMARY WORKFLOW:
GET /v1/intel/resources (discover callables; listed|live_402 claims separate from
settlement trust) -> evaluate_x402_resource (URL) -> get_merchant_card ->
get_readiness_card_tool / preflight (decision + reason_codes + recommended_action) ->
verify_receipt after paid trust. MCP stays at 24 tools (resources is HTTP).
Unit of analysis is the service you are about to buy, not a payer leaderboard
(get_top_intel_agents is secondary research).

## Buyer gate (core product — stock PayAI seat first)

Install before any client signs. Primary seat: PayAI `x402-solana@2.1.0` `beforePayment`
(after requirement selection, before signTransaction). Pin: twzrd-x402-gate@0.8.12 + x402-solana@2.1.0.

  npm install twzrd-x402-gate@0.8.12 x402-solana@2.1.0

  import { createX402Client } from "x402-solana";
  import { createTwzrdBeforePaymentHook } from "twzrd-x402-gate";
  // or: installTwzrdAutoGate("x402-solana", { refuseWashFlagged: true })

  const client = createX402Client({
    wallet,
    network: "solana",
    beforePayment: createTwzrdBeforePaymentHook({ refuseWashFlagged: true }),
  });

  // Also Path E: installTwzrdAutoGate(x402CoreClient) for @x402/core onBeforePaymentCreation.
  // Also: installTwzrdAutoGate(payWrap) / installTwzrdAutoGate("mpp", opts).
  // Fallback CLI only: node node_modules/twzrd-x402-gate/bin/twzrd-gate-eval-refuse.js

Optional paid V6 receipts and the local auto-pay MCP
(`pip install twzrd-mcp` or `npx -y twzrd-mcp-server`) buy portable proof;
auto-pay stays disabled unless TWZRD_MCP_PAYMENTS_ENABLED=1 is set explicitly.

Conformance (agent-facing): python scripts/conformance_public.py https://intel.twzrd.xyz
-> JSON report discovery/transport/initialize/tools/free_preflight.

### Zero-install MCP (recommended)
pip install twzrd-mcp
# or
npx -y twzrd-mcp-server

MCP config (add to your agent):
{"mcpServers":{"twzrd-agent-intel":{"url":"https://intel.twzrd.xyz/mcp"}}}

(Supports streamable-http, 24 tools, dual Accept headers.)

No wallet • No signup • Free preflight • Pay only for signed V6 trust receipt.

## Where TWZRD fits in your payment path

  BEFORE    POST /v1/intel/preflight       allow / warn / block + reason_codes + recommended_action (free, advisory)
            GET  /v1/intel/merchant_card/{wallet}  free seller graph card (wash_flagged,
            payable_conformance: live_402 density + fee_payer_stability stable|rotating|unknown)
  DURING    Path A paid routes only: ?seller_wallet= can refuse below-threshold sellers
            (402, charged:false). Refusal needs settle_gate_enabled=true AND
            settle_gate_shadow=false - shadow only logs a would-block and lets the payment
            through. Read settle_gate_enforcing from GET /health for the resolved answer;
            it is runtime config, so do not assume a default.
  SETTLE    Settle rail (opt-in facilitator — gas-sponsorship + trust attach):
            GET  /supported   exact + feePayer 4LkEFj… + settlement_policy
            POST /verify then POST /settle  → tx + best-effort twzrd_receipt +
            merchant_attach (attach never voids chain success).
            Settle rail is a cosign+attach rail, not a trust-gated settlement firewall.
            Path A note: paid trust 402 may still list external feePayers (CDP/PayAI/
            Dexter). accepts[0] is not the settle rail unless feePayer matches /supported.
            Path B = buyer AutoGate refuse (pre-sign), not this facilitator surface.
  AFTER     GET /v1/intel/trust/{pubkey}   signed V6 receipt - verify the paid
            response happened, offline, trusting no TWZRD code
            GET /v1/intel/merchant/{pubkey} signed merchant track-record receipt
            (observed receive-side graph quality; NOT demand proof or a payer trust score; 0.05 USDC)
  DISCOVERY GET /v1/intel/resources           resource join SOT (callable + claims)
            GET /v1/intel/x402-directory      multi-bazaar overlay by payTo
            GET /v1/intel/merchant_card/{wallet} qualify a seller before paying
  RESEARCH  GET /v1/intel/get_top_intel_agents payer-corpus leaderboard (secondary)

Infra one-liner: call TWZRD before x402 payment authorization to decide whether an
agent should pay this seller/service; route settlement through TWZRD to attach
merchant intel + portable receipt when money moves; verify offline after.

## The happy path: seller-first flywheel (then pay)

Payment is self-proving. Score the SELLER before money moves:

1. Free preflight    POST https://intel.twzrd.xyz/v1/intel/preflight
                     body: {"seller_wallet":"GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs","price_usdc":<amount>}
                     → readiness_card.decision (allow | warn | block)
2. Free merchant card GET https://intel.twzrd.xyz/v1/intel/merchant_card/GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs
                     → refuse if wash_flagged=true (default); read payable_conformance
                       (listed ≠ live_402; fee_payer_stability for sponsored Solana exact)
3. Optional paid     GET https://intel.twzrd.xyz/v1/intel/quick/GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs  ($0.001 teaser)
                     or GET https://intel.twzrd.xyz/v1/intel/trust/GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs ($0.05 + V6 receipt)
4. Verify receipt    POST https://intel.twzrd.xyz/v1/receipts/verify  (or sample first:
                     GET https://intel.twzrd.xyz/v1/receipts/example)
5. Only then pay the seller's x402 resource (or settle via TWZRD facilitator for
   free merchant_attach on POST /settle)

Operator dogfood: python packages/twzrd-agent-intel/scripts/seller_first_flywheel_dogfood.py

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/GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs?seller_wallet=GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs
  route on reputation_credential.credentialSubject.effectiveTrustScore
  (< 30 block | 30-60 warn | > 60 allow), then verify the signed receipt offline.
- decision=allow + wash_flagged=false + small spend → pay without further paid calls.

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     within one task, buy once and reuse across your agents
  Re-verify when  a cached decision is stale. Trust scores DECAY: an `allow`
                  drifts toward `warn`/`block` over days-to-weeks as a seller
                  goes dormant or a captive fleet forms around it. Re-check a
                  counterparty you keep paying before a large or recurring
                  settle — the fresh receipt is anchored to the NEW settlement
                  tx, the cached one is not.

Re-call contract (machine-readable):
  The paid receipt carries the re-call fields at JSON path twzrd_receipt.preimage.*:
    recheck_after_unix  int  UNIX time to re-call; = timestamp_unix + staleness_days*86400
    staleness_days      int  recommended re-check cadence in days
                             (7 for high/real_corpus data quality, 3 for partial/stale/low)
    score_decay_model   str  step:<=7d=1.0,<=30d=0.8,<=90d=0.5,>90d=0.25
  Rule: once now >= recheck_after_unix, re-call
    GET https://intel.twzrd.xyz/v1/intel/trust/GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs
  A cached receipt older than recheck_after_unix is not invalid - treat its score
  as decayed per score_decay_model until you buy a fresh one.

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/123?payer_wallet=GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs
  MCP       twzrd_watch_add / twzrd_watch_list / twzrd_watch_remove.

## 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) |
| Free seller graph card | GET /v1/intel/merchant_card/{wallet} | Free | wash_flagged / catalog_enriched / payable_conformance |
| Facilitator kinds + feePayer | GET /supported | Free | twzrd.merchant_attach |
| Settle + free merchant attach | POST /settle | rail fee | merchant_attach + twzrd_receipt |
| Full trust + signed receipt | GET /v1/intel/trust/{pubkey} | 0.05 USDC | reputation_credential.credentialSubject.effectiveTrustScore |
| Merchant track-record receipt | GET /v1/intel/merchant/{pubkey} | 0.05 USDC | attestation_kind=merchant_track_record |
| Market data via MCP | get_solana_market_* tools | Free | - |
| Market data via HTTP | GET /v1/intel/solana_market_* | FREE (discovery; no x402 payment). | - |
| Verify receipt | POST /v1/receipts/verify | Free | result.valid |
| Resource join SOT | GET /v1/intel/resources | Free | callable URL + discovery/counterparty claims |
| Service directory | GET /v1/intel/x402-directory | Free | multi-bazaar overlay by payTo |
| Seller card | GET /v1/intel/merchant_card/{wallet} | Free | wash_flagged / catalog |
| Payer leaderboard (secondary) | 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":"GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs","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/GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs, 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/GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs?seller_wallet=GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs  -> 0.05 USDC. Live trust intel + portable V6 receipt. Proven on mainnet.
- GET https://intel.twzrd.xyz/v1/intel/quick/GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs                                      -> 0.001 USDC. Cheap score + tier snapshot, no full receipt.
- POST https://intel.twzrd.xyz/v1/intel/verify-endpoint  {"url": "https://your-api.example"}  -> 0.05 USDC. SELLER-SIDE: probes YOUR x402 surface (discovery, unpaid-402 conformance, wash screen per resolved payTo) and returns a portable signed AgentReadinessReceipt of what was observed - a failing result is still delivered and still charged, because you are paying for the check, not for a pass. basis=endpoint_conformance, not_a_trust_vouch=true: it is not a trust vouch, it does not affect any ranking, and it is not proof you own the endpoint. Free unsigned equivalent: POST /v1/agent-readiness.
- GET https://intel.twzrd.xyz/v1/intel/solana_market_visibility_map?merchant=GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs        -> FREE (discovery; no x402 payment).
- GET https://intel.twzrd.xyz/v1/intel/solana_market_orderbook_depth?ticker=BTC&merchant=GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs   -> FREE (discovery; no x402 payment).
- GET https://intel.twzrd.xyz/v1/intel/solana_market_shape?ticker=BTC&merchant=GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs      -> FREE (discovery; no x402 payment).
- GET https://intel.twzrd.xyz/v1/intel/solana_market_onchain_trades_summary?merchant=GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs      -> FREE (discovery; no x402 payment).

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=GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs
- 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=GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs   (which x402 facilitators a payer settled through)
- GET  https://intel.twzrd.xyz/v1/intel/get_counterparties?wallet=GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs&limit=10   (capped teaser: top merchants this wallet pays; limit<=25)
- GET  https://intel.twzrd.xyz/v1/intel/compare_wallets?wallet_a=PUBKEY_A&wallet_b=PUBKEY_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.3.0 receipt.json --pubkey 9V6Pn19kiUA5Rn6JpQfNduanvGt2aXGwsarosNfa2Ldf

## Install
- Skill (one URL, save + self-update): https://intel.twzrd.xyz/skill.md
    Tell your agent: "set up https://intel.twzrd.xyz/skill.md". Canonical twzrd-trust
    skill; also on ClawHub: npx clawhub install twzrd-trust
- MCP (24 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: dual Accept (application/json, text/event-stream) is optimal;
    plain application/json, */*, or missing Accept are accepted (server normalizes).
- Auto-pay MCP (local, Solana x402):
    pip install twzrd-mcp
    npx -y twzrd-mcp-server --help
    Auto-pay is disabled by default. Every paying config must set TWZRD_MCP_PAYMENTS_ENABLED=1.
    Minimal Node config: {"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>"}}}}
    Node config: {"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"}}}}
- 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.3.0 receipt.json --pubkey 9V6Pn19kiUA5Rn6JpQfNduanvGt2aXGwsarosNfa2Ldf

## More
No wallet • No signup • Free preflight • Pay only for signed V6 trust receipt.

Get started in <60s:
- Run the free preflight curl above.
- pip install twzrd-mcp (or npm gate wrapper).
- Browse OpenAPI: https://intel.twzrd.xyz/openapi.json
- Verify receipts with npx twzrd-receipt-verifier@^1.3.0 (issuer key:
  https://intel.twzrd.xyz/.well-known/twzrd-receipt-pubkey).

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

## Docs

- [Preflight](https://intel.twzrd.xyz/v1/intel/preflight): free pre-spend gate (POST) - allow/warn/block ReadinessCard before you pay
- [Merchant card](https://intel.twzrd.xyz/v1/intel/merchant_card/GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs): free seller graph card - wash_flagged, observed graph quality, payable_conformance (live_402 + fee_payer_stability)
- [Trust receipt](https://intel.twzrd.xyz/v1/intel/trust/GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs): paid (0.05 USDC) - live trust intel + signed offline-verifiable V6 receipt
- [x402 directory](https://intel.twzrd.xyz/v1/intel/x402-directory): free multi-bazaar service directory indexed by payTo wallet
- [Leaderboard](https://intel.twzrd.xyz/v1/intel/get_top_intel_agents): free payer-corpus leaderboard + corpus_slices
- [Receipt example](https://intel.twzrd.xyz/v1/receipts/example): free sample signed receipt - verify offline before you spend
- [Receipt verify](https://intel.twzrd.xyz/v1/receipts/verify): free (POST) - recompute + check a portable V6 receipt leaf
- [OpenAPI](https://intel.twzrd.xyz/openapi.json): OpenAPI 3.1 with x402 payment annotations for every endpoint
- [MCP](https://intel.twzrd.xyz/mcp): streamable-http MCP server (24 tools, dual Accept headers)
- [Full reference](https://intel.twzrd.xyz/llms-full.txt): this document plus the complete tool + endpoint contract

## Optional

- [Health](https://intel.twzrd.xyz/health): service health - package_version, gate status
- [Service descriptor](https://intel.twzrd.xyz/.well-known/x402): machine-readable x402 service card

## Trust gate semantics (twzrd-agent-intel service v0.5.6)
- v0.5.6 is THIS service's package version (PyPI: twzrd-agent-intel; live value
  at /health package_version). It is NOT the version of the npm buyer-side gate
  (twzrd-x402-gate) or any other client SDK - those are versioned independently.
- 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 (Path A paid trust/market routes only): blocks x402 settlement when
  TWZRD_SETTLE_GATE_ENABLED=true and seller counterparty score is below threshold.
  Refusal requires settle_gate_enabled=true AND settle_gate_shadow=false: with shadow on,
  a would-block is only logged (measure-don't-enforce) and the payment settles. Read
  settle_gate_enforcing from GET /health for the resolved posture - settle_gate_enabled
  alone does not mean you can be refused.
  It is runtime config and changes without a release. Supply the counterparty per call so
  the armed path works in any posture:
  ?merchant= (market routes) or ?seller_wallet= / X-TWZRD-Seller-Wallet (trust route).
  Settle rail POST /settle is a separate cosign+attach rail; it does not run settle_gate.
- Client hook: packages/twzrd-agent-intel/verifier/on_before_settle.py (preflight before pay).
- MCP registry auth key (/.well-known/mcp-registry-auth) is NOT the receipt-signing key (/.well-known/twzrd-receipt-pubkey).

## Integration variants and optional operator policies

The canonical `installTwzrdAutoGate` buyer install is near the top of this document (alias: `installTwzrdX402ClientHook`).
These are secondary framework adapters and operator policies. The gate core is
dependency-free (no @elizaos/core required). Buyer gate defaults fail-closed on preflight outage
(TWZRD_FAIL_OPEN=true opts into legacy fail-open); merchant_card wash checks fail-open when
the card is unreachable (no invent wash).

  npm install @wzrd_sol/plugin-trustgate@^0.3.4  # elizaOS plugin + facilitator hook

Do not install twzrd-x402-gate@0.5.4 — that pin is stale (old attribution CLIENT_VERSION
drift era). Prefer @0.8.6 or check the registry first:
`npm view twzrd-x402-gate version` / `pip index versions twzrd-mcp`. Explicit
minimum-version pins stated in this document (e.g. twzrd-receipt-verifier>=1.2.0
for V6 leaves) still apply. The live /health package_version field is the
**twzrd-agent-intel service** (PyPI), not the npm gate version — they move independently.

### Wrap any fetch that may receive a 402
  import { wrapFetchWithTwzrdGate } from "twzrd-x402-gate";
  const gated = wrapFetchWithTwzrdGate(fetch);
  // THROWS on block-rated merchant 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 merchants)
  import { createTwzrdGate } from "twzrd-x402-gate";
  const gate = createTwzrdGate({
    onWarnUpsell: (ctx) => paidFetch("https://intel.twzrd.xyz" + ctx.upsellUrl),
  });

### Facilitator operators (screen the MERCHANT on every brokered settlement)
  import { createOnBeforeSettleHook } from "@wzrd_sol/plugin-trustgate/facilitator";
  const facilitator = createFacilitator({
    hooks: { onBeforeSettle: createOnBeforeSettleHook() },
  });
  // Buyer-side counterparty check at the rail: score payTo before settle.

### Resource-server operators (optional merchant policy on the PAYER)
  // Optional settle hook (0.8.x) — not an equal product to the buyer gate. Settled USDC is final.
  // Use for abuse / sanctions / bots / customer selection before you settle and serve.
  // Wash resistance is mainly TWZRD scoring (discount bad edges), not forced revenue rejection.
  import { createTwzrdSettleGuard, twzrdPayerScreen } from "twzrd-x402-gate";
  import { x402ResourceServer } from "@x402/core/server";
  const server = new x402ResourceServer(facilitator);
  server.onBeforeSettle(createTwzrdSettleGuard({ screen: twzrdPayerScreen() }));
  // Default abort: wash_flagged or decision=block; warn continues. Free merchant_card screen.
  // Paid /v1/intel/trust screening is inject-your-own screen (not defaulted — per-payment cost).

# 🛡️ 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/GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs">

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

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

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)


## Full MCP tools reference (24)
1) get_readiness_card_tool(resource_name?, seller_wallet?, resource_url?, price_usdc?, buyer_wallet?, agent_intent?, marketplace_score?)
   - Pre-spend readiness card: decision/can_spend/trust_score/proof/caveats/next_fixes + root_provenance (for WZRD protocol resources: onchain_match:null, optional market_velocity when the market data service is configured).
2) evaluate_x402_resource(resource_url, method?)
   - One-shot URL guard: fetch the resource URL, extract the 402 seller wallet (Solana preferred), run free preflight, return decision/trust_score/seller_wallet/receipt_url. Use when you have a URL but not the seller wallet.
3) low_level_preflight(resource_name?, seller_wallet?, price_usdc?, agent_intent?, marketplace_score?)
   - Lower-level preflight with max_spend_recommendation_usdc and paid_trust_endpoint hints.
4) verify_root_inputs(root_seq?, resource_name?, seller_wallet?)
   - Free MCP + GET /v1/intel/verify_root: fetches public leaves, recomputes every GLOBAL_V5 leaf + sorted-pair merkle + dataset_hash. Returns PASS|FAIL|ERROR + leaf_hash_match. onchain_match=null on ReadinessCard.root_provenance tells agents to call this before deposit/claim/settle. Canonical samples for hermetic tests.
5) score_wallet_for_intel(wallet)
   - Free wallet intel score from x402 payment-history signals.
6) get_top_intel_agents(limit=10, min_paid_calls=0, max_days_since_last=None)
   - Free leaderboard of active x402 payer wallets; behavioral cohort, not identity proof.
7) get_solana_market_visibility_map()
   - Market visibility map for Solana market activity.
8) get_solana_market_orderbook_depth(ticker)
   - Orderbook depth/liquidity by ticker.
9) get_solana_market_shape(ticker)
   - Market structure signals by ticker.
10) get_solana_market_onchain_trades_summary(ticker=None)
   - Recent on-chain trades summary (global or per ticker).
11) get_solana_market_status()
   - Market data-service health/status.
12) get_provider_reputation(merchant)
   - Free provider/merchant reputation from the observed x402 corpus.
13) get_merchant_card(wallet)
   - Free merchant card: observed receive-side graph quality (offering unknown unless catalog-enriched; not identity or demand proof). Includes payable_conformance (live_402 density, fee_payer_stability: stable|rotating|unknown). Listed ≠ live_402.
14) is_wash_fleet(wallet)
   - Free wash/sybil-fleet check on a single wallet.
15) verify_receipt(receipt, require_signature?, max_age_seconds?)
   - Free offline v6 receipt verification: recompute the keccak256 leaf + check the Ed25519 signature. Optional max_age_seconds (>0) rejects stale receipts (replay protection).
16) get_facilitator_footprint(wallet)
   - Free discovery: which x402 facilitators a payer has settled through (1 = thin/captive).
17) get_counterparties(wallet, limit=10)
   - Free discovery (capped teaser): top merchants a wallet pays (limit<=25).
18) score_wallets_batch(wallets)
   - Free discovery: score up to 25 wallets in one call.
19) compare_wallets(wallet_a, wallet_b)
   - Free discovery: side-by-side intel for two wallets by wash-discounted effective_score.
20) get_x402_directory(flagged_only?)
   - Free discovery: multi-bazaar x402 service directory (PayAI + CDP + Agentic Market) indexed by payTo wallet, with Solana wash/reputation overlay where applicable. Base/Polygon listings shown with honest "unavailable" flag (no cross-chain scoring yet).
21) twzrd_demo_gate(integration?, run_id?)
   - Runnable no-spend proof of the buyer-side x402 trust gate: returns a deterministic transcript (block path aborts, wallet/signer never contacted, ok=true). Spends nothing, contacts no wallet, needs no human. Surfaces an EXTERNAL_RUN candidate (not proof) tagged with your inbound IP + run_id.
22) twzrd_watch_add(payer_wallet, seller_wallet, webhook_url?)
   - Register a re-call watch: TWZRD re-checks the seller when recheck_after_unix elapses and POSTs event twzrd.watch.recheck_due to your webhook when the score/decision materially changes. webhook_url optional - omit for poll-only.
23) twzrd_watch_list(payer_wallet)
   - List your active re-call watches with current score/decision and recheck_after_unix (webhook URLs masked to host).
24) twzrd_watch_remove(watch_id, payer_wallet)
   - Deactivate a re-call watch by ID; payer_wallet must match the watch owner.

## Full x402 flow (paid HTTP endpoints)

Easiest path — let a payer client handle 402 + settle for you. This is the same
command the 402 body returns as `next_action.command`:

```
# one-time: create and fund a wallet (needs >= 0.05 USDC on Solana)
npx agentcash@latest onboard
npx agentcash@latest balance

# then pay any TWZRD paid route in one call
npx agentcash@latest fetch 'https://intel.twzrd.xyz/v1/intel/trust/GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs'
```

Without a funded wallet that command fails at SETTLE, not at the gate — the 402
is served to everyone, so "I got a 402" does not mean you were refused.

Hand-rolled alternative (any x402 client + your own signer):
1. Request paid endpoint without payment header.
2. Receive HTTP 402 with `payment-required` header.
3. Decode challenge and choose `accepts` payment requirement.
4. Build/sign payment payload using x402 client + wallet.
5. Retry same request with `payment-signature` header.
6. Receive paid JSON payload (includes tx anchor and route data; full trust includes signed V6 receipt fields).

Challenge example (runnable as-is; substitute your own pubkey when you have one):
curl -i -s https://intel.twzrd.xyz/v1/intel/trust/GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs

Python header inspection:
python3 - <<'PY'
import requests
u = "https://intel.twzrd.xyz/v1/intel/trust/GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs"
r = requests.get(u, timeout=15)
print(r.status_code)
print(r.headers.get("payment-required"))
PY

## Endpoint reference with request/response examples
- GET /v1/intel/trust/{pubkey} (paid 0.05 USDC)
  - 402 when unpaid; 200 keys: pubkey, trust, paid, network, tx/tx_pending, twzrd_receipt|receipt_error
- GET /v1/intel/quick/{pubkey} (paid 0.001 USDC)
  - Cheap tier snapshot: score/tier basics; no full signed receipt.
- GET /v1/intel/solana_market_visibility_map (paid FREE (discovery; no x402 payment).)
- GET /v1/intel/solana_market_orderbook_depth?ticker=SOL (paid FREE (discovery; no x402 payment).)
- GET /v1/intel/solana_market_shape?ticker=SOL (paid FREE (discovery; no x402 payment).)
- GET /v1/intel/solana_market_onchain_trades_summary[?ticker=SOL] (paid FREE (discovery; no x402 payment).)
- POST /v1/intel/preflight (free)
  request: {"resource_name":"Jupiter Quote Preview","price_usdc":0.01}
  response: readiness_card + paid_trust_endpoint hints
- POST /v1/receipts/verify (free)
  request: {"leaf":"<hex>","preimage":{...},"signature":"<hex>","signing_pubkey":"9V6Pn19kiUA5Rn6JpQfNduanvGt2aXGwsarosNfa2Ldf"}
  response: ok, version, result
- GET /v1/intel/score_wallet_for_intel?wallet={wallet} (free)
- GET /v1/intel/get_top_intel_agents?limit=10[&min_paid_calls=2&max_days_since_last=14] (free)
- GET /v1/intel/get_facilitator_footprint?wallet={wallet} (free)
- GET /v1/intel/get_counterparties?wallet={wallet}&limit=10 (free; limit<=25)
- GET /v1/intel/compare_wallets?wallet_a=PUBKEY_A&wallet_b=PUBKEY_B (free)
- POST /v1/intel/score_wallets_batch (free)
  request: {"wallets":["GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs", "GFpLvocNdEjnSsLH3VJQL6wGcjGxTbUBrj6fqN3Qe1Gs"]} (up to 25)
- GET /health (free)
- Discovery: /, /.well-known/x402, /.well-known/x402.json, /.well-known/agent-card.json,
  /.well-known/mcp, /.well-known/mcp.json, /.well-known/mcp-server.json,
  /mcp/agent-intel-mcp-card.json, /openapi.json, /llms.txt, /llms-full.txt

## Integration guide for LLM agents
- Read /llms.txt for quick orientation.
- Read /llms-full.txt for complete tool + endpoint contract.
- Parse /openapi.json for machine-readable schemas.
- Always call POST /v1/intel/preflight before paid actions.
- Only pay when decision/risk is acceptable.
- Persist tx + receipt fields from paid responses.
- Verify receipts via POST /v1/receipts/verify (or offline verifier).