How do I use web3-agent?

This server has a remotely hosted endpoint. Open its connector listing for connection details, authentication requirements, and setup instructions: * Web3 Systemic Agent

web3-agent

by RafaCoelho33

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

Web3 Condition-Action Trigger Agent

Autonomous Web3 Security & Governance Auditor with Two-Stage Hybrid LLM Pipeline & x402 Bazaar Micropayments

Python 3.11+ Base x402 Protocol MCP Server Gemini 2.5/3.5 License: PolyForm Noncommercial

An autonomous Web3 agent engineered for real-time smart contract monitoring, DEX honeypot detection, and DAO governance security. Features a two-stage hybrid architecture that combines zero-cost deterministic on-chain gatekeeping with structured Gemini LLM evaluations, monetized Agent-to-Agent (A2A) via x402 gasless USDC micropayments on Base.

Operates natively as both a high-throughput FastAPI REST Service and a Model Context Protocol (MCP) Server compatible with Claude Desktop, Cursor, Smithery, Glama, and Coinbase AgentKit.

🌐 Live Production Service

The service is continuously deployed and operational in production on Render:

Base URL: https://web3-systemic-agent.onrender.com
MCP Discovery / Streamable-HTTP: https://web3-systemic-agent.onrender.com/mcp
Deep Semantic Audit Price: 0.05 USDC (EIP-3009 Gasless)
Default Production Network: Base Mainnet (eip155:8453) & Base Sepolia (eip155:84532)
Agent Recipient Wallet (PAY_TO_ADDRESS): 0x2b7F1fd931f7f28f89e0f688Dd5Bb7a620c24b63

Canonical API Endpoints

Method	Route	Description	x402 Micropayment
`GET`	`/`	Service discovery, payment parameters, and endpoint directory	Free
`GET`	`/health`	Uptime probe, multi-chain RPC connectivity, LLM status	Free
`GET`	`/mcp`	MCP server discovery, transport metadata, tools manifest	Free
`POST`	`/mcp`	MCP JSON-RPC 2.0 execution endpoint (streamable-http)	Free / 402 for Deep Audit
`POST`	`/rules/validate`	Static deterministic rule pre-validation and syntax check	Free
`POST`	`/evaluate`	Two-stage hybrid evaluation (Deterministic + Gemini LLM)	0.05 USDC
`POST`	`/rules/evaluate-batch`	Synchronous batch evaluation for up to 50 rules	Free / Sub-rules gated
`POST`	`/rules/enqueue`	Asynchronous evaluation queue returning unique `job_id`	Free
`GET`	`/jobs/{job_id}`	Asynchronous job status inspection and results retrieval	Free

Related MCP server: aegis-defi

🔌 Model Context Protocol (MCP) Server

The agent provides a first-class Model Context Protocol (MCP) server (src/mcp_server.py) implementing protocol specification 2024-11-05. It serves 3 free Stage 1 on-chain analysis tools to discover and qualify threats, and 1 paid Stage 2 tool for deep semantic auditing:

                                  ┌───────────────────────────────────────────────┐
                                  │           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. Free Stage 1 Tools

`scan_contract_selectors`

Purpose: Free deterministic bytecode inspection on Base or any EVM network. Discovers 4-byte function selectors and flags high-privilege administrative backdoors (transferOwnership, upgradeTo, mint, selfdestruct).
Parameters:
- target_address (string, required): Hex EVM smart contract address.
- chain_id (integer, default 8453): EVM Chain ID (8453 for Base Mainnet, 84532 for Base Sepolia).
- bytecode_override (string, optional): Raw contract runtime bytecode hex string for offline analysis.
Returns: Contract status, bytecode size, extracted selectors, flagged high-risk capabilities, risk level (HIGH, LOW, EOA), and upsell recommendation.

`check_token_honeypot`

Purpose: Free static bytecode analysis for DEX honeypots, rugpull traps, and malicious token contracts:
- Blacklist manipulation (isBlacklisted, setBlacklist, addToBlacklist)
- Arbitrary transfer taxes & 100% sell fee traps (setTax, setFee, setSellFee)
- Trading freeze and pause backdoors (pause, setTrading, enableTrading)
- EVM SELFDESTRUCT (opcode 0xff) drainage traps
Parameters:
- 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 bytecode for offline analysis.
Returns: is_honeypot_suspect boolean, numeric risk_score (0.0 to 10.0), active threat categories, detailed risk flags, and audit upsell guidance.

`scan_dao_proposals`

Purpose: Free scanner for recent Snapshot DAO governance proposals (Arbitrum, Aave, ENS, etc.). Extracts proposed execution targets, native Wei value transfers, and 4-byte calldata to detect governance hijack attempts.
Parameters:
- space_id (string, default "arbitrumfoundation.eth"): Snapshot DAO space ENS domain.
- limit (integer, default 3): Maximum proposals to fetch.
- use_curated_offline (boolean, default false): If true, returns verified realistic curated proposals without outbound network calls.
Returns: Proposal IDs, natural language titles, execution targets, calldata payloads, and audit recommendations.

2. Paid Stage 2 Tool

`deep_semantic_audit`

Purpose: Two-stage autonomous security and governance audit. Executes deterministic on-chain gatekeeping followed by structured Google Gemini LLM reasoning crossing natural language claims with actual bytecode and calldata reality.
Parameters:
- target_address (string, required): Hex EVM smart contract address.
- proposal_description (string, required): Natural language claim or governance proposal explanation.
- policy_prompt (string, optional): Security policy or criteria to audit against.
- calldata (string, default "0x"): Transaction hex calldata being executed.
- chain_id (integer, default 8453): EVM Chain ID.
- risk_threshold (number, default 7.0): Threshold (0.0 to 10.0) above which intervention is warranted.
- x402_payment_header (string, optional): Base64-encoded EIP-3009 transfer authorization satisfying $0.05 USDC payment.
Pricing & Micropayment Flow:
- If invoked without payment credentials, returns a structured HTTP 402 payment challenge with the exact recipient address, amount ($0.05 USDC), and instructions.
- If x402_payment_header is supplied (or X402_BUYER_PRIVATE_KEY is configured in the environment), the audit executes immediately and returns a deterministic policy result (APPROVE, MANUAL_REVIEW, or REJECT) with risk scores and flagged issues.

🛠️ MCP Client Configuration & Installation

Claude Desktop

Add the server to your 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

Create or edit .cursor/mcp.json in your project root or user config:

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

Smithery (`smithery.yaml`)

Install directly via Smithery.ai:

smithery run web3-systemic-agent

Or reference the local manifest:

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

Verified for the 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

Connect via HTTP streaming to the remote MCP endpoint without local installation:

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"]

🏗️ Two-Stage Architecture & x402 Micropayments

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"]

Proven Live On-Chain Settlements (Base Sepolia)

The x402 A2A settlement cycle using EIP-3009 (transferWithAuthorization) has been verified and settled on Base Sepolia (Chain ID: 84532) with zero gas ETH consumed by the buyer or agent:

Metric	Transaction 1 (Direct Settlement)	Transaction 2 (Live Mempool Capture)	Transaction 3 (Production Render)
Transaction Hash	`0xa02872819cef...`	`0x6aa7c671469d...`	`0x63ea962e6f0d...`
Settlement Method	Direct EIP-3009 call	Live mempool/block scan	`POST https://web3-systemic-agent.onrender.com/evaluate`
On-Chain Status	`Success` (Block `54583500`)	`Success` (Block `54644484`)	`Success`
Agent Wallet (`PAY_TO_ADDRESS`)	`0x2b7F1fd931...`	`0x2b7F1fd931...`	`0x2b7F1fd931...`
Buyer Wallet (A2A Agent)	`0x4EbC7529d8...`	`0x4EbC7529d8...`	`0x4EbC7529d8...`
x402 Facilitator (Gas Sponsor)	`0xd407e409E3...` (`https://x402.org/facilitator`)	`0xd407e409E3...` (`https://x402.org/facilitator`)	`0xd407e409E3...` (`https://x402.org/facilitator`)
USDC Token Contract	`0x036CbD5384...`	`0x036CbD5384...`	`0x036CbD5384...`
Settled Amount	`0.01 USDC`	`0.01 USDC`	`0.05 USDC`
Gas Cost (Buyer / Server)	`0.00 ETH` (Gasless EIP-3009)	`0.00 ETH` (Gasless EIP-3009)	`0.00 ETH` (Gasless EIP-3009)

📁 Repository Structure

├── 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

⚡ Quickstart & Setup

1. Installation

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. Configuration (`.env`)

Copy the template and provide your API keys:

cp .env.example .env

Key environment variables:

# 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. Verify MCP Server Offline

python src/mcp_server.py --dry-run

Expected output:

=== 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. Run the Full Test Suite

pytest

📜 License

This project is licensed under the PolyForm Noncommercial License 1.0.0.

Permitted: Non-commercial use, research, educational study, and personal experimentation.
Prohibited: Commercial use, hosting as a paid commercial service, or embedding in proprietary enterprise offerings without a commercial license.
Commercial Inquiries: Contact https://github.com/RafaCoelho33 for commercial licensing agreements.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

AgentDiet Base EVM & Solana Smart Contract Security ScannerA
dev.agentdiet
Audits any Base EVM 0x contract or Solana SPL Mint for proxy patterns, GoPlus honeypot flags, and.
Blockchain Penetration Testing Web3 & Decentralized Tech
21
https://onchain-risk.agentdiet.dev/mcp
RugShield 402B
io.github.ak10082247-max
Real-time token contract safety scanner and honeypot auditor via x402 on Base.
Blockchain Cryptocurrency Penetration Testing
1412
https://rugshield-402.onrender.com/mcp
Guava Wallet Intelligence
io.github.Guava-Research
Crypto security, honeypot detection, wallet analysis, and token risk scoring across 31 blockchains.
Blockchain Cryptocurrency Security
1
https://api.guavaintel.com/mcp
aegis-x402-mcpA
io.github.Goatincrypto
On-chain token security, honeypot simulation, KYA wallet trust, and x402 PreFlight audits on Base.
Blockchain Security Web3 & Decentralized Tech
71
https://aegis-audit-x402.project-easy-x.workers.dev/mcp

Related MCP Servers

base-security-scanner-mcp
lordbasilaiassistant-sudo
A
license
A
quality
C
maintenance
Smart contract security scanner for Base. Detect honeypots, rug pulls, hidden mints, proxy dangers, and generate audit reports.
Updated 2 months ago (2026-09-13 22:23 UTC)
8
25 npm
1
MIT
aegis-defi
Blockchain Autonomous Agents Security
StanleytheGoat
A
license
A
quality
D
maintenance
Safety layer for autonomous DeFi agents. Scans contracts for exploit patterns, simulates transactions, blocks honeypots.
Updated 7 months ago (2026-03-24 17:06 UTC)
4
9 npm
1
MIT
safeagent-token-safety
Blockchain Cryptocurrency
Aigen-Protocol
A
license
Not graded
quality
D
maintenance
Token safety oracle for AI agents. Honeypot detection, 17 scam pattern checks, LP lock verification across 6 EVM chains. Score 0-100 with risk flags. ERC Token Safety Score standard.
Updated 7 months ago (2026-04-05 04:46 UTC)
1
MIT
BlueAgent x402 Services
Blockchain Security Autonomous Agents
madebyshun
F
license
Not graded
quality
D
maintenance
Pay-per-use AI security and research tools for autonomous agents on Base, enabling honeypot detection, risk assessment, wallet analysis, and yield optimization via the x402 protocol.
Updated 5 months ago (2026-06-07 17:46 UTC)
1
-