# TWZRD Agent Intelligence

TWZRD is the independent scorer on the real Solana x402 payer graph. We observe
cross-facilitator x402 payment behavior across the Solana ecosystem and score it, so an agent can qualify a counterparty BEFORE paying
it. It is a discovery + trust surface, not another way to pay.

## Before every x402 payment — 5 steps

1. Free preflight    POST https://intel.twzrd.xyz/v1/intel/preflight
                     body: {"seller_wallet":"<seller>","price_usdc":<amount>}
                     → readiness_card.decision  (MCP: get_readiness_card → decision)
2. decision=block  → abort. Do not pay. Skip all remaining steps.
3. decision=warn, OR payment >= $1.00, OR seller has < 3 known counterparties
   → buy $0.05 trust receipt:
     GET https://intel.twzrd.xyz/v1/intel/trust/{pubkey}?seller_wallet=<seller>
4. Route on reputation_credential.credentialSubject.effectiveTrustScore
     < 30 → block  |  30-60 → warn  |  > 60 → allow
5. Then, and only then, sign the x402 / Solana / Base payment.

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          (elevated risk confirmed)
  Always buy if   seller has < 3 known counterparties (thin history)
  Skip if         decision = allow + payment < $0.10 + seller is well-known
  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)
curl -s 'https://intel.twzrd.xyz/v1/intel/get_top_intel_agents?limit=1'
# one self-consistent JSON: agents[0] (top-scored x402 payer) + total_payers_observed
# + corpus_slices (denoised view) + leaderboard_note. No auth, no payment.

TWZRD is the independent scorer on the real Solana x402 payer graph. We observe
cross-facilitator x402 payment behavior across the Solana ecosystem and score it. Free discovery tools let an agent qualify a
counterparty BEFORE paying it; the free score already gives the number. 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). It is a discovery + trust surface for x402 agents on Solana,
not another way to pay.

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

## One-command demo (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}'

## 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.0.7 (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.0.7'   # then: twzrd-verify-receipt receipt.json --pubkey 9V6Pn19kiUA5Rn6JpQfNduanvGt2aXGwsarosNfa2Ldf
  npx twzrd-receipt-verifier@1.0.7 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.
- 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.0.7 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
- Live mainnet proof tx: 3aXGtvmNvFhSSDXF8D4DBDntXFczraUABg75MdWtCgchdYAApRwC7KxdGxbCmewYcA6ZNzw6FvdAHcoevMUG44Sc
- Live at https://intel.twzrd.xyz | health: /health (package_version, gate status)

## 0.5.1 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() },
  });