name: web3-investor description: AI-friendly Web3 investment infrastructure for autonomous agents. Use when (1) discovering and analyzing DeFi/NFT investment opportunities, (2) executing secure transactions via local keystore signer REST API with preview-approve-execute state machine, (3) managing portfolio with dashboards and expiry alerts. Supports base and ethereum chains, configurable security constraints including whitelist protection, transaction limits, and mandatory simulation before execution.

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:

Recommended Method	Action
`keystore_signer`	Use `preview → approve → execute` flow
`eip681_payment_link`	Generate EIP-681 link with `eip681_payment.py`

🎯 Quick Start for Agents

Step 1: Collect Investment Preferences (REQUIRED)

Before running discovery, ask the user:

Preference	Key	Options	Why It Matters
Chain	`chain`	ethereum, base, arbitrum, optimism	Determines which blockchain to search
Capital Token	`capital_token`	USDC, USDT, ETH, WBTC, etc.	The token they want to invest
Reward Preference	`reward_preference`	single / multi / any	Single token rewards vs multiple tokens
Accept IL	`accept_il`	true / false / any	Impermanent loss tolerance
Underlying Type	`underlying_preference`	rwa / onchain / mixed / any	Real-world assets vs on-chain

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

Module	Purpose	Details
Discovery	Search DeFi yield opportunities	See references/discovery.md
Investment Profile	Preference collection & filtering	See references/investment-profile.md
Trade Executor	Transaction execution REST API	See references/trade-executor.md
Portfolio Indexer	On-chain balance queries	See references/portfolio-indexer.md

🔍 Discovery Data Sources

Primary Data Sources

Source	Type	Use Case
MCP (AntAlpha)	Real-time yields	Primary source for DeFi opportunities
DefiLlama	Protocol TVL/Yields	Fallback and cross-validation
Dune	On-chain analytics	Custom queries, advanced analysis

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:

Header Auth (Recommended): x-dune-api-key: <DUNE_API_KEY>
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

Parameter	Default	Description
`whitelist_enabled`	`false`	Enable/disable whitelist filtering in trade execution
`whitelist_tokens`	[...]	Allowed tokens for trading
`whitelist_protocols`	[...]	Allowed protocols for interaction

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

Web3 Investor

Description