moon-dev-trading-agents

# Moon Dev's AI Trading Agents System

Expert knowledge for working with Moon Dev's experimental AI trading system that orchestrates 48+ specialized AI agents for cryptocurrency trading across Hyperliquid, Solana (BirdEye), Asterdex, and Extended Exchange.

## When to Use This Skill

Use this skill when:
- Working with Moon Dev's trading agents repository
- Need to understand agent architecture and capabilities
- Running, modifying, or creating trading agents
- Configuring trading system, exchanges, or LLM providers
- Debugging trading operations or agent interactions
- Understanding backtesting with RBI agent
- Setting up new exchanges or strategies

## Environment Setup Note

**For New Users**: This repo uses Python 3.10.9. If using conda, the README shows setting up an environment named `tflow`, but you can name it whatever you want. If you don't use conda, standard pip/venv works fine too.

## Quick Start Commands

```bash
# Activate your Python environment (conda, venv, or whatever you use)
# Example with conda: conda activate tflow
# Example with venv: source venv/bin/activate
# Use whatever environment manager you prefer

# Run main orchestrator (controls multiple agents)
python src/main.py

# Run individual agent
python src/agents/trading_agent.py
python src/agents/risk_agent.py
python src/agents/rbi_agent.py

# Update requirements after adding packages
pip freeze > requirements.txt
```

## Core Architecture

### Directory Structure

```
src/
├── agents/              # 48+ specialized AI agents (<800 lines each)
├── models/              # LLM provider abstraction (ModelFactory)
├── strategies/          # User-defined trading strategies
├── scripts/             # Standalone utility scripts
├── data/                # Agent outputs, memory, analysis results
├── config.py            # Global configuration
├── main.py              # Main orchestrator loop
├── nice_funcs.py        # Core trading utilities (~1,200 lines)
├── nice_funcs_hl.py     # Hyperliquid-specific functions
├── nice_funcs_extended.py # Extended Exchange functions
└── ezbot.py             # Legacy trading controller
```

### Key Components

**Agents** (src/agents/)
- Each agent is standalone executable
- Uses ModelFactory for LLM access
- Stores outputs in src/data/[agent_name]/
- Under 800 lines (split if longer)

**LLM Integration** (src/models/)
- ModelFactory provides unified interface
- Supports: Claude, GPT-4, DeepSeek, Groq, Gemini, Ollama
- Pattern: `ModelFactory.create_model('anthropic')`

**Trading Utilities**
- `nice_funcs.py`: Core functions (Solana/BirdEye)
- `nice_funcs_hl.py`: Hyperliquid exchange
- `nice_funcs_extended.py`: Extended Exchange (X10)

**Configuration**
- `config.py`: Trading settings, risk limits, agent behavior
- `.env`: API keys and secrets (never expose these)

## Agent Categories

**Trading**: trading_agent, strategy_agent, risk_agent, copybot_agent

**Market Analysis**: sentiment_agent, whale_agent, funding_agent, liquidation_agent, chartanalysis_agent

**Content**: chat_agent, clips_agent, tweet_agent, video_agent, phone_agent

**Research**: rbi_agent (codes backtests from videos/PDFs), research_agent, websearch_agent

**Specialized**: sniper_agent, solana_agent, tx_agent, million_agent, polymarket_agent, compliance_agent, swarm_agent

See AGENTS.md for complete list with descriptions.

## Common Workflows

### 1. Run Single Agent

```bash
# Activate your environment first
python src/agents/[agent_name].py
```

Each agent is standalone and can run independently.

### 2. Run Main Orchestrator

```bash
python src/main.py
```

Runs multiple agents in loop based on `ACTIVE_AGENTS` dict in main.py.

### 3. Change Exchange

Edit agent file or config:
```python
EXCHANGE = "hyperliquid"  # or "birdeye", "extended"
```

Then import corresponding functions:
```python
if EXCHANGE == "hyperliquid":
    from src import nice_funcs_hl as nf
elif EXCHANGE == "extended":
    from src import nice_funcs_extended as nf
```

### 4. Switch AI Model

Edit `src/config.py`:
```python
AI_MODEL = "claude-3-haiku-20240307"  # Fast, cheap
# AI_MODEL = "claude-3-sonnet-20240229"  # Balanced
# AI_MODEL = "claude-3-opus-20240229"  # Most powerful
```

Or use ModelFactory per-agent:
```python
from src.models.model_factory import ModelFactory
model = ModelFactory.create_model('deepseek')  # or 'openai', 'groq', etc.
response = model.generate_response(system_prompt, user_content, temperature, max_tokens)
```

### 5. Backtest Strategy (RBI Agent)

```python
python src/agents/rbi_agent.py
```

Provide: YouTube URL, PDF, or trading idea text
→ DeepSeek-R1 extracts strategy logic
→ Generates backtesting.py compatible code
→ Executes backtest, returns metrics

See WORKFLOWS.md for more examples.

## Development Rules

### CRITICAL Rules

1. **Keep files under 800 lines** - split into new files if longer
2. **NEVER move files** - can create new, but no moving without asking
3. **Use existing environment** - don't create new virtual environments, use the one from initial setup
4. **Update requirements.txt** after any pip install: `pip freeze > requirements.txt`
5. **Use real data only** - never synthetic/fake data
6. **Minimal error handling** - user wants to see errors, not over-engineered try/except
7. **Never expose API keys** - don't show .env contents

### Agent Development Pattern

Creating new agents:
```python
# 1. Use ModelFactory for LLM
from src.models.model_factory import ModelFactory
model = ModelFactory.create_model('anthropic')

# 2. Store outputs in src/data/
output_dir = "src/data/my_agent/"

# 3. Make independently executable
if __name__ == "__main__":
    # Standalone logic here

# 4. Follow naming: [purpose]_agent.py

# 5. Add to config.py if needed
```

### Backtesting

- Use `backtesting.py` library (NOT built-in indicators)
- Use `pandas_ta` or `talib` for indicators
- Sample data: `src/data/rbi/BTC-USD-15m.csv`

## Configuration Files

**config.py**: Trading settings
- `MONITORED_TOKENS`, `EXCLUDED_TOKENS`
- Position sizing: `usd_size`, `max_usd_order_size`
- Risk: `CASH_PERCENTAGE`, `MAX_LOSS_USD`, `MAX_GAIN_USD`
- Agent: `SLEEP_BETWEEN_RUNS_MINUTES`, `ACTIVE_AGENTS`
- AI: `AI_MODEL`, `AI_MAX_TOKENS`, `AI_TEMPERATURE`

**.env**: Secrets (NEVER expose)
- Trading APIs: `BIRDEYE_API_KEY`, `MOONDEV_API_KEY`, `COINGECKO_API_KEY`
- AI: `ANTHROPIC_KEY`, `OPENAI_KEY`, `DEEPSEEK_KEY`, `GROQ_API_KEY`, `GEMINI_KEY`
- Blockchain: `SOLANA_PRIVATE_KEY`, `HYPER_LIQUID_ETH_PRIVATE_KEY`, `RPC_ENDPOINT`
- Extended: `X10_API_KEY`, `X10_PRIVATE_KEY`, `X10_PUBLIC_KEY`, `X10_VAULT_ID`

## Exchange Support

**Hyperliquid** (`nice_funcs_hl.py`)
- EVM-compatible perpetuals DEX
- Functions: `market_buy()`, `market_sell()`, `get_position()`, `close_position()`
- Leverage up to 50x

**BirdEye/Solana** (`nice_funcs.py`)
- Solana spot token data and trading
- Functions: `token_overview()`, `token_price()`, `get_ohlcv_data()`
- Real-time market data for 15,000+ tokens

**Extended Exchange** (`nice_funcs_extended.py`)
- StarkNet-based perpetuals (X10)
- Auto symbol conversion (BTC → BTC-USD)
- Leverage up to 20x
- Functions match Hyperliquid API for compatibility

See docs/hyperliquid.md, docs/extended_exchange.md for exchange-specific guides.

## Data Flow Pattern

```
Config/Input → Agent Init → API Data Fetch → Data Parsing →
LLM Analysis (via ModelFactory) → Decision Output →
Result Storage (CSV/JSON in src/data/) → Optional Trade Execution
```

## Common Tasks

**Add new package:**
```bash
# Make sure your environment is activated first
pip install package-name
pip freeze > requirements.txt
```

**Read market data:**
```python
from src.nice_funcs import token_overview, get_ohlcv_data, token_price

overview = token_overview(token_address)
ohlcv = get_ohlcv_data(token_address, timeframe='1H', days_back=3)
price = token_price(token_address)
```

**Execute trade (Hyperliquid):**
```python
from src import nice_funcs_hl as nf
nf.market_buy("BTC", usd_amount=100, leverage=10)
position = nf.get_position("BTC")
nf.close_position("BTC")
```

**Execute trade (Extended):**
```python
from src import nice_funcs_extended as nf
nf.market_buy("BTC", usd_amount=100, leverage=15)
position = nf.get_position("BTC")
nf.close_position("BTC")
```

## Git Operations

**Current branch**: main
**Main branch for PRs**: main

**Recent commits:**
- dc55e90: websearch agent
- 921ead6: websearch_agent launched and rbi agent updated
- 6bb55c2: backtest dash

**Modified files** (current):
- .env_example
- src/agents/swarm_agent.py
- src/agents/trading_agent.py
- src/data/ohlcv_collector.py

## Documentation

**Main docs** (docs/):
- `CLAUDE.md`: Project overview and development guidelines
- `hyperliquid.md`, `hyperliquid_setup.md`: Hyperliquid exchange
- `extended_exchange.md`: Extended Exchange (X10) setup
- `rbi_agent.md`: Research-Based Inference agent
- `websearch_agent.md`: Web search capabilities
- `swarm_agent.md`: Multi-agent coordination
- `[agent_name].md`: Individual agent docs

**README files**:
- Root `README.md`: Project overview
- `src/models/README.md`: LLM provider guide

## Risk Management

- Risk Agent runs FIRST before any trading decisions
- Circuit breakers: `MAX_LOSS_USD`, `MINIMUM_BALANCE_USD`
- AI confirmation for position-closing (configurable)
- Default loop: every 15 minutes (`SLEEP_BETWEEN_RUNS_MINUTES`)

## Philosophy

This is an **experimental, educational project**:
- No guarantees of profitability
- Open source and free
- YouTube-driven development
- Community-supported via Discord
- No official token (avoid scams)

Goal: Democratize AI agent development through practical trading examples.

## Additional Resources

For complete agent list, see AGENTS.md
For workflow examples, see WORKFLOWS.md
For architecture details, see ARCHITECTURE.md

---

**Built with 🌙 by Moon Dev**

*"Never over-engineer, always ship real trading systems."*