Metadata-Version: 2.4
Name: twzrd-agent-intel
Version: 0.4.1
Summary: Trust + receipt layer that Solana agents call before and after paying over x402 — free preflight readiness cards, paid signed trust receipts, and a wash/Sybil-resistant agent reputation corpus. MCP + HTTP.
Author-email: twzrd <privacy@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 receipt**. Live on Solana mainnet.

## Ingest the corpus (registries / scorers / facilitators)

The package builds and serves the only live cross-facilitator x402 payer corpus on
Solana. Pull the scored signal population as a feed — no auth, paginated, wash-discounted —
to ingest into your own reputation system:

    curl -s 'https://intel.twzrd.xyz/v1/intel/corpus_feed?limit=5' | jq .

Each row carries the intel score, the wash-discounted effective score, the wash flag, and
the component breakdown; page with `next_offset` until null. See it run in your browser at
https://twzrd.xyz/demo/ingest/ , the full schema in the API docs
(https://intel.twzrd.xyz/docs), and the ingestion-pilot path on https://twzrd.xyz/grants .
Email privacy@twzrd.xyz with your use case.

## Where this sits

Autonomous agents hold wallets and pay strangers over x402 — no human gut-check. At
pay time a wash seller looks identical to an honest one. TWZRD is the wedge that scores
the seller before the agent signs.

```text
  AGENTS (spend)   live cross-facilitator x402 graph (~75k payers observed)
        │  "should I pay this seller?"  ── no reputation rail exists
        v
  ┌────────────────────  TWZRD TRUST LAYER  ────────────────────┐
  │  POST /v1/intel/preflight  (free)                           │
  │    - known registry + corpus wash detection for indexed     │
  │      sellers → allow / warn / BLOCK                        │
  │    - unknown sellers (not in TWZRD corpus) → warn/45.0     │
  │                       (not a bad signal — just unknown)     │
  │  GET /v1/intel/trust/{wallet}  (paid, 0.05 USDC)           │
  │    - full corpus renorm + signed receipt → definitive    │
  │  CONSUMABLE: plugin-trustgate (npm) · MCP · PyPI · verifier │
  └──────────────────────────────┬──────────────────────────────┘
          allow / warn            │             BLOCK
                │                 │               │
                v                 │               v
  RAILS THAT SETTLE (PayAI · openfacilitator · x402)    ╳ agent ABORTS
        │
        v
  SELLERS    honest organic    wash-shaped tail (corpus-indexed)
             7uh2ibD1          34w53Ukh (known via paid surface)
             → free: WARN      → paid: BLOCK (wash_flagged, 91% captive)
             → paid: ALLOW     → free: WARN/default_no_data
             (broad organic    (not indexed in free registry)
              counterparties)
```

**What the free preflight discriminates on:** Sellers indexed in TWZRD's corpus (settlement
events ingested from tracked facilitators) trigger wash detection and tier scoring. The wash
seller `34w53Ukh` (91.4% captive payers, real shopper paid it ~$7,957) → `block` on the paid
surface and through the `evaluate_settle_gate`. On the free preflight, sellers outside the
current registry return `warn/default_no_data` — unknown, not bad.

**Paid surface = definitive.** `GET /v1/intel/trust/{wallet}` runs the full renorm model
against the x402 receipt corpus. For high-value decisions or unknown sellers above your risk
threshold, use the paid surface.

**Honest frontier.** The **buyer preflight** gates spending today. The **settle-side** hook
(`onBeforeSettle`) is next — it runs inside the facilitator before the payment settles, so
even a buyer with no TWZRD integration gets protection from the seller's side.

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

**One command (no install):**

```bash
# pipx (Python — this package)
pipx run twzrd-agent-intel preflight 6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P

# npx (Node.js — standalone, zero-dependency, no Python required)
npx twzrd-preflight 6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P
```

The `npx twzrd-preflight` path is a separate zero-dependency Node package
([`twzrd-preflight`](https://www.npmjs.com/package/twzrd-preflight)) that calls the
same free preflight over HTTP — it does **not** require Python. Both front doors
share exit-code semantics so they are interchangeable in shells and CI.

**Or via curl (no runtime at all):**

```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.

### CLI reference

```
usage: twzrd-preflight <seller_wallet_or_resource_name> [options]

positional:
  <wallet>            Base58 seller wallet pubkey
  <resource_name>     Resource name, e.g. "Jupiter Quote Preview"

options:
  --seller-wallet     Explicit seller wallet (alternative to positional)
  --wallet            Your queried wallet pubkey (attribution)
  --intent            Brief intent string (e.g. "swap_quote")
  --max-spend USDC    Budget hint in USDC
  --json              Raw JSON output (machine-readable)
  --timeout N         HTTP timeout seconds (default: 20)

exit codes:  0=allow/warn (safe to proceed)  1=block (do not pay)  2=usage/network error
```

Compose in CI or a shell: `twzrd-preflight $SELLER && pay-the-invoice`. `warn`
exits 0 because unknown sellers default to `warn` (score 45) — only an explicit
`block` halts the pipeline.

## Install

**Requires Python >= 3.11.** On 3.10 or older, `pip install` fails with
`No matching distribution found` — that is the version floor, not a broken package.
Check with `python3 --version`; on 3.10 use a 3.11+ interpreter (`python3.11 -m venv ...`).

```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 x402 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
- `low_level_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 signed 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 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 x402 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
  cross-facilitator corpus; breadth floor on counterparties. Read
  `/v1/intel/get_top_intel_agents?limit=1` for current corpus counts.
- **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 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 -->
