Web3 Systemic Agent

Web3 条件-操作触发 Agent

采用两阶段混合式大模型流水线与 x402 Bazaar 微支付的自主 Web3 安全与治理审计器

这是一款自主 Web3 Agent，专为实时智能合约监控、DEX 貔貅盘检测和 DAO 治理安全审计而打造。它采用两阶段混合架构，将零成本的确定性链上筛查与结构化 Gemini 大模型评估相结合，并通过 Base 上的 x402 免 Gas USDC 微支付实现 Agent 对 Agent（A2A）变现。

它原生支持高吞吐量的 FastAPI REST 服务和 模型上下文协议（MCP）服务，兼容 Claude Desktop、Cursor、Smithery、Glama 和 Coinbase AgentKit。

---

🌐 线上生产服务

该服务通过 Render 持续部署，并在生产环境中运行：

• 基础 URL： https://web3-systemic-agent.onrender.com
• MCP 发现 / Streamable-HTTP： https://web3-systemic-agent.onrender.com/mcp
• 深度语义审计价格： 0.05 USDC（EIP-3009 免 Gas）
• 默认生产网络： Base 主网（eip155:8453）和 Base Sepolia（eip155:84532）
• Agent 收款钱包（PAY_TO_ADDRESS）： 0x2b7F1fd931f7f28f89e0f688Dd5Bb7a620c24b63

标准 API 端点

方法	路由	说明	x402 微支付
GET	/	服务发现、支付参数和端点目录	免费
GET	/health	运行时间探测、多链 RPC 连通性、大模型状态	免费
GET	/mcp	MCP 服务发现、传输元数据、工具清单	免费
POST	/mcp	MCP JSON-RPC 2.0 执行端点（streamable-http）	免费 / 深度审计需支付 402
POST	/rules/validate	静态确定性规则预验证和语法检查	免费
POST	/evaluate	两阶段混合评估（确定性评估 + Gemini 大模型）	0.05 USDC
POST	/rules/evaluate-batch	最多 50 条规则的同步批量评估	免费 / 子规则受限
POST	/rules/enqueue	返回唯一 job_id 的异步评估队列	免费
GET	/jobs/{job_id}	异步作业状态检查和结果获取	免费

---

🔌 模型上下文协议（MCP）服务

该 Agent 提供一流的**模型上下文协议（MCP）**服务（src/mcp_server.py），实现协议规范 2024-11-05。它提供 3 个免费的第 1 阶段链上分析工具，用于发现和判定威胁，以及 1 个用于深度语义审计的付费第 2 阶段工具：

                                  ┌───────────────────────────────────────────────┐
                                  │           MCP Server Tools Registry           │
                                  └───────────────────────────────────────────────┘
                                                          │
                    ┌─────────────────────────────────────┴─────────────────────────────────────┐
                    ▼                                                                           ▼
      ┌───────────────────────────┐                                               ┌───────────────────────────┐
      │     STAGE 1: FREE TOOLS   │                                               │    STAGE 2: PAID AUDIT    │
      │   (Deterministic / $0.00) │                                               │     ($0.05 USDC via x402) │
      └───────────────────────────┘                                               └───────────────────────────┘
                    │                                                                           │
       ├── scan_contract_selectors ───> Discovers EVM selectors & high-risk backdoors           │
       ├── check_token_honeypot    ───> Static bytecode analysis for tax & blacklist traps      │
       └── scan_dao_proposals      ───> Ingests Snapshot DAO proposals & calldata payloads     │
                                                                                                │
                               └─── (Upsell Recommendation Triggered) ──────────────────────────┘
                                                                ▼
                                                      deep_semantic_audit
                                        (Two-Stage Gatekeeping + Gemini LLM Reasoning)

1. 免费第 1 阶段工具

scan_contract_selectors

• 用途： 在 Base 或任何 EVM 网络上免费确定性地检查字节码。发现 4 字节函数选择器，并标记高权限管理后门（transferOwnership、upgradeTo、mint、selfdestruct）。
• 参数：
  • target_address (string, required)：十六进制 EVM 智能合约地址。
  • chain_id (integer, default 8453)：EVM 链 ID（8453 表示 Base 主网，84532 表示 Base Sepolia）。
  • bytecode_override (string, optional)：用于离线分析的原始合约运行时字节码十六进制字符串。
• 返回： 合约状态、字节码大小、提取出的选择器、标记出的高风险功能、风险等级（HIGH、LOW、EOA）及升级推荐。

check_token_honeypot

• 用途： 免费静态分析字节码，以检测 DEX 蜜罐、跑路陷阱和恶意代币合约：
  • 黑名单操纵（isBlacklisted、setBlacklist、addToBlacklist）
  • 任意转账税及 100% 卖出手续费陷阱（setTax、setFee、setSellFee）
  • 交易冻结和暂停后门（pause、setTrading、enableTrading）
  • EVM SELFDESTRUCT（操作码 0xff）资金抽离陷阱
• 参数：
  • token_address (string, required)：代币合约的十六进制 EVM 地址。
  • chain_id (integer, default 8453)：EVM 链 ID。
  • bytecode_override (string, optional)：用于离线分析的原始代币运行时字节码。
• 返回： is_honeypot_suspect 布尔值、数值型 risk_score（0.0 到 10.0）、活跃威胁类别、详细风险标记及审计升级指引。

scan_dao_proposals

• 用途： 免费扫描 Snapshot DAO 的近期治理提案（Arbitrum、Aave、ENS 等）。提取拟议的执行目标、原生 Wei 转账金额和 4 字节 calldata，以检测治理劫持企图。
• 参数：
  • space_id (string, default "arbitrumfoundation.eth")：Snapshot DAO 空间的 ENS 域名。
  • limit (integer, default 3)：最多获取的提案数。
  • use_curated_offline (boolean, default false)：若为 true，则返回经过验证的、真实可信的精选提案，且不进行外部网络调用。
• 返回： 提案 ID、自然语言标题、执行目标、calldata 负载及审计建议。

2. 付费第二阶段工具

deep_semantic_audit

• 用途： 两阶段自主安全与治理审计。先执行确定性的链上把关，再通过结构化的 Google Gemini 大模型推理，将自然语言声明与实际字节码和 calldata 进行交叉核验。
• 参数：
  • target_address (string, required)：十六进制 EVM 智能合约地址。
  • proposal_description (string, required)：自然语言声明或治理提案说明。
  • policy_prompt (string, optional)：用于审计的安全策略或标准。
  • calldata (string, default "0x")：正在执行的交易十六进制 calldata。
  • chain_id (integer, default 8453)：EVM 链 ID。
  • risk_threshold (number, default 7.0)：超过此阈值（0.0 到 10.0）时建议进行干预。
  • x402_payment_header (string, optional)：Base64 编码的 EIP-3009 转账授权，用于支付 0.05 美元 USDC。
• 定价与小额支付流程：
  • 如果调用时未提供支付凭证，则返回结构化的 HTTP 402 付款质询，包含准确的收款地址、金额（0.05 美元 USDC）和操作说明。
  • 如果提供了 x402_payment_header（或在环境中配置了 X402_BUYER_PRIVATE_KEY），则立即执行审计，并返回确定性的策略结果（APPROVE、MANUAL_REVIEW 或 REJECT）、风险评分和标记的问题。

---

🛠️ MCP 客户端配置与安装

Claude Desktop

将服务添加到你的 claude_desktop_config.json：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "web3-systemic-agent": {
      "command": "python",
      "args": ["-m", "src.mcp_server"],
      "cwd": "/path/to/web3-condition-action-trigger-agent",
      "env": {
        "WEB3_AGENT_URL": "https://web3-systemic-agent.onrender.com",
        "X402_BUYER_PRIVATE_KEY": ""
      }
    }
  }
}

Cursor IDE

在项目根目录或用户配置目录中创建或编辑 .cursor/mcp.json：

{
  "mcpServers": {
    "web3-systemic-agent": {
      "command": "python",
      "args": ["-m", "src.mcp_server"],
      "env": {
        "WEB3_AGENT_URL": "https://web3-systemic-agent.onrender.com"
      }
    }
  }
}

Smithery（smithery.yaml）

通过 Smithery.ai 直接安装：

smithery run web3-systemic-agent

或者引用本地清单：

startCommand:
  type: stdio
  configSchema:
    type: object
    properties:
      web3AgentUrl:
        type: string
        default: "https://web3-systemic-agent.onrender.com"
      x402BuyerPrivateKey:
        type: string
  commandFunction:
    python: "python -m src.mcp_server"

Glama（glama.json）

已通过 Glama MCP Directory 验证：

{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "name": "web3-systemic-agent",
  "maintainers": ["RafaCoelho33"],
  "homepage": "https://web3-systemic-agent.onrender.com",
  "repository": "https://github.com/RafaCoelho33/web3-systemic-agent"
}

Coinbase AgentKit / Streamable-HTTP

通过 HTTP 流式传输连接到远程 MCP 端点，无需本地安装：

import httpx

# Ingest tools manifest via Streamable-HTTP
async with httpx.AsyncClient() as client:
    resp = await client.get("https://web3-systemic-agent.onrender.com/mcp")
    tools = resp.json()["tools"]

---

🏗️ 两阶段架构与 x402 微支付

flowchart TD
    Client["Client / Agent / MCP Tool"] -->|POST /evaluate or deep_semantic_audit| Gate["x402 Payment Gatekeeper\n(EIP-3009 Gasless USDC)"]
    Gate -->|No / Invalid Payment Header| R402["HTTP 402 Payment Required\n(0.05 USDC -> PAY_TO_ADDRESS)"]
    Gate -->|Valid EIP-3009 Authorization| S1["Stage 1: ChainInspector (AsyncWeb3)\nBytecode Cache + Native Balance + Selectors"]
    S1 -->|Condition Fails| ShortCircuit["Deterministic Short-Circuit\n(llm_invoked=False, LLM Cost = $0.00)"]
    S1 -->|RPC Connectivity Error| Err503["HTTP 503 Unavailable\n(Payment NOT Settled / No Charge)"]
    S1 -->|Condition Passes| S2["Stage 2: GeminiSemanticEvaluator\nStructured JSON Schema + Failover Models"]
    S2 --> Policy["enforce_decision_policy\nDeterministic Escalation: REJECT / MANUAL / APPROVE"]
    ShortCircuit --> Settle["Settle Payment via x402 Facilitator\nLog to SQLite Ledger (data/agent.db)"]
    Policy --> Settle
    Settle --> Resp["HTTP 200 OK: FinalAgentResponse + PaymentReceipt"]

已验证的链上实时结算（Base Sepolia）

使用 EIP-3009（transferWithAuthorization） 的 x402 A2A 结算周期已在 Base Sepolia（链 ID：84532） 上验证并完成结算，买方或 Agent 均未消耗任何 Gas ETH：

指标	交易 1（直接结算）	交易 2（实时内存池捕获）	交易 3（生产渲染）
交易哈希	0xa02872819cef...	0x6aa7c671469d...	0x63ea962e6f0d...
结算方式	直接调用 EIP-3009	实时内存池／区块扫描	POST https://web3-systemic-agent.onrender.com/evaluate
链上状态	Success（区块 54583500）	Success（区块 54644484）	Success
Agent 钱包（PAY_TO_ADDRESS）	0x2b7F1fd931...	0x2b7F1fd931...	0x2b7F1fd931...
买方钱包（A2A Agent）	0x4EbC7529d8...	0x4EbC7529d8...	0x4EbC7529d8...
x402 Facilitator（Gas 赞助方）	0xd407e409E3...（https://x402.org/facilitator）	0xd407e409E3...（https://x402.org/facilitator）	0xd407e409E3...（https://x402.org/facilitator）
USDC 代币合约	0x036CbD5384...	0x036CbD5384...	0x036CbD5384...
结算金额	0.01 USDC	0.01 USDC	0.05 USDC
Gas 费用（买方／服务端）	0.00 ETH（无 Gas 的 EIP-3009）	0.00 ETH（无 Gas 的 EIP-3009）	0.00 ETH（无 Gas 的 EIP-3009）

---

📁 仓库结构

├── src/
│   ├── api.py                    # FastAPI service, x402 middleware, REST & MCP endpoints
│   ├── mcp_server.py             # MCP server implementation (stdio & HTTP, 4 tools)
│   ├── engine.py                 # ConditionAgentEngine two-stage orchestrator
│   ├── chain_inspector.py        # Stage 1 deterministic on-chain gatekeeper with FIFO cache
│   ├── semantic_evaluator.py     # Stage 2 Gemini/OpenAI LLM evaluator with cooldown failovers
│   ├── schemas.py                # Pydantic v2 strict schemas and contracts
│   ├── x402_payment.py           # x402 protocol, EIP-3009 signatures, replay defense
│   ├── governance_connector.py   # Snapshot GraphQL connector & Discord/Slack dispatcher
│   ├── storage.py                # Asynchronous SQLite ledger with automatic secret redaction
│   ├── task_worker.py            # In-memory background task worker pool
│   └── report.py                 # Telemetry CLI reporting token costs, revenue, net profit
├── scripts/
│   ├── block_contract_scanner.py # Autonomous Base Mainnet block deployment scanner
│   ├── dex_pool_monitor.py       # Uniswap v3 & Aerodrome pool event monitor & honeypot engine
│   ├── governance_listener.py    # Snapshot DAO sentinel bot
│   ├── client_agent_x402.py      # Standalone A2A client with real on-chain settlement
│   └── setup_buyer_wallet.py     # Wallet generation and USDC balance inspection utility
├── tests/                        # 460+ automated unit, security, and integration tests
├── smithery.yaml                 # Smithery MCP registry manifest
├── glama.json                    # Glama MCP directory configuration
├── Dockerfile                    # Production Docker container definition
├── docker-compose.yml            # Local containerized orchestration
└── .env.example                  # Environment configuration template

---

⚡ 快速开始与设置

1. 安装

git clone https://github.com/RafaCoelho33/web3-condition-action-trigger-agent.git
cd web3-condition-action-trigger-agent

# Install core and development dependencies
pip install -r requirements-dev.txt

2. 配置（.env）

复制模板并提供你的 API 密钥：

cp .env.example .env

关键环境变量：

# Server
PORT=8000
PUBLIC_EVALUATE_ONLY=true

# Google Gemini API
GEMINI_API_KEY=your_gemini_api_key_here
GEMINI_MODEL=gemini-3.5-flash-lite
GEMINI_FAILOVER_MODELS=gemini-3.5-flash-lite,gemini-3.1-flash-lite,gemini-2.5-flash-lite,gemini-2.0-flash

# x402 Micropayment Protocol
PAY_TO_ADDRESS=0x2b7F1fd931f7f28f89e0f688Dd5Bb7a620c24b63
X402_ENABLED=true
X402_NETWORK=eip155:8453
X402_PRICE_EVALUATE=0.05
X402_USE_LIVE_FACILITATOR=true

3. 离线验证 MCP 服务

python src/mcp_server.py --dry-run

预期输出：

=== Web3 Systemic Agent MCP Server Self-Test ===
[1/5] Registered 4 MCP tools: scan_contract_selectors, check_token_honeypot, scan_dao_proposals, deep_semantic_audit
[2/5] Tool 'scan_contract_selectors' OK: risk_level=LOW, selectors=1, cost=$0.00
[3/5] Tool 'check_token_honeypot' OK: is_honeypot=True, score=7.5, cost=$0.00
[4/5] Tool 'scan_dao_proposals' OK: count=1, cost=$0.00
[5/5] Tool 'deep_semantic_audit' OK: status=payment_required, status_code=402, price_usdc=0.05
=== All MCP self-tests PASSED successfully ===

4. 运行完整测试套件

pytest

---

📜 许可证

本项目采用 PolyForm Noncommercial License 1.0.0 许可。

• 允许： 非商业用途、研究、教育学习和个人实验。
• 禁止： 商业用途、作为付费商业服务托管，或未经商业许可嵌入专有企业产品。
• 商业咨询： 请联系 https://github.com/RafaCoelho33 洽谈商业许可协议。