Metadata-Version: 2.4
Name: twzrd-agent-intel
Version: 0.1.0
Summary: Trust + receipt layer that Solana agents call before and after paying over x402 — free preflight readiness cards, paid signed V5 trust receipts, and a wash/Sybil-resistant agent reputation corpus. MCP + HTTP.
Author-email: twzrd <twzrd@twzrd.xyz>
License: MIT
Project-URL: Homepage, https://intel.twzrd.xyz
Project-URL: Documentation, https://intel.twzrd.xyz/llms.txt
Project-URL: Agent Card, https://intel.twzrd.xyz/.well-known/agent-card.json
Project-URL: MCP Card, https://intel.twzrd.xyz/.well-known/mcp.json
Project-URL: Public Leaderboard, https://twzrd.xyz/leaderboard
Project-URL: Repository, https://github.com/twzrd-sol/wzrd-final
Keywords: x402,agent,agentic-commerce,reputation,trust,solana,micropayments,usdc,mcp,preflight,readiness-card,receipts,ai-agents,autonomous-agents
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.104
Requires-Dist: uvicorn[standard]>=0.24
Requires-Dist: pydantic>=2.0
Requires-Dist: httpx>=0.25
Requires-Dist: python-dotenv>=1.0
Requires-Dist: solders>=0.21
Requires-Dist: solana>=0.36
Requires-Dist: x402[fastapi,svm]>=0.4.2
Requires-Dist: mcp>=1.10.1
Requires-Dist: pycryptodome>=3.20
Requires-Dist: psycopg2-binary>=2.9
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: mypy>=1.5; extra == "dev"

# twzrd-agent-intel

**The trust + receipt layer that Solana agents call before and after paying over x402.**

Before an autonomous agent pays a stranger's API, it should be able to answer one
question: *should I pay this, and what proof will I get?* `twzrd-agent-intel` answers
it. Free **preflight readiness cards** score any x402 resource on a wash/Sybil-resistant
reputation corpus; a paid **trust endpoint** returns a portable, offline-verifiable
**signed V5 receipt**. Live on Solana mainnet.

- Live API: https://intel.twzrd.xyz
- Public agent leaderboard: https://twzrd.xyz/leaderboard
- Agent card: https://intel.twzrd.xyz/.well-known/agent-card.json
- MCP card: https://intel.twzrd.xyz/.well-known/mcp.json

---

## Install

```bash
pip install twzrd-agent-intel
```

This installs the MCP server console script `twzrd-agent-intel-mcp` and the Python
package `twzrd_agent_intel`.

## Two surfaces, same data

| Surface | Best for | How to reach |
|---------|----------|--------------|
| **MCP** (recommended) | Claude Code, agent frameworks, tool-calling agents | `twzrd-agent-intel-mcp` (stdio) or `--sse` |
| **HTTP** | Direct calls, custom routers, testing | `POST /v1/intel/preflight` (free), `GET /v1/intel/trust/{pubkey}` (0.05 USDC) |

## 60-second flow: don't pay blind

The canonical pattern a well-behaved agent follows before spending:

1. Call the **free** preflight with the resource you're about to pay and your intent.
2. Inspect `decision`, `can_spend`, and `trust_score`. Fail closed on `block`.
3. If you proceed and want durable proof, fetch the **paid** trust receipt and store
   the V5 leaf + preimage for later offline verification or on-chain anchoring.

```bash
# 1. Free preflight against the live mainnet API
curl -s -X POST https://intel.twzrd.xyz/v1/intel/preflight \
  -H "Content-Type: application/json" \
  -d '{
    "resource_name": "Jupiter Quote Preview",
    "seller_wallet": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
    "agent_intent": "swap_quote"
  }'
```

Returns the canonical `ReadinessCard` (`decision`, `trust_score`, `can_spend`, `proof`,
`caveats`, `next_fixes`, and the `paid_deep_dive` path).

```bash
# 2. Verify a signed receipt offline BEFORE you ever spend — free sample, no wallet
curl -s https://intel.twzrd.xyz/v1/receipts/example
```

The paid deep dive (`GET /v1/intel/trust/{pubkey}`, 0.05 USDC over x402) returns the
full trust object plus a portable, Ed25519-signed V5 receipt leaf you can verify
without trusting our server.

## MCP: wire into Claude Code / Claude Desktop

```json
{
  "mcpServers": {
    "twzrd-agent-intel": {
      "command": "twzrd-agent-intel-mcp",
      "type": "stdio"
    }
  }
}
```

After restart, agents see tools including:

- `get_readiness_card_tool` — **primary**; returns the canonical ReadinessCard shape
- `dexter_preflight` — lower-level (full evidence, `max_spend_recommendation_usdc`, upsell)
- `get_top_intel_agents` — agent leaderboard discovery
- DFlow market-intelligence tools (orderbook depth, visibility map, market shape)

The paid trust receipt is intentionally exposed over HTTP x402, not MCP.

## Run the servers locally

```bash
# MCP (stdio — default for most agents)
twzrd-agent-intel-mcp
# MCP over SSE (remote / web agents)
twzrd-agent-intel-mcp --sse
# HTTP server
uvicorn twzrd_agent_intel.server_http:app --port 8001
```

## Signal sources

By default the surface uses a small static research registry (good for testing). Point
it at live data with environment variables:

| `TWZRD_SIGNAL_SOURCE` | What it does |
|-----------------------|--------------|
| `artifacts` | Aggregate your own real settlement volume from `TWZRD_ARTIFACTS_DIR` |
| `bazaar` | Pull the live cross-facilitator x402 catalog (CDP Bazaar `/resources` + `/merchant`) |

TWZRD is the **judgment layer** ("should this agent pay?") on top of the public x402
directories — it does not duplicate the listing function. Combine `bazaar` (discovery)
with `artifacts` (your receipt volume) for the strongest signal.

## What makes the score trustworthy

- **Wash/Sybil-resistant**: circular-flow and reciprocal-wash discounting on a 42k-wallet
  cross-facilitator corpus; breadth floor on counterparties.
- **Honest basis**: trust components are renormalized (`score_version intel_renorm_v1`) so
  arbitrary wallets aren't penalized for lacking TWZRD-native execution history.
- **Verifiable**: every paid response carries a signed V5 receipt; verify it offline with
  the free `/v1/receipts/example` + `/v1/receipts/verify` endpoints before you trust the
  paid path.

## License

MIT
