Metadata-Version: 2.4
Name: twzrd-agent-intel
Version: 0.3.5
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
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.

## Try it now (no install, no signup)

```bash
curl -s -X POST https://intel.twzrd.xyz/v1/intel/preflight \
  -H "Content-Type: application/json" \
  -d '{
    "seller_wallet": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
    "agent_intent": "swap_quote"
  }'
```

Returns a `ReadinessCard` with `decision` (`allow` / `warn` / `block`), `trust_score`,
`can_spend`, `caveats`, and the path to the paid deep-dive receipt.

## Install

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

## Wire into Claude Code / Claude Desktop / Cursor (60 seconds)

Add to your MCP config and restart. The remote server runs the live 42k-wallet corpus —
no env vars, no local server, no configuration:

```json
{
  "mcpServers": {
    "twzrd-agent-intel": {
      "type": "streamable-http",
      "url": "https://intel.twzrd.xyz/mcp"
    }
  }
}
```

After restart your agent sees 17 tools. The most useful one to call first:

```
get_readiness_card_tool(seller_wallet="6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P")
```

That's the full install. No database, no keypair, no USDC needed for the free tools.

## 17 MCP tools

**Free preflight + discovery (no payment, no auth):**
- `get_readiness_card_tool` — primary ReadinessCard
- `dexter_preflight` — lower-level preflight + spend recommendation
- `score_wallet_for_intel` — wallet intel score
- `get_top_intel_agents` — agent leaderboard discovery

**Free corpus reputation + receipts:**
- `get_provider_reputation` — inbound corpus reputation for a seller/merchant wallet
- `is_wash_fleet` — circular-flow / wash-fleet check on a wallet
- `get_facilitator_footprint` — which x402 facilitators a payer settled through
- `get_counterparties` — capped teaser: top merchants a wallet pays (limit ≤ 25)
- `score_wallets_batch` — score up to 25 wallets in one call
- `compare_wallets` — side-by-side intel for two wallets
- `verify_receipt` — offline V5 receipt verification (recompute leaf + check Ed25519 sig)
- `verify_root_inputs` — independently recompute a published attention root and assert against the on-chain commitment

**Solana market intel (free over MCP; $0.03 USDC each over HTTP x402):**
- `get_solana_market_visibility_map`
- `get_solana_market_orderbook_depth`
- `get_solana_market_shape`
- `get_solana_market_onchain_trades_summary`
- `get_solana_market_status`

The paid trust receipt (`GET /v1/intel/trust/{pubkey}`, 0.05 USDC over x402) is also
available over HTTP with a portable signed V5 receipt you can verify offline.

## HTTP API

```bash
# Free preflight (no payment required)
curl -s -X POST https://intel.twzrd.xyz/v1/intel/preflight \
  -H "Content-Type: application/json" \
  -d '{"seller_wallet": "<pubkey>", "agent_intent": "swap_quote"}'

# Paid trust receipt (0.05 USDC over x402 — use an x402-capable client)
curl -s https://intel.twzrd.xyz/v1/intel/trust/<pubkey>
# → 402 Payment Required with payment requirements if no x402 header

# Free sample receipt for offline verify testing
curl -s https://intel.twzrd.xyz/v1/receipts/example
```

- OpenAPI: https://intel.twzrd.xyz/openapi.json
- Agent card: https://intel.twzrd.xyz/.well-known/agent-card.json
- MCP card: https://intel.twzrd.xyz/.well-known/mcp-server.json

## Self-hosting

> **Note**: Running `twzrd-agent-intel-mcp` locally serves from a small static research
> registry by default — not the live 42k-wallet corpus. Use the remote MCP above for
> real data. Self-host only if you need to run behind a firewall or extend the server.

```bash
# Local MCP stdio (static demo data by default)
twzrd-agent-intel-mcp

# Local HTTP server
uvicorn twzrd_agent_intel.server_http:app --port 8001
```

Point a self-hosted instance at live data with environment variables:

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

## 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 you can verify offline
  at `/v1/receipts/verify` without trusting our server.

## More TWZRD surfaces

- **Verify a live receipt offline in one command** (TypeScript SDK, no wallet):
  ```bash
  npx @wzrd_sol/sdk
  ```
- **OpenClaw agents**: install the skill that wraps this API into a pre-payment check:
  ```bash
  clawhub install twzrd-trust
  ```

## License

MIT

- Public leaderboard: https://twzrd.xyz/leaderboard

<!-- mcp-name: io.github.twzrd-sol/twzrd-agent-intel -->
<!-- mcp-name: xyz.twzrd.intel/twzrd-agent-intel -->
