# ⚡ Multi-Chain & Solana x402 Autonomous AI Agent Suite & Spend Firewall (v2.8.4)

> **"High-Throughput Clean Web Markdown, YouTube Intelligence & Cryptographic Web3 Oracles for Autonomous AI Agents & Swarms."**  
> *Zero credit cards required. Pure B2A (Business-to-Agent) USDC micropayments & pre-funded vaults on Solana, Polygon, Base, and Arbitrum with Solscan Verified IDLs & EIP-712 spend policy attestations.*

[![Version](https://img.shields.io/badge/Version-2.8.4-00f2fe?style=for-the-badge&logo=fastapi&logoColor=black)](https://github.com/nohosa001-pixel/x402-cleanweb-agent)
[![LangChain Official Integration](https://img.shields.io/badge/LangChain-Official%20Provider-1C3C3C?style=for-the-badge&logo=langchain&logoColor=white)](https://docs.langchain.com/oss/python/integrations/providers/all_providers)
[![LlamaIndex](https://img.shields.io/badge/LlamaIndex-Official%20Reader-8A2BE2?style=for-the-badge&logo=llamaindex&logoColor=white)](https://pypi.org/project/llama-index-readers-x402-cleanweb/)
[![PyPI](https://img.shields.io/pypi/v/x402-cleanweb-agent?style=for-the-badge&logo=pypi&logoColor=white&color=blue)](https://pypi.org/project/x402-cleanweb-agent/)
[![npm agentkit](https://img.shields.io/npm/v/agentkit-cleanweb?style=for-the-badge&logo=npm&logoColor=white&label=agentkit-cleanweb&color=cb3837)](https://www.npmjs.com/package/agentkit-cleanweb)
[![npm eliza](https://img.shields.io/npm/v/cleanweb-eliza-plugin?style=for-the-badge&logo=npm&logoColor=white&label=cleanweb-eliza-plugin&color=cb3837)](https://www.npmjs.com/package/cleanweb-eliza-plugin)
[![Tests](https://img.shields.io/badge/Tests-84%2F84%20Passed%20(100%25)-success?style=for-the-badge&logo=pytest&logoColor=white)](https://github.com/nohosa001-pixel/x402-cleanweb-agent)
[![MCP](https://img.shields.io/badge/MCP-14%20Tools%20Ready-blueviolet?style=for-the-badge&logo=anthropic&logoColor=white)](https://glama.ai/mcp/servers)
[![Multi-Chain](https://img.shields.io/badge/Chains-Polygon%20%7C%20Base%20%7C%20Arbitrum%20%7C%20Solana-8247e5?style=for-the-badge&logo=ethereum&logoColor=white)](https://solscan.io/account/411ksMz9RHYVtVMe6RUUErzZYtrU9zzvkgzswKbqx9qp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)

---

## 🚀 New in v2.8.4 (Community-Driven Release from r/mcp)

CleanWeb v2.8.4 brings major performance & capability upgrades inspired directly by community feedback on `r/mcp`:

1. **Multimodal Image `alt` Text Preservation**:
   - Preserves high-value image captions and chart descriptions (`![alt text](url)`) crucial for Multimodal LLMs (Claude 3.5 Sonnet, GPT-4o, Gemini 2.0).
   - **Covert Channel Defense**: Transparently neutralizes 1x1 tracking pixels and parameter-leaking exfiltration vectors (`![alt text][EXFILTRATION_IMAGE_BLOCKED]`), ensuring zero data leakage.

2. **Zero-Overhead SPA Hydration State Extractor**:
   - Parses client-side Single Page Applications (SPAs) by extracting pre-rendered state from Next.js (`__NEXT_DATA__`), Nuxt.js (`__NUXT_DATA__`), and Schema.org JSON-LD (`application/ld+json`).
   - Pure Python execution with **sub-millisecond latency** and **<16MB RAM**—no heavy 500MB headless browser instances required for 90% of dynamic web pages.
   - Optional `dynamic_render=True` and `scroll_depth=N` for JavaScript-heavy infinite scroll feeds.

---

## 📦 Official Multi-Registry Ecosystem Suite (PyPI ↔ npm)

CleanWeb is distributed natively across both **Python (PyPI)** and **TypeScript/Node.js (npm)** registries. Install the companion package for your stack—or combine the Python MCP/Oracle Core with TypeScript agent frameworks:

| Registry | Package Name | Target Ecosystem | 1-Line Install Command |
| :---: | :--- | :--- | :--- |
| **PyPI** | [**`x402-cleanweb-agent`**](https://pypi.org/project/x402-cleanweb-agent/) | **Python Core, FastAPI Oracle, Claude/Cursor MCP Server & Dual-Core Eliza Brain** | `pip install x402-cleanweb-agent` *(or `uvx x402-cleanweb-agent`)* |
| **PyPI** | [**`llama-index-readers-x402-cleanweb`**](https://pypi.org/project/llama-index-readers-x402-cleanweb/) | **LlamaIndex High-Purity RAG Reader (87% Token Compression & Injection Defense)** | `pip install llama-index-readers-x402-cleanweb` |
| **npm** | [**`agentkit-cleanweb`**](https://www.npmjs.com/package/agentkit-cleanweb) | **Coinbase AgentKit Action Provider (Base Mainnet EIP-712 & x402 Vaults)** | `npm install agentkit-cleanweb @coinbase/agentkit` |
| **npm** | [**`cleanweb-eliza-plugin`**](https://www.npmjs.com/package/cleanweb-eliza-plugin) | **ElizaOS v2 Plugin (Solana x402 Micropayments & A.GRID Priority 0 Feed)** | `npm install cleanweb-eliza-plugin` |
| **npm** | [**`elizaos-plugin-security-gate`**](https://www.npmjs.com/package/elizaos-plugin-security-gate) | **Security Gate & Polygon OMS Spend Firewall (Prompt-Injection Defense)** | `npm install elizaos-plugin-security-gate` |

> 💡 **Full-Stack Zero-Trust Pattern (Recommended)**:
> 1. Use **`cleanweb-eliza-plugin`** (or `x402-cleanweb-agent`) for 87% token-compressed, ad-free web ground truth.
> 2. Guard outbound transactions and web payloads via **`elizaos-plugin-security-gate`** with **Polygon Open Money Stack (OMS) spend controls** (`SecurityGateOMSPolicy.sol` verified on Polygon: `0x4A28F9A2E6D0DcB69791980560FC8364A514f205`) and sub-second **Solana (`501`) settlements**.

---

## 🌐 Live Production Gateway & Endpoints

* **Production Gateway**: `https://x402-cleanweb-agent-7qxtp3324q-du.a.run.app`
* **Agent LLM Standard (`llms.txt`)**: [`https://x402-cleanweb-agent-7qxtp3324q-du.a.run.app/llms.txt`](https://x402-cleanweb-agent-7qxtp3324q-du.a.run.app/llms.txt)
* **A2A Agent Manifest**: [`/.well-known/agent.json`](https://x402-cleanweb-agent-7qxtp3324q-du.a.run.app/.well-known/agent.json)
* **OpenAI Plugin Manifest**: [`/.well-known/ai-plugin.json`](https://x402-cleanweb-agent-7qxtp3324q-du.a.run.app/.well-known/ai-plugin.json)
* **MCP Server Card**: [`/.well-known/mcp/server-card.json`](https://x402-cleanweb-agent-7qxtp3324q-du.a.run.app/.well-known/mcp/server-card.json)
* **Arbitrage ROI Calculator**: [`/api/v1/agent/arbitrage-roi`](https://x402-cleanweb-agent-7qxtp3324q-du.a.run.app/api/v1/agent/arbitrage-roi)
* **Interactive Studio Dashboard**: `https://x402-cleanweb-agent-7qxtp3324q-du.a.run.app/dashboard`
* **Interactive OpenAPI Specs**: `https://x402-cleanweb-agent-7qxtp3324q-du.a.run.app/docs`

---

## 🤖 1-Minute Framework Integration (Coinbase AgentKit, ElizaOS, LangChain & CrewAI)

Equip your autonomous agents across TypeScript (npm) and Python (PyPI) in under 1 minute:

```typescript
// TypeScript: Official Coinbase AgentKit Action Provider (npm: agentkit-cleanweb)
import { cleanWebActionProvider } from "agentkit-cleanweb";

const cleanWeb = cleanWebActionProvider({ vaultKey: process.env.AGENT_VAULT_KEY });
```

```typescript
// TypeScript: Official ElizaOS v2 Plugin (npm: cleanweb-eliza-plugin)
import { cleanWebPlugin } from "cleanweb-eliza-plugin";

export default { name: "AlphaScoutAgent", plugins: [cleanWebPlugin] };
```

```python
# Python: ElizaOS / Dual-Core Gate-Brain Bridge (PyPI: x402-cleanweb-agent)
from app.integrated_gate_brain_bridge import IntegratedGateBrainBridge

bridge = IntegratedGateBrainBridge(require_x402_payment=False)
res = bridge.execute_pipeline("https://paulgraham.com/greatwork.html", "https://paulgraham.com")
```

```python
# Python: LlamaIndex High-Purity RAG Reader (pip install llama-index-readers-x402-cleanweb)
from llama_index.readers.x402_cleanweb import X402CleanWebReader
from llama_index.core import VectorStoreIndex

# 87% token-compressed, prompt-injection defended web documents for vector search
documents = X402CleanWebReader().load_data(["https://paulgraham.com/greatwork.html"])
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()
response = query_engine.query("What are the core habits of great work?")
```

```python
# Python: LangChain & CrewAI Agent Tools
from examples.langchain_agent_example import clean_web_tool
from examples.crewai_agent_example import clean_web_for_crewai

result = clean_web_tool.invoke({"url": "https://paulgraham.com/greatwork.html"})
```

---

## ⚡ 10-Second Instant Test (Zero Auth / 3 Free Calls Included)

No wallet, credit card, or API key needed. Attach an `X-Agent-Nonce` header to test immediately:

```bash
# Instant JSON Request via curl
curl -X POST "https://x402-cleanweb-agent-7qxtp3324q-du.a.run.app/api/v1/clean-web" \
     -H "Content-Type: application/json" \
     -H "X-Agent-Nonce: instant-trial-uuid-001" \
     -d '{"url": "https://news.ycombinator.com"}'
```

```python
# Zero-dependency Python snippet
import urllib.request, json

req = urllib.request.Request(
    "https://x402-cleanweb-agent-7qxtp3324q-du.a.run.app/api/v1/clean-web",
    data=json.dumps({"url": "https://news.ycombinator.com"}).encode(),
    headers={"Content-Type": "application/json", "X-Agent-Nonce": "instant-trial-01"}
)
res = json.loads(urllib.request.urlopen(req).read())
print(f"Tokens Saved: {res.get('estimated_token_savings', '87%')}")
print("Clean Markdown Preview:\n", res["clean_markdown"][:300])
```

---

## 💡 Mathematical Token Arbitrage Proof (Economic Rationality)

Autonomous agents route web traffic through x402 because **it mathematically saves the operator money on every query**:

* **Direct Scraping Cost**: 80KB HTML ≈ 20,000 tokens ($0.05 USD input cost on GPT-4o / Claude 3.5 Sonnet).
* **x402 CleanWeb Cost**: $0.001 API fee + 2,600 clean tokens ($0.0065 USD) = **$0.0075 USD Total**.
* **Net Savings**: **$0.0425 USD saved per web query (85% net dollar reduction)**.
* **Service Fee ROI**: **4,250% ROI on the $0.001 fee**.
* **Live Arbitrage Endpoint**: `GET /api/v1/agent/arbitrage-roi?input_tokens=50000`

```json
{
  "status": "economically_optimal",
  "routing_recommendation": "ROUTE_VIA_X402",
  "financial_analysis": {
    "cost_raw_direct_usd": 0.125,
    "cost_with_x402_usd": 0.01725,
    "net_dollar_savings": 0.10775,
    "net_savings_percentage": "86.2%",
    "service_fee_roi_percentage": "10775.0%"
  }
}
```

---

## 🔮 14 Production Agent Tools & Micro-Pricing (USDC)

| Tool Name | Endpoint / Function | Cost (USDC) | What It Does |
| :--- | :--- | :---: | :--- |
| **🌐 Clean Web** | `GET/POST /api/v1/clean-web` | **0.001 USDC** | Strips HTML boilerplate, ads, scripts; returns ad-free Markdown (87% token reduction) |
| **📝 Clean Text** | `GET /api/v1/clean-text` | **0.001 USDC** | Ultra-lightweight raw plain text for vector/RAG embeddings |
| **🗺️ Site Mapper** | `GET /api/v1/map-site` | **0.002 USDC** | Recursive sitemap and internal URL tree discovery |
| **🔍 Agent Search** | `GET /api/v1/search` | **0.002 USDC** | Fast real-time keyword search & verified snippets (Tavily engine) |
| **📑 PDF Extractor** | `GET /api/v1/clean-pdf` | **0.005 USDC** | Formula- and table-preserved academic paper & research PDF extractor |
| **📦 Batch Clean** | `POST /api/v1/batch-clean` | **0.005 USDC** | Concurrent parallel scraping for up to 10 URLs in a single request |
| **🎬 YouTube AI** | `GET /api/v1/clean-youtube` | **0.010 USDC** | Gemini 3.8 Flash multimodal video intelligence & timestamped audio transcript |
| **📊 Extract JSON** | `POST /api/v1/extract-json` | **0.030 USDC** | Converts arbitrary web content into strict schema-constrained JSON |
| **🔮 Web3 Oracle** | `POST /api/v1/oracle/grounding` | **0.035 USDC** | **Live Search + Clean-to-JSON + EIP-712 Cryptographic On-Chain Attestation** |
| **🛡️ Oracle Verify** | `POST /api/v1/oracle/verify` | **0.000 USDC** | Verifies ECDSA signature of CleanWeb Oracle attestations on-chain |
| **🧠 Deep Research** | `GET /api/v1/deep-research` | **0.150 USDC** | Multi-source synthesized AI executive research briefing |
| **💼 Vault Deposit** | `POST /api/v1/vault/deposit` | **0.000 USDC** | Multi-chain USDC vault prefunding for sub-5ms gasless executions |
| **💳 Vault Balance** | `GET /api/v1/vault/balance` | **0.000 USDC** | Real-time query of credit pass balance and validity |
| **🎫 Pass Status** | `GET /api/v1/pass-status` | **0.000 USDC** | Inspects status and remaining credits of a prepaid pass |

---

## 💻 1-Click MCP Setup (Claude Desktop, Cursor, Windsurf)

Connect CleanWeb directly to Claude Desktop, Cursor, or any Model Context Protocol client using `uvx`:

```json
{
  "mcpServers": {
    "polygon-x402-cleanweb": {
      "command": "uvx",
      "args": ["x402-cleanweb-agent"]
    }
  }
}
```

Or configure via local clone:

```json
{
  "mcpServers": {
    "polygon-x402-cleanweb": {
      "command": "python",
      "args": ["-u", "mcp_server.py"],
      "env": {
        "POLYGON_RPC_URL": "https://polygon-bor-rpc.publicnode.com",
        "SERVER_WALLET_ADDRESS": "0xA185B43fDD19619f99952AAed6eabf1029bF36a1",
        "USDC_CONTRACT_ADDRESS": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359"
      }
    }
  }
}
```

---

## 🤖 Multi-Agent Framework Integrations

Drop-in ready integrations for every major autonomous agent framework via `GET /api/v1/agent/integrations/{framework}`:

### 🦜 LangChain / LangGraph

```python
from langchain.tools import tool
import requests

@tool
def clean_web(url: str) -> str:
    """Fetches a URL and returns ad-free, token-optimized Markdown (87% token savings)."""
    res = requests.get(
        "https://x402-cleanweb-agent-7qxtp3324q-du.a.run.app/api/v1/clean-web",
        params={"url": url},
        headers={"X-Agent-Nonce": "langchain-agent-session"}
    )
    return res.json().get("clean_markdown", "")
```

### 👥 CrewAI

```python
from crewai.tools import tool
import requests

@tool("CleanWeb Tool")
def clean_web(url: str) -> str:
    """Strips HTML boilerplate and returns pure Markdown to save LLM context window."""
    res = requests.post(
        "https://x402-cleanweb-agent-7qxtp3324q-du.a.run.app/api/v1/clean-web",
        json={"url": url},
        headers={"X-Agent-Nonce": "crewai-agent-session"}
    )
    return res.json().get("clean_markdown", "")
```

### 🤖 Microsoft AutoGen

```python
import requests

def clean_web_tool(url: str) -> str:
    res = requests.get(
        "https://x402-cleanweb-agent-7qxtp3324q-du.a.run.app/api/v1/clean-web",
        params={"url": url},
        headers={"X-Agent-Nonce": "autogen-session"}
    )
    return res.json().get("clean_markdown", "")

# assistant.register_for_llm(name="clean_web", description="Clean web markdown")(clean_web_tool)
```

---

## 🏛️ Verified On-Chain Smart Contracts & Accounts (Polygon, Base, Arbitrum, Solana)

CleanWeb operates verified, deterministic smart contracts and native settlement accounts for on-chain EIP-712 oracle verification, autonomous agent pre-funded vault management, and Solana SPL USDC micropayments.

| Contract / Account | Polygon Mainnet (137) ✔ | Base Mainnet (8453) ✔ | Arbitrum One (42161) ✔ | Solana Mainnet-Beta (101) ✔ |
| :--- | :--- | :--- | :--- | :--- |
| **`AgentPaymentVault`** | [`0x45ecBf...1861`](https://polygonscan.com/address/0x45ecBfAa2F4B0Bc6ccD3eB2dB9B1Ca49CF121861#code) | [`0x28292D...76DD`](https://basescan.org/address/0x28292D76E07E5539F15F3b97935dE8E0432E76DD#code) | [`0x28292D...76DD`](https://arbiscan.io/address/0x28292D76E07E5539F15F3b97935dE8E0432E76DD#code) | [`7oZ16Y...Wi3y (Solscan)`](https://solscan.io/account/7oZ16YaazQzN6z5uA1nAZWD9oGUDXyvHwXGJLFYyWi3y) |
| **`CleanWebOracleConsumer`** | [`0xAECbfB...6D66`](https://polygonscan.com/address/0xAECbfBc171F522c35985AABa2FA1F9881A046D66) | [`0x2394d8...dabe`](https://basescan.org/address/0x2394d888Bd4FFeD472318B891FA17f7F9119dabe#code) | [`0x2394d8...dabe`](https://arbiscan.io/address/0x2394d888Bd4FFeD472318B891FA17f7F9119dabe#code) | [`21ZR1Q...bkTL (Solscan)`](https://solscan.io/account/21ZR1QCyAbNrRLs1iWEkdbNsfCFdJcy6ip9R2JxDbkTL) |
| **`CleanWebOracleVerifier`** | [`0x18fA45...Dc46`](https://polygonscan.com/address/0x18fA451b1d9A9FbbDa6Ebd86F8b42891866ADc46) | [`0x3eD259...0740`](https://basescan.org/address/0x3eD259e47ebA439A9A35489787482B0003310740#code) | [`0x3eD259...0740`](https://arbiscan.io/address/0x3eD259e47ebA439A9A35489787482B0003310740#code) | [`9nVrym...iopC (Solscan)`](https://solscan.io/account/9nVrymJgNWCXkuGKn8CCQnSK6aDazFR7z3WL82jZiopC) |
| **`Treasury Recipient Wallet`** | [`0xA185B4...36a1`](https://polygonscan.com/address/0xA185B43fDD19619f99952AAed6eabf1029bF36a1) | [`0xA185B4...36a1`](https://basescan.org/address/0xA185B43fDD19619f99952AAed6eabf1029bF36a1) | [`0xA185B4...36a1`](https://arbiscan.io/address/0xA185B43fDD19619f99952AAed6eabf1029bF36a1) | [`411ksM...9qp (Solscan)`](https://solscan.io/account/411ksMz9RHYVtVMe6RUUErzZYtrU9zzvkgzswKbqx9qp) |
| **`Native USDC Token Tracker`** | [`0x3c499c...3359`](https://polygonscan.com/token/0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359) | [`0x833589...2913`](https://basescan.org/token/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913) | [`0xaf88d0...5831`](https://arbiscan.io/token/0xaf88d065e77c8cC2239327C5EDb3A432268e5831) | [`EPjFWd...YTDt1v (Solscan)`](https://solscan.io/token/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v) |

---

## 🧪 Production Readiness Review: 84/84 Tests Passed (100%)

Verified across all 38+ FastAPI routes, 14 agent tools, Dual-Core Gate-Brain cognitive pipeline, multi-chain settlement vaults, and EIP-712 attestations:

```bash
python -m pytest tests/ -v
```

---

## ⚖️ Legal, Fair Use & Financial Non-Liability Disclaimer

CleanWeb Studio operates strictly under the **Transformative Non-Expressive Text/Data Mining (TDM) Fair Use** doctrine for autonomous AI reasoning.

1. **No Financial or Investment Warranty**: All oracle feeds, search results, and scraped contents are provided **AS-IS**. CleanWeb Studio assumes zero liability for DeFi smart contract liquidations, prediction market settlements (e.g. Polymarket), or trading losses resulting from external web misreporting or LLM hallucinations.
2. **Caller Responsibility**: The autonomous agent deployer/caller is solely responsible for respecting target website intellectual property and applicable laws.
3. **Zero-Data Retention (GDPR Compliant)**: All fetched HTML and raw assets are processed ephemerally in RAM and purged immediately upon response transmission.
4. **100% OFAC Sanctions Filtering**: All micropayment addresses are verified against OFAC Specially Designated Nationals (SDN) lists.
5. **Full Legal Endpoints**:
   * `GET /api/v1/legal/terms`: Official Machine-to-Machine Terms of Service
   * `GET /api/v1/legal/disclaimer`: Full Legal & Financial Disclaimer

---

## 📜 License

Distributed under the MIT License. See `LICENSE` for more information.