Web3 Investor

Web3 Investor Skill

Purpose: Enable AI agents to safely discover, analyze, and execute DeFi investments.

Core Philosophy: Data-driven decisions. No generic advice without real-time discovery.

⚠️ Critical Rules (MUST FOLLOW)

Rule 1: Discovery First

When user asks for investment advice:

❌ WRONG: Give generic advice immediately (e.g., "I recommend Aave")
✅ CORRECT: 
   1. Collect investment preferences (chain, token, risk tolerance)
   2. Run discovery to get real-time data
   3. Analyze data
   4. Provide data-backed recommendations

Rule 2: User's LLM Makes Decisions

• This skill provides raw data only
• Investment analysis and recommendations are the responsibility of the user's LLM/agent
• This skill is NOT responsible for investment outcomes

Rule 3: Risk Acknowledgment

• APY data comes from third-party APIs and may be delayed or inaccurate
• Investment decisions are made at the user's own risk
• Always DYOR (Do Your Own Research)

Rule 4: Verify Execution Capability Before Trading

Before attempting any transaction, the agent MUST check signer availability:

❌ WRONG: Directly call preview/execute without checking API
✅ CORRECT:
   1. Check if signer API is reachable (call balances endpoint)
   2. If unreachable → inform user: "Signer service unavailable, please check SETUP.md"
   3. Never proceed with preview if signer is unavailable

Health Check Command:

python3 scripts/trading/trade_executor.py balances --network base
# If success → signer is available
# If error E010 → signer unavailable, stop and inform user

Rule 5: Check Payment Capability FIRST (NEW in v0.5.0)

Before asking user for transaction details, ALWAYS check execution readiness:

❌ WRONG: Ask "How much do you want to invest?" without checking payment capability
✅ CORRECT:
   1. Run: python3 scripts/trading/preflight.py check --network <chain>
   2. Inform user of available payment methods
   3. Then ask for transaction details

Preflight Check Output:

{
  "recommended": "eip681_payment_link",
  "methods": [
    {"method": "keystore_signer", "status": "unavailable"},
    {"method": "eip681_payment_link", "status": "available"}
  ],
  "message": "⚠️ No local signer. Use EIP-681 payment link."
}

Payment Method Flow:

🎯 Quick Start for Agents

Step 1: Collect Investment Preferences (REQUIRED)

Before running discovery, ask the user:

Step 2: Run Discovery

# Basic search
python3 scripts/discovery/find_opportunities.py \
  --chain ethereum \
  --min-apy 5 \
  --limit 20

# With LLM-ready output
python3 scripts/discovery/find_opportunities.py \
  --chain ethereum \
  --llm-ready \
  --output json

Step 3: Filter by Preferences

from scripts.discovery.investment_profile import InvestmentProfile

profile = InvestmentProfile()
profile.set_preferences(
    chain="ethereum",
    capital_token="USDC",
    accept_il=False,
    reward_preference="single"
)
filtered = profile.filter_opportunities(opportunities)

Step 4: Execute Transaction (Choose Payment Method)

Option A: Keystore Signer (Production)

# Preview → Approve → Execute
python3 scripts/trading/trade_executor.py preview \
  --type deposit --protocol aave --asset USDC --amount 1000 --network base

python3 scripts/trading/trade_executor.py approve --preview-id <uuid>

python3 scripts/trading/trade_executor.py execute --approval-id <uuid>

Option B: EIP-681 Payment Link (Mobile)

python3 scripts/trading/eip681_payment.py generate \
  --token USDC --to 0x... --amount 10 --network base \
  --qr-output /tmp/payment_qr.png

📁 Project Structure

web3-investor/
├── scripts/
│   ├── discovery/           # Opportunity discovery tools
│   ├── trading/             # Transaction execution modules
│   └── portfolio/           # Balance queries
├── config/
│   ├── config.json          # Execution model & security settings
│   └── protocols.json       # Protocol registry
├── references/              # Detailed module documentation
│   ├── discovery.md
│   ├── investment-profile.md
│   ├── trade-executor.md
│   ├── portfolio-indexer.md
│   ├── protocols.md
│   └── risk-framework.md
└── SKILL.md

📚 Module Overview

🔍 Discovery Data Sources

Primary Data Sources

Dune MCP Integration

Dune provides powerful on-chain analytics through MCP (Model Context Protocol). Use Dune for:

• Custom on-chain data queries
• Protocol-specific analytics
• Historical trend analysis
• Whale wallet tracking

Configuration (config/config.json):

{
  "discovery": {
    "data_sources": ["mcp", "dune", "defillama"],
    "dune": {
      "mcp_endpoint": "https://api.dune.com/mcp/v1",
      "auth": {
        "header": { "name": "x-dune-api-key", "env_var": "DUNE_API_KEY" },
        "query_param": { "name": "api_key", "env_var": "DUNE_API_KEY" }
      }
    }
  }
}

Environment Setup:

# Required for Dune integration
export DUNE_API_KEY="your_dune_api_key"

Authentication Methods:

1. Header Auth (Recommended): x-dune-api-key: <DUNE_API_KEY>
2. Query Param: ?api_key=<DUNE_API_KEY>

Usage Example:

# Query Dune for protocol analytics
curl -H "x-dune-api-key: $DUNE_API_KEY" \
  "https://api.dune.com/mcp/v1/query/<query_id>/results"

⚙️ Configuration

Environment Variables

# Optional: Alchemy for better RPC
ALCHEMY_API_KEY=your_key_here

# Optional: Debank for portfolio tracking
WEB3_INVESTOR_DEBANK_API_KEY=your_key_here

# Trade Executor: Local API endpoint
WEB3_INVESTOR_API_URL=http://localhost:3000/api

Security Configuration (config/config.json)

{
  "security": {
    "max_trade_usd": 10000,
    "max_slippage_percent": 3.0,
    "whitelist_enabled": false,
    "whitelist_tokens": ["USDC", "USDT", "DAI", "WETH", "ETH", "stETH", "rETH"],
    "whitelist_protocols": ["uniswap", "aave", "compound", "lido", "0x"],
    "double_confirm": {
      "enabled": true,
      "large_trade_threshold_usd": 5000
    }
  }
}

Whitelist Configuration

Note: When whitelist_enabled is false (default), trade execution skips whitelist checks, allowing broader protocol/token access. Set to true to enforce strict whitelist validation.

Whitelist Setup

python3 scripts/trading/whitelist.py \
  --add 0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2 \
  --name "Aave V3 Pool" \
  --limit 10000

📝 Skill Author Template (MUST INCLUDE IN PROMPTS)

When using this skill for transaction generation, include this template:

Output structured transaction request (JSON), do not execute directly.
All transactions must go through preview -> approve -> execute.
If transaction parameters cannot be determined, return clarification, do not guess.

Required Output Format

{
  "request_id": "uuid",
  "timestamp": "ISO8601", 
  "network": "base|ethereum",
  "chain_id": 8453|1,
  "type": "transfer|swap|deposit|contract_call",
  "description": "human readable description",
  "transaction": {
    "to": "0x...",
    "value": "0x0",
    "data": "0x...",
    "gas_limit": 250000
  },
  "metadata": {
    "protocol": "uniswap|aave|compound|...",
    "from_token": "USDC",
    "to_token": "WETH", 
    "amount": "5"
  }
}

🆘 Troubleshooting

Import Errors

Run from workspace root:

cd /home/admin/.openclaw/workspace
python3 skills/web3-investor/scripts/discovery/find_opportunities.py ...

No Opportunities Found

• Check chain name spelling
• Try lowering --min-apy threshold
• Ensure --max-apy isn't too restrictive

Rate Limiting

• DefiLlama has generous limits but can occasionally rate limit
• Add delays between requests if batch processing

🤝 Contributing

Test donations welcome:

• Network: Base Chain
• Address: 0x1F3A9A450428BbF161C4C33f10bd7AA1b2599a3e

Maintainer: Web3 Investor Skill Team
Registry: https://clawhub.com/skills/web3-investor
License: MIT