Bridging Autonomous AI Agents with Decentralized Finance through Deterministic Policy Engines, Real-Time Blockchain Indexing, and Human-in-the-Loop Cryptographic Execution.
Figure 1: WETH Landing Page — Zero-Trust AI Agent Execution with Ironclad Ethereum Security
Figure 2: WETH Human-in-the-Loop Web Dashboard — Autonomous AI Reasoning paired with Zero-Trust Execution
- 1. Executive Overview & Core Philosophy
- 2. Deep Dive: How AI Interacts with Ethereum in WETH
- 3. System Architecture & Diagrams
- 4. Complete MCP Tool Suite (13 Specialized Tools)
- 5. Application Gallery & Visual Showcase
- 6. Monorepo Structure & Packages
- 7. Quickstart & Deployment Guide
- 8. Claude Desktop & AI Agent Configuration
- 9. Audit Trail & Compliance
- 10. Security & Threat Model
🎯 Target Buildathon Tracks:
- Track: AI x Ethereum — Architected specifically to connect autonomous Large Language Model agents (via standard Model Context Protocol) with secure Ethereum execution and zero-trust human-in-the-loop cryptographic signing.
- Track: Infratooling (Infra & Tooling) — Open-source developer infrastructure providing stdio JSON-RPC MCP servers, PostgreSQL transaction auditing, deterministic Zod policy guardrails, and automated gas simulation pipelines.
As Large Language Models (LLMs) and autonomous agents evolve from conversation assistants into actionable economic agents, their integration with blockchain networks becomes critical. However, granting direct private key custody to non-deterministic AI models introduces catastrophic financial risk.
WETH solves this fundamental challenge by creating an MCP-Native, Zero-Trust Execution Infrastructure between AI models (such as Claude, Gemini, or custom LLM copilots) and Ethereum:
+--------------------------------------------------------------------------------------------------+
| THE WETH SECURITY PARADIGM |
| |
| [ AI AGENT SANDBOX ] [ POLICY & RISK ENGINE ] [ HUMAN WALLET ] |
| Reads Chain State Evaluates Gas & Allowance Holds Private Key |
| Simulates Transactions -------> Enforces Max Spend Limits ----> Signs Approved Drafts |
| Drafts Intent Actions Detects Anomalies / Drains Broadcasts On-Chain |
+--------------------------------------------------------------------------------------------------+
- AI Autonomous Intelligence Layer: AI agents can query live token balances, index historical token flows via Alchemy, resolve ENS domains, simulate transactions against EVM state, and scan wallets for risky ERC20 allowances.
- Deterministic Guardrail Layer: Before any transaction draft is created, WETH's automated Policy Engine and Risk Engine intercept the payload, checking deterministic rules (maximum transfer volume, contract blacklists, unusual gas spikes, concentration limits).
- Non-Custodial Human Execution Layer: AI agents never hold private keys. Instead, they produce cryptographically verified transaction drafts. Human operators review and sign these drafts inside a sleek Next.js 15 Web Dashboard using MetaMask or wallet extensions.
WETH turns raw Ethereum JSON-RPC and Alchemy Indexer APIs into structured, semantic tools via the Model Context Protocol (MCP). Instead of prompting an LLM to generate raw hex-encoded calldata or manage brittle RPC calls, WETH exposes type-safe JSON schemas (Zod) directly to the model's tool-calling engine.
When an AI agent receives a natural language prompt such as:
"Analyze my Sepolia wallet
ayush.eth, check if I have suspicious token approvals, and draft a 0.5 ETH transfer tovitalik.ethif safe."
The model autonomously reasons over its available MCP toolset and executes structured function calls sequentially.
AI agents connected to WETH act as institutional-grade blockchain analysts:
- Token Balance Indexing (
alchemy_getTokenBalances): AI inspects real-time native ETH and ERC20 balances, calculating portfolio concentration and diversification metrics. - Transaction Flow Mapping (
alchemy_getAssetTransfers): AI maps historical incoming and outgoing asset transfers to detect wallet behavioral patterns. - Smart Contract Risk Auditing (
detect_risky_approvals): AI inspects ERC20allowance()states across protocols to identify unlimited spending permissions granted to unverified or potentially compromised spender contracts.
WETH establishes an explicit, auditable separation between Intent Generation (AI) and Cryptographic Authorization (Human):
[ Natural Language Prompt ]
│
▼
┌────────────────────────────────────────────────────────┐
│ Phase 1: Autonomous AI Intelligence & State Simulation │
├────────────────────────────────────────────────────────┤
│ 1. resolve_ens(name) -> Address │
│ 2. estimate_gas(tx) -> EIP-1559 Cost Breakdown │
│ 3. simulate_transaction(tx) -> EVM Revert Check │
└────────────────────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────┐
│ Phase 2: Deterministic Policy & Risk Interception │
├────────────────────────────────────────────────────────┤
│ 4. analyze_transaction_risk(draft) -> Risk Score 0-100 │
│ ├── Threshold Verification (e.g. < 10 ETH Limit) │
│ ├── Blacklisted Recipient Verification │
│ └── Policy Compliance Flag │
└────────────────────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────┐
│ Phase 3: Cryptographic Human-In-The-Loop Execution │
├────────────────────────────────────────────────────────┤
│ 5. create_transaction_draft() -> PENDING_APPROVAL │
│ 6. Next.js Web Application Fetches Drafts │
│ 7. Human Signs via MetaMask (Private Key Local) │
│ 8. Broadcast & Permanent Audit Log Recording │
└────────────────────────────────────────────────────────┘
Every AI action passes through two independent evaluation layers:
| Layer | Type | Responsibility | Examples |
|---|---|---|---|
| Policy Engine | Hard Deterministic Rules | Instant acceptance or rejection based on hardcoded governance limits. | • Reject transfer > 10 ETH • Reject interaction with blacklisted addresses • Require explicit simulation success |
| Risk Engine | Quantitative Scoring | Computes a composite risk score (0.0 - 100.0) categorized into LOW, MEDIUM, HIGH, or CRITICAL. |
• New / unverified recipient address • High gas consumption relative to value transferred • Portfolio concentration erosion |
graph TB
subgraph AI["AI Layer (Client Sandbox)"]
Claude["Claude Desktop / AI Copilot"]
LLM["Agent LLM Runtime"]
end
subgraph MCP["MCP Infrastructure Layer"]
MCPServer["WETH MCP Server (Stdio/SSE)"]
ToolRegistry["13 Structured Blockchain Tools"]
end
subgraph Core["Core Application & Policy Layer"]
Fastify["Fastify Backend API"]
Policy["Deterministic Policy Engine"]
Risk["Quantitative Risk Scoring Engine"]
Audit["Immutable Audit Logger"]
end
subgraph Data["Persistence & Caching"]
Postgres[(PostgreSQL / Prisma)]
Redis[(Redis Cache / RPC Limiter)]
end
subgraph Blockchain["Ethereum & Indexing Layer"]
Viem["Viem / EVM Execution Service"]
Alchemy["Alchemy Indexer APIs"]
Sepolia["Ethereum Sepolia Network"]
end
subgraph Frontend["Human Execution Layer"]
WebDashboard["Next.js 15 Dashboard"]
MetaMask["MetaMask / Browser Wallet"]
end
Claude <-->|JSON-RPC via MCP| MCPServer
MCPServer <--> ToolRegistry
ToolRegistry <--> Fastify
Fastify --> Policy
Fastify --> Risk
Fastify --> Audit
Fastify <--> Postgres
Fastify <--> Redis
Fastify <--> Viem
Viem <--> Alchemy
Viem <--> Sepolia
WebDashboard <-->|REST / WebSockets| Fastify
WebDashboard <-->|EIP-1193 Sign| MetaMask
MetaMask -->|Broadcast Raw Tx| Sepolia
sequenceDiagram
autonumber
actor User as Human Operator
participant AI as AI Agent (Claude)
participant MCP as WETH MCP Server
participant Policy as Policy & Risk Engine
participant DB as PostgreSQL DB
participant Web as Next.js Web Dashboard
participant Chain as Ethereum Sepolia
User->>AI: "Send 0.5 ETH to vitalik.eth if my risk profile is low."
AI->>MCP: resolve_ens({ name: "vitalik.eth" })
MCP->>Chain: ENS Registry Lookup
Chain-->>MCP: 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
MCP-->>AI: Resolved Address
AI->>MCP: simulate_transaction({ to, value: "0.5 ETH" })
MCP->>Chain: eth_call State Simulation
Chain-->>MCP: Simulation Success (Gas: 21000)
MCP-->>AI: Simulation Verified
AI->>MCP: analyze_transaction_risk({ to, value })
MCP->>Policy: Evaluate Rules & Risk Weight
Policy-->>MCP: Risk: LOW (12.5/100), Policy: APPROVED
MCP-->>AI: Risk Assessment Report
AI->>MCP: create_transaction_draft({ to, value, reason })
MCP->>DB: INSERT TransactionDraft (status: PENDING_APPROVAL)
DB-->>MCP: Draft ID: #tx_981a
MCP-->>AI: Draft Created. Waiting for Human Signature.
AI-->>User: "I simulated and drafted the transaction (#tx_981a). Please sign in the dashboard."
User->>Web: Opens WETH Web Dashboard -> Pending Transactions
Web->>DB: Fetch PENDING_APPROVAL Drafts
User->>Web: Click "Approve & Sign"
Web->>User: Prompt MetaMask Wallet Signature
User->>Web: Sign Transaction
Web->>Chain: eth_sendRawTransaction
Chain-->>Web: Tx Hash: 0x8f2a...
Web->>DB: Update Status -> COMPLETED (Recorded in Audit Log)
flowchart LR
A[AI Agent Request:<br>detect_risky_approvals] --> B[Fetch Token Holdings<br>via Alchemy Indexer]
B --> C[Iterate ERC20 Spender Allowances]
C --> D{Is Allowance > 1,000,000<br>or UNLIMITED?}
D -->|No| E[Mark Spender as Safe]
D -->|Yes| F{Is Spender Address<br>Verified Protocol?}
F -->|Yes| G[Flag as Informational High-Allowance]
F -->|No| H[ALERT: CRITICAL SPEND RISK<br>Unverified Unlimited Spender]
E --> I[Compile AI Audit Report]
G --> I
H --> I
WETH equips AI models with 13 strictly typed MCP tools grouped across four strategic operational layers:
| Tool Name | Parameters | Description |
|---|---|---|
get_balance |
address: string |
Retrieves the real-time native ETH balance of an address on Sepolia. |
get_token_balances |
address: string |
Fetches complete ERC20 token balances using Alchemy indexer APIs. |
get_transactions |
address: string, limit?: number |
Queries historical incoming and outgoing token transfers. |
get_wallet_summary |
address: string |
Returns an aggregated overview of balances, token counts, and recent activity. |
resolve_ens |
name: string |
Resolves Ethereum Name Service (.eth) domains to 0x addresses. |
| Tool Name | Parameters | Description |
|---|---|---|
estimate_gas |
from, to, value, data |
Calculates precise gas estimates and EIP-1559 fee parameters. |
simulate_transaction |
from, to, value, data |
Performs dry-run EVM state simulation to catch reverts before drafting. |
| Tool Name | Parameters | Description |
|---|---|---|
analyze_transaction_risk |
txPayload: TransactionDraft |
Evaluates transaction payload against deterministic policy rules and AI risk models. |
analyze_wallet |
address: string |
Performs deep portfolio concentration and asset distribution analysis. |
detect_risky_approvals |
address: string |
Scans wallet history for suspicious or unlimited ERC20 token spending allowances. |
| Tool Name | Parameters | Description |
|---|---|---|
create_transaction_draft |
to, value, data, reason |
Creates a zero-trust transaction draft flagged for human cryptographic approval. |
approve_transaction |
draftId: string |
Updates draft state in PostgreSQL after human review. |
broadcast_transaction |
signedTxHex: string |
Broadcasts raw signed transaction hex to Ethereum network. |
Figure 2: Dark-mode Web Dashboard displaying PENDING_APPROVAL AI drafts awaiting user MetaMask signature.
Figure 3: Expandable secret phrase management, chain selector, and human-in-the-loop transaction signing console.
Figure 4: Immutable ledger of signed transfers and contract interactions.
Figure 5: Claude autonomously inspecting balances, evaluating safety, and drafting transactions via WETH MCP Tools.
WETH is organized as a modular pnpm monorepo architected for scalability, strict type safety, and clean separation of concerns:
weth/
├── apps/
│ ├── api/ # Fastify REST API server with Policy & Risk validation
│ ├── mcp-server/ # Standard Stdio/SSE Model Context Protocol Server
│ └── web/ # Next.js 15 / React 19 / Wagmi Human Dashboard
├── packages/
│ ├── blockchain/ # Viem clients, Alchemy integration & ENS resolvers
│ ├── database/ # Prisma ORM schema & PostgreSQL migrations
│ └── shared/ # Zod schemas, Policy Engine, Risk Engine & Analytics
├── docs/ # Technical specifications & hackathon documentation
├── docker-compose.yml # PostgreSQL & Redis infrastructure containers
└── pnpm-workspace.yaml # Monorepo workspace configuration
- Node.js:
>= 20.x - pnpm:
>= 9.x - Docker & Docker Compose: For local PostgreSQL database and Redis caching instance.
git clone https://github.com/ayushkumar2601/wallet_weth.git
cd wallet_weth
pnpm installCopy .env.example to .env and configure your Sepolia RPC / Alchemy keys:
cp .env.example .envEnsure the following variables are set in your .env:
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/weth?schema=public"
REDIS_URL="redis://localhost:6379"
ALCHEMY_API_KEY="your_alchemy_api_key_here"
RPC_URL="https://eth-sepolia.g.alchemy.com/v2/your_alchemy_api_key_here"
PORT=3001Start PostgreSQL and Redis services via Docker Compose:
docker-compose up -d
pnpm prisma:generate
pnpm prisma:migrateRun all backend, MCP, and frontend services concurrently in development mode:
pnpm dev- Fastify API Server:
http://localhost:3001 - Next.js Web Dashboard:
http://localhost:3000 - MCP Server: Stdio stream or SSE endpoint ready for LLM connection.
To connect Claude Desktop directly to your local WETH Ethereum infrastructure, add the following configuration block to your claude_desktop_config.json:
{
"mcpServers": {
"weth-blockchain-agent": {
"command": "node",
"args": [
"/ABSOLUTE_PATH_TO/wallet_weth/apps/mcp-server/dist/index.js"
],
"env": {
"DATABASE_URL": "postgresql://postgres:postgres@localhost:5432/weth?schema=public",
"ALCHEMY_API_KEY": "your_alchemy_api_key_here"
}
}
}
}Once saved, restart Claude Desktop. You will see the hammer icon indicating all 13 WETH blockchain tools are active and ready for autonomous reasoning.
WETH is built for high-security environments. Every interaction between an AI model and the blockchain is permanently captured in the TransactionAudit database table:
model TransactionAudit {
id String @id @default(uuid())
toolName String // MCP tool invoked (e.g., create_transaction_draft)
requestPayload Json // Full JSON input passed by the LLM
responsePayload Json // Full JSON output / risk score returned
transactionId String? // Associated draft or on-chain tx hash
createdAt DateTime @default(now())
}This ensures complete institutional compliance and reproducibility: security teams can reconstruct the exact prompt, risk evaluation, and human signature associated with any on-chain event.
- Zero Private Key Exposure: The AI model operates strictly inside a sandboxed read/draft layer. No private keys are ever injected into LLM system prompts or server environment variables.
- Double-Layered Threshold Enforcements: Even if an AI agent experiences prompt injection or hallucination and drafts a malicious transaction, the backend Policy Engine deterministically blocks unauthorized payloads before they enter the human signing queue.
- Frontend Origin Verification: Only cryptographically signed payloads authorized by the user's browser wallet (MetaMask / EIP-1193) can trigger on-chain execution.
Built with precision for High-Assurance AI + Blockchain Infrastructure.
Made by Ayush with ❤️