--- 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:

1. Header Auth (Recommended): x-dune-api-key:
2. Query Param: ?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)

...