Metadata-Version: 2.4
Name: twzrd-agent-intel
Version: 0.5.9
Summary: Pre-spend x402 counterparty reputation from observed behavior, with free preflight, signed V6 receipts, and a hosted MCP server.
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
Project-URL: Source Code, https://github.com/twzrd-sol/twzrd-trust
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.37,>=0.36
Requires-Dist: x402[evm,fastapi,svm]<2.14,>=2.13
Requires-Dist: mcp<2,>=1.10.1
Requires-Dist: pycryptodome>=3.20
Requires-Dist: psycopg2-binary>=2.9
Requires-Dist: redis>=5.0.0
Requires-Dist: prometheus-client>=0.20
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"
Requires-Dist: pynacl>=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 answer: *what am I
buying, should I pay this seller, and what proof will I get?* `twzrd-agent-intel`
answers that. Free **resource join** inventorizes callables; free **preflight**
returns allow/warn/block on the seller; a paid **trust endpoint** returns a portable,
offline-verifiable **signed v6 receipt**. Live on Solana mainnet.

## Where this sits

TWZRD is a buyer-side reputation rail at the payment boundary. **Services come from
bazaar / resource-join discovery first**; settlement trust then enriches the
`pay_to` wallet when it appears in the Solana x402 corpus. The settlement graph is
**not** a service catalog. Corpus wallets are ecosystem observations — not TWZRD
customers, usage, or revenue. Read live counts from
[`/health`](https://intel.twzrd.xyz/health) and
[`get_top_intel_agents?limit=1`](https://intel.twzrd.xyz/v1/intel/get_top_intel_agents?limit=1)
instead of frozen README snapshots.

**Core product** is the buyer gate: free ReadinessCard + wash refusal on the
**merchant** (`payTo`) before spend. Optional on npm `twzrd-x402-gate@0.8.19`
(canonical: `installTwzrdAutoGate`, also `"mpp"`):
resource-server `createTwzrdSettleGuard` / `twzrdPayerScreen` for **merchant policy** on
the *payer* before settle+serve (abuse/sanctions/bots) — not an equal mirror of the buyer
problem; wash resistance is mainly TWZRD scoring. Facilitator operators use
`@wzrd_sol/plugin-trustgate/facilitator` `createOnBeforeSettleHook` to screen the
*merchant* on brokered settle.

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

**Resource → seller → preflight** (discover callables, then score the payee):

```bash
# 1) resource join SOT — listed | live_402 claims; settlement overlay separate
curl -s "https://intel.twzrd.xyz/v1/intel/resources?limit=5" | jq '.honesty, .stats, .resources[0].resource_url'

# 2) multi-bazaar overlay (optional; Base/Polygon wash often unknown)
# curl -s "https://intel.twzrd.xyz/v1/intel/x402-directory?limit=20"

# 3) free merchant graph card (refuse when wash_flagged is true; null = never evaluated, route on next_action)
curl -s "https://intel.twzrd.xyz/v1/intel/merchant_card/X4o2D8op42a2jcNJJVZcDq3eYivh1oR9XiezPWCXosZ"

# 4) free preflight on the 402 payTo
curl -s -X POST https://intel.twzrd.xyz/v1/intel/preflight \
  -H "Content-Type: application/json" \
  -d '{
    "seller_wallet": "X4o2D8op42a2jcNJJVZcDq3eYivh1oR9XiezPWCXosZ",
    "agent_intent": "swap_quote"
  }'
# decision = allow | warn | block  →  abort on block

# 5) optional paid teaser ($0.001) or full trust receipt ($0.05)
# GET https://intel.twzrd.xyz/v1/intel/quick/{pubkey}
# GET https://intel.twzrd.xyz/v1/intel/trust/{pubkey}

# 6) verify any returned V6 receipt (or the sample first)
curl -s https://intel.twzrd.xyz/v1/receipts/example > /tmp/ex.json
curl -s -X POST https://intel.twzrd.xyz/v1/receipts/verify \
  -H 'content-type: application/json' -d @/tmp/ex.json
```

One-command operator dogfood (logs day0 deltas):
`python packages/twzrd-agent-intel/scripts/seller_first_flywheel_dogfood.py`

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 -U twzrd-agent-intel==0.5.8
```

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

Add to your MCP config and restart. The remote server runs the live large cross-facilitator 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 the live MCP tool set (watch + seller signals + no-spend gate proof included; count = read `tools/list` — never freeze it here). 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.

## Live MCP tools (resource/seller-first + watch + no-spend proof)

**Free discovery + preflight (no payment, no auth):**
- HTTP SOT (not a 25th MCP tool): `GET /v1/intel/resources` — resource join inventory
- `get_x402_directory` — multi-bazaar overlay by payTo (prefer HTTP `/resources` for join SOT)
- `evaluate_x402_resource` — fetch a resource's 402, extract `payTo`, and run preflight
- `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` — **secondary** payer-wallet leaderboard research only (not a service catalog)

**Free corpus reputation + receipts:**
- `get_provider_reputation` — observed corpus reputation for a seller/merchant wallet
- `get_merchant_card` — observed receive-side graph card (`GET /v1/intel/merchant_card/{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/v6 receipt verification (recompute leaf + check Ed25519 sig)
- `verify_root_inputs` — recompute published leaves and server root inputs; this does not read an on-chain anchor
- `twzrd_demo_gate` — deterministic no-spend proof; block aborts before signer, attribution remains a candidate

**Solana market intel (free over MCP and over HTTP - the $0.03 paywall was dropped in #477):**
- `get_solana_market_visibility_map`
- `get_solana_market_orderbook_depth`
- `get_solana_market_shape`
- `get_solana_market_onchain_trades_summary`
- `get_solana_market_status`

**Free re-call watches:**
- `twzrd_watch_add`
- `twzrd_watch_list`
- `twzrd_watch_remove`

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

**After the free gate — paying a third-party x402 seller:** see
[`docs/PAYABLE_CLIENT_PATH.md`](./docs/PAYABLE_CLIENT_PATH.md) (feePayer-sponsored
Solana: use `@x402/svm`, not AgentCash; pin stable feePayer — per-request
feePayer pools make retries a lottery; see [2s-io/sdk#3](https://github.com/2s-io/sdk/issues/3)).

## HTTP API

```bash
# Free resource join SOT
curl -s "https://intel.twzrd.xyz/v1/intel/resources?limit=20"

# 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/BJGdsDXJFy63eCAnX3UmGfShp8BuqbtkTfcamyRGr7VQ
# → 402 with x402 v2 payment-required if payment-signature is absent

# 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
- Quick agent guide: https://intel.twzrd.xyz/llms.txt
- Full tool and payment reference: https://intel.twzrd.xyz/llms-full.txt
- Apex front door: https://twzrd.xyz/llms.txt (resources-first; full contract on intel)

## Self-hosting

> **Note**: Running `twzrd-agent-intel-mcp` locally serves from a small static research
> registry by default — not the live large cross-facilitator 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 wash-resistant scoring over a large cross-facilitator corpus.
- **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 v6 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 twzrd-receipt-verifier@^1.3.0 receipt.json --pubkey 9V6Pn19kiUA5Rn6JpQfNduanvGt2aXGwsarosNfa2Ldf
  ```
- **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 -->
