warden-protocol · ccclin111 · Jan 5, 2026 · Jan 5, 2026 · Jan 5, 2026 · Jan 8, 2026
diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
@@ -0,0 +1,76 @@
+# Warden Agent Builder Incentive Programme
+
+## 專案目標
+為 Warden Protocol Agent Builder Incentive Programme 開發 AI agents，獲取獎勵（首月 Top 10 最高 $10,000/agent）。
+
+## 技術要求（官方）
+- 框架：僅支援 LangGraph（TypeScript 或 Python）
+- 部署：LangGraph Cloud 或自架（需要 API 可存取，不需要 UI）
+- 一個 LangGraph instance 只能有一個 agent
+- Agent 無法存取用戶錢包、無法儲存數據在 Warden 基礎設施（2026 初解除）
+- 可以連接外部 API、使用自己的資料庫
+
+## 獎勵條件
+- Clean code
+- Great docs
+- 創新或冷門類別有額外獎勵
+
+## API 格式規範（重要教訓）
+
+<rule name="array_response_format">
+GET /assistants 和 POST /threads/search 必須直接回傳陣列 [{...}]，不是 {assistants: [...]}。
+Why: 前端用 .map() 處理，物件包裝會導致 "t.map is not a function" 錯誤。
+</rule>
+
+<rule name="assistants_search_endpoint">
+必須實作 POST /assistants/search endpoint，Warden App 依賴此 API 獲取 assistant_id。
+Request: { "metadata": {}, "limit": 10, "offset": 0 }
+Response: 陣列格式 [{ assistant_id, graph_id, name, ... }]
+Why: 此 endpoint 容易漏掉，缺少會導致 agent 無法被發現。
+</rule>
+
+### 完整必要 endpoints 清單
+| Method | Endpoint | 回傳格式 |
+|--------|----------|----------|
+| GET | /health | 物件 |
+| GET | /info | 物件 |
+| GET | /assistants | 陣列 |
+| POST | /assistants/search | 陣列 |
+| POST | /threads/search | 陣列 |
+| POST | /threads/:id/runs/wait | 物件 |
+| POST | /threads/:id/runs/stream | SSE |
+
+## 已完成的 Agents
+1. ZenGuard Agent - AI 情感守護系統，保護加密交易者避免衝動決策
+   - GitHub: https://github.com/ccclin111/zenguard-agent
+   - 部署: https://zenguard-agent.onrender.com
+   - PR #30: https://github.com/warden-protocol/community-agents/pull/30
+   - 狀態: 等待審核
+
+2. DeFi Risk Scanner - AI 驅動的 DeFi 協議風險評估工具
+   - GitHub: https://github.com/ccclin111/defi-risk-scanner
+   - 部署: https://defi-risk-scanner.onrender.com
+   - PR #33: https://github.com/warden-protocol/community-agents/pull/33
+   - 狀態: 等待審核
+
+## 範例 Agents（官方）
+- langgraph-quick-start: 最簡單（TypeScript）
+- langgraph-quick-start-py: 最簡單（Python）
+- weather-agent: 推薦新手
+- coingecko-agent: 較複雜
+- portfolio-agent: 較複雜
+
+## 資源
+- community-agents repo: https://github.com/warden-protocol/community-agents
+- 文檔: https://github.com/warden-protocol/community-agents/tree/main/docs
+- Warden Discord: #developers
+- Agent Chat 測試: https://agentchat.vercel.app
+- Warden Studio: 即將上線（註冊和變現平台）
+
+## 發布流程
+1. 開發 agent
+2. 部署到 Render 或其他平台
+3. 在 Agent Chat 測試
+4. Fork community-agents，加入 agents/ 目錄
+5. 提交 PR
+6. Warden Studio 上線後註冊
diff --git a/README.md b/README.md
@@ -58,6 +58,7 @@ Awesome agents and tools built by the community! Add yours by submitting a PR to
 ### Agents
 
 - [Travel DeFi Agent](https://github.com/Joshua15310/travel-defi-agent): LangGraph agent for travel planning and expense optimization using Gemini AI and DeFi strategies.
+- [ZenGuard Agent](agents/zenguard-agent): AI emotional guardian that protects crypto traders from panic-driven decisions using sentiment analysis and Warden Protocol integration.
 
 ### Tools & Resources
 

diff --git a/agents/defi-risk-scanner/.env.example b/agents/defi-risk-scanner/.env.example
@@ -0,0 +1,10 @@
+# Server
+PORT=3000
+
+# OpenAI (optional - for future AI-powered analysis)
+OPENAI_API_KEY=your_openai_key
+
+# Data Source API Keys (optional - will use mock data if not provided)
+DEBANK_API_KEY=your_debank_api_key
+CERTIK_API_KEY=your_certik_api_key
+ETHERSCAN_API_KEY=your_etherscan_api_key
diff --git a/agents/defi-risk-scanner/.gitignore b/agents/defi-risk-scanner/.gitignore
@@ -0,0 +1,4 @@
+node_modules/
+dist/
+.env
+*.log
diff --git a/agents/defi-risk-scanner/LICENSE b/agents/defi-risk-scanner/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ccclin111
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/agents/defi-risk-scanner/README.md b/agents/defi-risk-scanner/README.md
@@ -0,0 +1,208 @@
+# DeFi Risk Scanner Agent
+
+> AI-powered DeFi protocol risk assessment tool for Warden Protocol
+
+## Overview
+
+DeFi Risk Scanner analyzes DeFi protocols across multiple dimensions to generate comprehensive risk scores, helping users make informed investment decisions.
+
+## Features
+
+- **Multi-source Data Collection**: Aggregates data from DeFiLlama, Certik, DeBank, and Etherscan
+- **Comprehensive Risk Scoring**: Evaluates contract security, TVL stability, team transparency, and on-chain behavior
+- **Real-time Warnings**: Identifies critical risk factors like whale concentration, TVL drops, and missing audits
+- **LangGraph Integration**: Built on LangGraph for Warden Protocol compatibility
+
+## Risk Scoring Model
+
+| Component | Weight | Factors |
+|-----------|--------|---------|
+| Contract Security | 40% | Audit status, contract age, code verification |
+| TVL & Liquidity | 30% | TVL size, change rate, multi-chain presence |
+| Team Transparency | 15% | Doxxed vs anonymous, public team |
+| On-chain Behavior | 15% | Whale concentration, holder count, abnormal activity |
+
+### Risk Levels
+
+- 🔴 **HIGH RISK** (Score < 50): Significant concerns, proceed with extreme caution
+- 🟡 **MEDIUM RISK** (Score 50-70): Some risk factors present, DYOR
+- 🟢 **LOW RISK** (Score > 70): Relatively safe, standard DeFi risks apply
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js 18+
+- npm or yarn
+
+### Installation
+
+```bash
+# Install dependencies
+npm install
+
+# Configure environment
+cp .env.example .env
+# Edit .env with your API keys (optional)
+
+# Run in development
+npm run dev
+
+# Build for production
+npm run build
+npm start
+```
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| PORT | No | Server port (default: 3000) |
+| OPENAI_API_KEY | No | For future AI analysis |
+| DEBANK_API_KEY | No | DeBank Pro API key |
+| CERTIK_API_KEY | No | Certik API key |
+| ETHERSCAN_API_KEY | No | Etherscan API key |
+
+> Note: The scanner works without API keys using DeFiLlama (free) and mock data for other sources.
+
+## API Reference
+
+### Health Check
+
+```
+GET /health
+```
+
+### Scan Protocol
+
+```
+POST /threads/{thread_id}/runs/wait
+Content-Type: application/json
+
+{
+  "input": {
+    "messages": [
+      { "role": "user", "content": "aave" }
+    ]
+  }
+}
+```
+
+Response:
+```json
+{
+  "status": "success",
+  "outputs": {
+    "messages": [{
+      "type": "ai",
+      "content": "🟢 DeFi Risk Report: Aave...",
+      "additional_kwargs": {
+        "risk_score": 82,
+        "risk_level": "LOW"
+      }
+    }]
+  }
+}
+```
+
+### Supported Inputs
+
+- Protocol name: `aave`, `uniswap`, `compound`
+- Contract address: `0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9`
+
+## Architecture
+
+```
+User Input
+    │
+    ▼
+┌─────────────┐
+│ Parse Input │ → Identify protocol/address
+└──────┬──────┘
+       │
+       ▼
+┌──────────────────────────────────────┐
+│        Parallel Data Collection       │
+│  ┌──────────┐ ┌────────┐ ┌────────┐  │
+│  │DeFiLlama│ │ Certik │ │DeBank  │  │
+│  │  (TVL)   │ │(Audit) │ │(Chain) │  │
+│  └──────────┘ └────────┘ └────────┘  │
+└──────────────────┬───────────────────┘
+                   │
+                   ▼
+          ┌────────────────┐
+          │  Risk Scorer   │ → Calculate weighted score
+          └───────┬────────┘
+                  │
+                  ▼
+          ┌────────────────┐
+          │ Risk Report    │ → Generate warnings & summary
+          └────────────────┘
+```
+
+## Example Output
+
+```
+🟡 DeFi Risk Report: Example Protocol
+
+📊 Overall Score: 58/100 (MEDIUM RISK)
+
+Component Scores:
+• Contract Security: 45/100
+• TVL & Liquidity: 72/100
+• Team Transparency: 50/100
+• On-chain Behavior: 65/100
+
+⚠️ Warnings:
+🚨 Protocol has NOT been audited
+⚠️ Team is anonymous
+⚠️ High whale concentration: 62.3% in top 10
+
+💡 Summary: This protocol has moderate risk factors. Found 1 critical issue(s). Found 2 warning(s). Always DYOR before investing.
+```
+
+## Data Sources
+
+| Source | Data | Status | Notes |
+|--------|------|--------|-------|
+| [DeFiLlama](https://defillama.com) | TVL, protocols | ✅ **Real API** | Free, no API key required |
+| [Certik](https://certik.com) | Audits, security scores | ⚠️ Mock* | Requires paid API key |
+| [DeBank](https://debank.com) | Token holders, on-chain | ⚠️ Mock* | Requires paid API key |
+| [Etherscan](https://etherscan.io) | Contract verification | ⚠️ Mock* | Free tier available |
+
+> **\*Mock Data**: Without API keys, these sources return simulated data based on protocol reputation.
+> The mock data provides reasonable estimates for well-known protocols (Aave, Uniswap, Compound, etc.)
+> but should not be relied upon for investment decisions. Add your API keys in `.env` for real data.
+
+### Current Default Behavior
+
+- **TVL & Protocol Data**: Real-time from DeFiLlama (always accurate)
+- **Audit Status**: Mock data assumes major protocols are audited
+- **On-chain Behavior**: Mock data with typical whale concentration values
+- **Contract Info**: Mock data with estimated contract age
+
+## Deployment
+
+### Render
+
+1. Connect GitHub repository
+2. Set environment variables
+3. Build command: `npm run build`
+4. Start command: `npm start`
+
+### Docker
+
+```bash
+docker build -t defi-risk-scanner .
+docker run -p 3000:3000 --env-file .env defi-risk-scanner
+```
+
+## License
+
+MIT
+
+## Links
+
+- [Warden Protocol](https://wardenprotocol.org)
+- [Agent Builder Programme](https://wardenprotocol.org/agent-builder)
+- [LangGraph Documentation](https://langchain-ai.github.io/langgraph)
diff --git a/agents/defi-risk-scanner/langgraph.json b/agents/defi-risk-scanner/langgraph.json
@@ -0,0 +1,8 @@
+{
+  "node_version": "20",
+  "graphs": {
+    "defi_risk_scanner": "./src/graph/index.ts:createScannerWorkflow"
+  },
+  "env": ".env",
+  "dependencies": ["."]
+}
diff --git a/agents/defi-risk-scanner/package.json b/agents/defi-risk-scanner/package.json
@@ -0,0 +1,40 @@
+{
+  "name": "defi-risk-scanner",
+  "version": "1.0.0",
+  "description": "DeFi Risk Scanner Agent for Warden Protocol - Analyzes DeFi protocol security risks",
+  "main": "dist/server.js",
+  "scripts": {
+    "dev": "ts-node src/server.ts",
+    "build": "tsc",
+    "start": "node dist/server.js",
+    "start:prod": "npm run build && npm run start"
+  },
+  "keywords": [
+    "defi",
+    "risk",
+    "security",
+    "warden",
+    "langgraph",
+    "agent"
+  ],
+  "author": "ccclin111",
+  "license": "MIT",
+  "dependencies": {
+    "@langchain/core": "^0.3.0",
+    "@langchain/langgraph": "^0.2.0",
+    "@langchain/openai": "^0.3.0",
+    "axios": "^1.7.0",
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.0",
+    "express": "^4.21.0",
+    "uuid": "^11.0.0"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.17",
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.0.0",
+    "@types/uuid": "^10.0.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.7.0"
+  }
+}