# Web3 Systemic Agent (io.github.RafaCoelho33/web3-systemic-agent) > Autonomous Web3 Security & Governance Auditor with Two-Stage Hybrid LLM Pipeline & x402 Bazaar Micropayments. ## System Overview - **System Identifier:** `io.github.RafaCoelho33/web3-systemic-agent` - **Name:** Web3 Systemic Agent - **Version:** `1.0.0` - **Public API URL:** `https://web3-systemic-agent.onrender.com` - **Supported Chains:** Base Mainnet (`eip155:8453`), Base Sepolia (`eip155:84532`), Arbitrum One (`eip155:42161`) ## Two-Stage Hybrid Architecture 1. **Stage 1: Deterministic On-Chain Gatekeeping (Zero LLM Token Cost / Free)** - High-throughput EVM bytecode and calldata analysis using `ChainInspector` with local FIFO caching. - Extracts 4-byte function selectors, inspects target contract bytecode existence, verifies native balances, and evaluates DEX honeypot signatures. - Short-circuits non-matching or benign conditions with `llm_invoked=False` ($0.00 LLM token cost). 2. **Stage 2: Deep Semantic LLM Governance & Security Audit ($0.05 USDC via x402)** - Triggered only when Stage 1 deterministic conditions pass or high-risk administrative capabilities are detected. - Leverages Google Gemini (`gemini-3.5-flash-lite` with automatic cooldown failover to `gemini-3.1-flash-lite`, `gemini-2.5-flash-lite`, and `gemini-2.0-flash`). - Evaluates natural language claims against actual on-chain bytecode, native balance, and execution calldata. - Enforces deterministic policy escalation (`APPROVE`, `MANUAL_REVIEW`, `REJECT`) via `enforce_decision_policy`. ## Model Context Protocol (MCP) Streamable-HTTP (`POST /mcp`) Connect using MCP specification `2024-11-05` via HTTP POST: - **Endpoint:** `POST https://web3-systemic-agent.onrender.com/mcp` - **Headers:** `Content-Type: application/json` ### JSON-RPC 2.0 Examples #### 1. Initialize Request ```json { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "autonomous-client", "version": "1.0.0"} } } ``` #### 2. Tools List Request ```json { "jsonrpc": "2.0", "id": 2, "method": "tools/list" } ``` #### 3. Tools Call Request (scan_contract_selectors) ```json { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "scan_contract_selectors", "arguments": { "target_address": "0x4200000000000000000000000000000000000006", "chain_id": 8453 } } } ``` ## Available MCP Tools ### 1. `scan_contract_selectors` (Stage 1 Free) - **Description:** Deterministic inspection of smart contract bytecode to discover 4-byte EVM selectors and detect high-risk administrative backdoors (`transferOwnership`, `upgradeTo`, `mint`, `selfdestruct`). - **Arguments:** - `target_address` (string, required): Hex EVM address of smart contract. - `chain_id` (integer, default 8453): EVM Chain ID (8453 for Base Mainnet, 84532 for Base Sepolia, 42161 for Arbitrum One). - `bytecode_override` (string, optional): Raw contract runtime hex bytecode for offline analysis. ### 2. `check_token_honeypot` (Stage 1 Free) - **Description:** Static bytecode analysis for DEX honeypots, rugpull traps, and malicious token contracts: blacklist manipulation (`isBlacklisted`, `setBlacklist`), arbitrary transfer taxes (`setTax`, `setFee`), pause backdoors (`pause`, `setTrading`), and `selfdestruct` (opcode `0xff`). - **Arguments:** - `token_address` (string, required): Hex EVM address of token contract. - `chain_id` (integer, default 8453): EVM Chain ID. - `bytecode_override` (string, optional): Raw token runtime hex bytecode for offline analysis. ### 3. `scan_dao_proposals` (Stage 1 Free) - **Description:** Ingests recent Snapshot DAO governance proposals (Arbitrum, Aave, ENS). Extracts on-chain target addresses, Wei transfers, and calldata execution payloads to flag governance discrepancies. - **Arguments:** - `space_id` (string, default "arbitrumfoundation.eth"): Snapshot space ENS domain. - `limit` (integer, default 3): Number of proposals to fetch. - `use_curated_offline` (boolean, default false): If true, returns verified offline curated proposals. ### 4. `deep_semantic_audit` (Stage 2 Paid - $0.05 USDC via x402) - **Description:** Two-stage security audit crossing natural language proposal text with on-chain bytecode and calldata. Returns risk scores (0.0 to 10.0), flagged issues, and deterministic policy action (`APPROVE`, `MANUAL_REVIEW`, `REJECT`). - **Arguments:** - `target_address` (string, required): Smart contract address under evaluation. - `proposal_description` (string, required): Claim or governance proposal intent. - `policy_prompt` (string, optional): Custom policy prompt. - `calldata` (string, default "0x"): Hex calldata being executed. - `chain_id` (integer, default 8453): EVM Chain ID. - `risk_threshold` (number, default 7.0): Risk threshold. - `x402_payment_header` (string, optional): Base64 EIP-3009 transfer authorization. - **Payment Requirement:** If called without `x402_payment_header` or configured buyer key, returns HTTP 402 with recipient address `0x2b7F1fd931f7f28f89e0f688Dd5Bb7a620c24b63` on Base Mainnet (`eip155:8453`). ## REST API Integration ### Static Rule Validation (Free) - **Endpoint:** `POST https://web3-systemic-agent.onrender.com/rules/validate` - Validates payload structure and parameters before submission. ### Deep Evaluation Execution ($0.05 USDC via x402) - **Endpoint:** `POST https://web3-systemic-agent.onrender.com/evaluate` - **Headers:** `X-PAYMENT: ` #### Example Request Payload: ```json { "rule_id": "rule-audit-001", "chain_id": 8453, "deterministic": { "target_address": "0x4200000000000000000000000000000000000006", "min_value_wei": 0, "required_function_selectors": null, "check_native_balance": false }, "semantic": { "enabled": true, "policy_prompt": "Audit contract for unauthorized ownership transfer or backdoor drainage.", "risk_threshold": 7.0 }, "context_metadata": { "proposal_description": "Routine parameter update without audit", "calldata": "0xf2fde38b000000000000000000000000deadbeefdeadbeefdeadbeefdeadbeefdeadbeef" } } ``` ### Simplified Quick Contract Audit ($0.05 USDC via x402) - **Endpoint:** `POST https://web3-systemic-agent.onrender.com/audit` - **Headers:** `X-PAYMENT: ` - **Request Body:** `QuickAuditRequest` (`target_address`, `chain_id`, `proposal_description`, `calldata`, `policy_prompt`, `risk_threshold`) #### Example Quick Audit Payload: ```json { "target_address": "0x4200000000000000000000000000000000000006", "chain_id": 8453, "proposal_description": "Audit smart contract for administrative backdoors, honeypot traps, or unauthorized privilege escalation.", "calldata": "0x" } ``` ### Preflight Transaction Security Firewall ($0.01 USDC via x402) - **Endpoint:** `POST https://web3-systemic-agent.onrender.com/preflight` - **Headers:** `X-PAYMENT: ` - **Request Body:** `PreflightRequest` (`to_address`, `calldata`, `value_wei`, `chain_id`, `eip712_typed_data`, `untrusted_text`, `run_simulation`) ### Deep Source & Proxy Smart Contract Audit ($0.25 USDC via x402) - **Endpoint:** `POST https://web3-systemic-agent.onrender.com/audit/deep` - **Headers:** `X-PAYMENT: ` - **Request Body:** `DeepAuditRequest` (`target_address`, `chain_id`, `proposal_description`, `resolve_proxy`, `fetch_verified_source`) ### x402 Bazaar Protocol Discovery - **Endpoint:** `GET https://web3-systemic-agent.onrender.com/.well-known/x402` - Returns official x402 v2 service discovery metadata and resource specifications for `/evaluate`, `/audit`, `/preflight`, and `/audit/deep`. ## Security & Transparency - **Security Policy:** `/.well-known/security.txt` - **MCP Server Card:** `/.well-known/mcp/server-card.json` - **Agent Card:** `/.well-known/agent.json` - **Contact:** https://github.com/RafaCoelho33/web3_systemic-agent/issues