# TWZRD Agent Intel — Agent Orientation

## Live Server
- **MCP endpoint:** `https://intel.twzrd.xyz/mcp` (streamable HTTP, 23 tools)
- **HTTP API:** `https://intel.twzrd.xyz/v1/intel/...`
- **Agent Card:** `https://intel.twzrd.xyz/.well-known/agent-card.json`
- **OpenAPI:** `https://intel.twzrd.xyz/openapi.json`

## Core Flow

Before paying any x402 endpoint:
1. Call `get_readiness_card_tool(seller_wallet="...")` — free
2. If `decision == "block"` → DO NOT PAY
3. If `decision == "warn"` → optional: buy paid trust receipt ($0.05)
4. If `decision == "allow"` → proceed with payment
5. After payment → `verify_receipt(receipt)` to check the signed proof

## 🛡️ Self-Serve Trust Badges (free, embeddable, cacheable)

Add instant credibility to your Smithery / CDP Bazaar / marketplace listing with a one-line image embed:

- **Wash trust badge:** `<img src="https://api.twzrd.xyz/v1/wash/badge/YOUR_WALLET">`
  Shows real-time wash detection score for your wallet. Auto-updates hourly.
- **Provider reputation badge:** `<img src="https://api.twzrd.xyz/v1/reputation/badge/YOUR_WALLET">`
  Dynamic provider reputation tier from the live provider_reputation engine.
- **Full reputation report:** `POST https://api.twzrd.xyz/v1/reputation/analyze`
  Body: `{"wallet":"YOURS","merchants":["MERCHANT_PUBKEY"]}`
  Returns tier, confidence, evidence (heavy-fleet CV, captive payer %, revenue).

Both badges are free, require no API key, and cache with `Cache-Control: public, max-age=3600`.

## All Free Tools

- `get_readiness_card_tool` — primary pre-spend gate
- `evaluate_x402_resource` — fetch URL + extract seller + preflight
- `low_level_preflight` — richer preflight with evidence
- `get_solana_market_status` — backend health probe
- `get_solana_market_visibility_map` — active settlement markets
- `get_solana_market_orderbook_depth` — liquidity depth per ticker
- `get_solana_market_shape` — market structure signals
- `get_solana_market_onchain_trades_summary` — recent trades
- `score_wallet_for_intel` — wallet intel score (0-100)
- `get_top_intel_agents` — active agent leaderboard
- `get_provider_reputation` — seller-side reputation tier
- `is_wash_fleet` — circular-flow wash check
- `verify_receipt` — offline receipt verification
- `get_facilitator_footprint` — facilitator breadth
- `get_counterparties` — who a wallet pays
- `score_wallets_batch` — batch score (up to 25)
- `compare_wallets` — side-by-side comparison
- `verify_root_inputs` — WZRD protocol root verification

## Receipts API (query + verify + export)

- `GET /v1/receipts` — query receipts by wallet, date range, tx hash
- `GET /v1/receipts/:id` — single receipt detail
- `POST /v1/receipts/verify` — offline V6 receipt verification
- `POST /v1/receipts/export` — bulk export (CSV/JSON)

## Spend Authorization (Surface #1)

Every MCP paid tool call (quick_trust at $0.001, full_trust at $0.05) now POSTs to `/v1/spend/authorize` before x402 payment. In shadow mode all calls are authorized and logged. Signals: wallet reputation (wash), provider reputation, velocity caps, policy match.

- `POST /v1/spend/authorize` — multi-signal gate
- `GET /v1/spend/policy/:wallet` — read wallet policy
- `PUT /v1/spend/policy/:wallet` — set wallet policy
- `GET /v1/spend/stats` — shadow mode metrics

## Pricing

Free MCP tools, free badge embeds, free receipt verification. Paid x402 surfaces:
- `GET /v1/intel/trust/{pubkey}` (0.05 USDC) — full renorm model + signed V6 receipt
- `GET /v1/intel/quick/{pubkey}` (0.001 USDC) — quick tier+score
- Market data routes (0.03 USDC each)
- Spend authorization check (free, pre-payment)

## Source
- Public repo: https://github.com/twzrd-sol/twzrd-trust
- Scoring engine (intel_scoring, wash_signal, trust_renorm): private
- MCP auto-pay server (npm): twzrd-mcp-server@0.4.0 (TWZRD_RPC_URL required for paid)
- MCP auto-pay server (PyPI): twzrd-mcp@0.1.6

## Live Mainnet Proof
- Settle tx: `5inMkSPpe9v3jD7ca3VZpTV6kHnqBU8mNgDwAysBvUFN4YapspeCTZZFcrTwAU73vr5Ec2FUFqxiM8jdBjFFwtda`
- Evidence: `docs/launch/evidence/twzrd-mcp-settle-proof-2026-06-26T02-57-57Z.md`
