1 line
60 KiB
JSON
1 line
60 KiB
JSON
{"repo": "brenwhyte/moon-dev-ai-agents", "files": {"docs/volume_agent.md": {"cbc2ddf1162c53dbdaa01389a81b0c78aa1df7f8": {"t": 1785746625.084107, "n": 10231, "h": "59242c8a6857d76d", "c": "# Hyperliquid Volume Agent - AI Swarm Edition\n\n**Built by Moon Dev**\n\nAn autonomous AI-powered agent that monitors Hyperliquid's top 15 highest-volume altcoins every 4 hours and uses a multi-model AI swarm to identify the best trading opportunities before they blow up on Crypto Twitter.\n\n---\n\n## What It Does\n\nThe Volume Agent continuously:\n1. Fetches top 15 highest-volume altcoins from Hyperliquid (excludes BTC/ETH/SOL)\n2. Tracks 4-hour volume changes, price movements, and rank shifts\n3. Analyzes market data with 5+ AI models running in parallel (via SwarmAgent)\n4. Provides individual AI recommendations + consensus pick\n5. Logs all data and analysis to CSV/JSONL files\n\n---\n\n## File Location\n\n- **Agent**: `src/agents/volume_agent.py`\n- **Data Directory**: `src/data/volume_agent/`\n - `volume_history.csv` - All volume snapshots\n - `agent_analysis.jsonl` - AI swarm analysis logs\n\n---\n\n## Quick Start\n\n```bash\n# Make sure you're in the right environment\nconda activate tflow\n\n# Single run (test mode)\npython src/agents/volume_agent.py --once\n\n# Continuous mode (checks every 4 hours)\npython src/agents/volume_agent.py\n\n# Run in background (24/7)\nnohup python src/agents/volume_agent.py > volume_agent.log 2>&1 &\n```\n\n---\n\n## Configuration\n\nAll settings are at the top of `volume_agent.py`:\n\n```python\n# Trade filtering\nEXCLUDED_TOKENS = ['BTC', 'ETH', 'SOL'] # Skip majors\nTOP_N = 15 # Top N altcoins to track\n\n# Check interval\nCHECK_INTERVAL = 4 * 60 * 60 # 4 hours\n\n# Data paths (auto-configured to project structure)\nDATA_DIR = \"src/data/volume_agent\"\n```\n\n---\n\n## Features\n\n### Data Collection\n- Real-time Hyperliquid API integration\n- Top 15 altcoins by 24h volume (majors excluded)\n- 4-hour volume change tracking\n- Price change monitoring (24h)\n- Rank movement detection\n- Funding rate analysis\n- Open interest tracking\n\n### AI Swarm Analysis\n- 5+ AI models query in parallel (via SwarmAgent)\n- Individual reasoning from each model\n- Consensus recommendation generation\n- Response time tracking\n- Success/failure handling\n\n### Terminal Output\n- Beautiful color-coded data tables\n- 170-character wide display for maximum data density\n- Auto-detected signals (NEW, VOL+50%, PUMP+30%, etc.)\n- Market snapshot summaries\n- Full AI recommendation display with reasoning\n- Clean data table for human analysis (after AI results)\n- Clean, scrollable format for all-day monitoring\n\n### Data Persistence\n- CSV logging of all volume snapshots (`volume_history.csv`)\n- JSONL logging of AI analysis (`agent_analysis.jsonl`)\n- Timestamped entries for historical analysis\n\n---\n\n## Terminal Output Example\n\n### Output Flow\n1. **Top 15 Altcoins Table** (with signals and colors)\n2. **Market Snapshot** (summary of key signals)\n3. **AI Swarm Analysis** (consensus + individual recommendations)\n4. **Data Table** (clean tabular view for human analysis)\n\n### Top 15 Altcoins Table\nShows all 15 tokens with:\n- Rank\n- Symbol\n- Price\n- 24H Volume\n- 4H Volume Change (GREEN = up, RED = down, YELLOW = new)\n- 24H Price Change (GREEN = up, RED = down)\n- Rank Movement (arrows showing up/down/stable)\n- Funding Rate (YELLOW = high, MAGENTA = negative)\n- Open Interest\n- Signals (auto-detected patterns)\n\n### Market Snapshot\nQuick summary showing:\n- New top-15 entries\n- Big 24H movers (>20%)\n- Volume accelerators (>50%)\n- Rank climbers\n\n### AI Swarm Analysis\n- **CONSENSUS RECOMMENDATION** (what all AIs agree on)\n- **INDIVIDUAL RECOMMENDATIONS** (all 5+ AIs with full reasoning)\n\n### Data Table (After AI Analysis)\nClean tabular view of all 15 tokens showing:\n- Rank, Symbol, Price\n- 24H Volume, 4H Volume Change, 24H Volume Change\n- 24H Price Change\n- Funding Rate, Open Interest\n\n**Purpose**: Compare AI recommendations with raw data to find your own edge!\n\n**Note**: 24H VOL Δ shows volume change over 24 hours (requires 6+ checks / 24h of history). Shows \"N/A\" for first day.\n\n---\n\n## Signals Explained\n\n- **NEW** - New top-15 entry\n- **VOL+50%** - Volume spiked >50% in 4h\n- **VOL+20%** - Volume increased >20% in 4h\n- **CLIMB+3** - Rank climbed 3+ positions\n- **PUMP+30%** - Price pumped >30% in 24h\n- **PUMP+15%** - Price pumped >15% in 24h\n\n---\n\n## Data Files\n\n### volume_history.csv\nAll volume snapshots with columns:\n- `timestamp`, `datetime`\n- `rank`, `symbol`\n- `volume_24h`, `price`\n- `change_24h_pct`, `funding_rate_pct`, `open_interest`\n\n### agent_analysis.jsonl\nAI swarm analysis logs with:\n- `timestamp`, `datetime`\n- `changes` - Array of market changes\n- `swarm_result` - Full swarm analysis with:\n - `consensus_summary` - AI consensus\n - `model_mapping` - Which AI corresponds to which provider\n - `responses` - Individual AI responses\n - `metadata` - Timing and success stats\n\n---\n\n## How It Works\n\n### 1. Data Fetching\n- `get_all_tokens_volume()` - Hits Hyperliquid API\n- `get_top_altcoins()` - Filters to top 15 altcoins\n- Uses Hyperliquid's `metaAndAssetCtxs` endpoint\n\n### 2. Change Calculation\n- `load_previous_snapshot()` - Loads last 4h snapshot from CSV\n- `calculate_changes()` - Compares current vs previous\n- Calculates:\n - 4-hour volume change percentage\n - Rank movement (up/down/new/stable)\n - Identifies new top-15 entries\n\n### 3. AI Swarm Analysis\n- `SwarmAgent()` - Initializes 5+ AI models\n- `swarm.query(prompt)` - Parallel queries with ThreadPoolExecutor\n- Process:\n 1. Creates detailed prompt with all 15 tokens + changes\n 2. Queries 5+ models in parallel\n 3. Collects individual responses\n 4. Generates consensus summary\n 5. Returns structured result with timing data\n\n### 4. Data Table Display\n- `display_data_table(changes)` - Shows clean tabular view\n- Displays after AI analysis for human comparison\n- Allows non-AI analysis and edge-finding\n- All 15 tokens with key metrics in one view\n\n### 5. Data Logging\n- `log_volume_snapshot(tokens)` - Appends to CSV\n- `log_agent_analysis(changes, swarm_result)` - Appends to JSONL\n\n---\n\n## Key Signals to Watch For\n\n### Volume Signals\n- **VOL+50%**: Massive volume spike - something BIG is happening\n- **VOL+20%**: Strong volume growth - increasing interest\n- Negative 4H volume: Cooling off, profit taking\n\n### Price Signals\n- **PUMP+30%**: Major price movement - verify volume confirmation\n- **PUMP+15%**: Solid momentum - check if sustainable\n- Price + Volume aligned: High conviction setup\n\n### Rank Signals\n- **CLIMB+3**: Token moving up ranks - gaining market share\n- **NEW**: Fresh entry to top 15 - catch early breakout\n- Stable rank: Established volume leader\n\n### Funding Rate\n- **YELLOW (>0.01%)**: Longs paying shorts - overheating warning\n- **MAGENTA (<-0.01%)**: Shorts paying longs - potential squeeze\n- **WHITE (normal)**: Balanced market\n\n### Liquidity (Open Interest)\n- **>$100M**: High liquidity - safe for larger positions\n- **$10M-$100M**: Medium liquidity - moderate position sizes\n- **<$10M**: Low liquidity - small positions only, risk of slippage\n\n---\n\n## Trading Strategy Ideas\n\n### Moon Dev's Approach: \"Data Dog Mode\"\n1. Watch all day - Terminal always open\n2. AI swarm validation - If 3+ AIs agree, high conviction\n3. Volume + Price confirmation - Both must align\n4. Check every 4 hours - Catch moves early\n5. Compare consensus changes - Track AI sentiment shifts\n\n### Signal Combinations\n1. **Strong Buy**: NEW + VOL+50% + PUMP+30% + AI consensus\n2. **Momentum Play**: CLIMB+3 + VOL+20% + High OI\n3. **Early Breakout**: NEW + Positive 4H volume + 3+ AI picks\n4. **Contrarian**: MAGENTA funding + Stable volume + High OI\n\n---\n\n## Dependencies\n\n### Core Libraries\n```bash\npip install requests termcolor\n```\n\n### Moon Dev Framework\n- `src/agents/swarm_agent.py` - Multi-model AI swarm\n- `src/models/model_factory.py` - Unified model interface\n\n### AI Model Providers (configured in `.env`)\n```bash\nDEEPSEEK_KEY=sk-your-deepseek-key\nGROK_API_KEY=xai-your-grok-key\nOPENROUTER_API_KEY=sk-or-your-openrouter-key\nANTHROPIC_KEY=sk-ant-your-claude-key\n# Add more as needed by SwarmAgent\n```\n\n---\n\n## API Costs\n\nRunning continuously with swarm mode:\n- **Per analysis**: ~5-6 models × 15 markets × 100 tokens = ~$0.10-0.50\n- **Per day**: 6 runs × $0.30 = ~$1.80/day\n- **Per month**: ~$54/month\n\nCost reduction:\n- Use cheaper models (DeepSeek, Groq are nearly free)\n- Reduce check frequency (e.g., 6 hours instead of 4)\n- Disable expensive models in SwarmAgent config\n\n---\n\n## Troubleshooting\n\n**Q: Module 'SwarmAgent' not found**\n- Ensure you're running from the project root\n- Check that `src/agents/swarm_agent.py` exists\n\n**Q: API key errors**\n- Verify `.env` file exists in project root\n- Check all required keys are present\n- Ensure keys are valid and have credit\n\n**Q: Connection refused to Hyperliquid**\n- Check internet connection\n- Hyperliquid API is public and requires no authentication\n- Verify API endpoint: `https://api.hyperliquid.xyz/info`\n\n**Q: Terminal output too wide**\n- Maximize terminal window\n- Or reduce width constant in code (currently 170 chars)\n\n---\n\n## Integration with Main Orchestrator\n\nTo add to `main.py`:\n\n```python\nfrom src.agents.volume_agent import run_check as volume_agent_check\n\n# In main loop:\nif should_run_agent('volume_agent'):\n volume_agent_check()\n```\n\nOr run standalone for 24/7 monitoring without orchestrator.\n\n---\n\n## Future Enhancements\n\nPlanned features:\n- Discord/Telegram notifications for high-conviction signals\n- Historical backtesting of AI consensus accuracy\n- Additional exchanges (dYdX, GMX, etc.)\n- Correlation analysis between tokens\n- Custom signal threshold configuration\n- Web dashboard for remote monitoring\n- Position size calculator based on liquidity\n- Stop-loss/take-profit suggestions from AI\n\n---\n\n## Disclaimers\n\n- **Not Financial Advice**: This is a research tool, not trading advice\n- **Use At Your Own Risk**: Trading crypto is highly risky\n- **No Guarantees**: Past performance ≠ future results\n- **API Costs**: Running 5+ AI models per check costs money\n- **Rate Limits**: Respect API rate limits for all services\n\n---\n\n## Support\n\nBuilt by Moon Dev for the Data Dogs\n\n**Location**: `/Users/md/Dropbox/dev/github/moon-dev-ai-agents-for-trading/src/agents/volume_agent.py`\n\n**Data**: `/Users/md/Dropbox/dev/github/moon-dev-ai-agents-for-trading/src/data/volume_agent/`\n\n---\n\nBuilt with Moon Dev 🌙\n\n*\"Catch the pumps BEFORE Crypto Twitter\"*\n"}, "a1295e35a2c5db31009b706e6c4bdb3ce8cf412f": {"t": 1785766384.6926396, "n": 10231, "h": "59242c8a6857d76d", "c": "# Hyperliquid Volume Agent - AI Swarm Edition\n\n**Built by Moon Dev**\n\nAn autonomous AI-powered agent that monitors Hyperliquid's top 15 highest-volume altcoins every 4 hours and uses a multi-model AI swarm to identify the best trading opportunities before they blow up on Crypto Twitter.\n\n---\n\n## What It Does\n\nThe Volume Agent continuously:\n1. Fetches top 15 highest-volume altcoins from Hyperliquid (excludes BTC/ETH/SOL)\n2. Tracks 4-hour volume changes, price movements, and rank shifts\n3. Analyzes market data with 5+ AI models running in parallel (via SwarmAgent)\n4. Provides individual AI recommendations + consensus pick\n5. Logs all data and analysis to CSV/JSONL files\n\n---\n\n## File Location\n\n- **Agent**: `src/agents/volume_agent.py`\n- **Data Directory**: `src/data/volume_agent/`\n - `volume_history.csv` - All volume snapshots\n - `agent_analysis.jsonl` - AI swarm analysis logs\n\n---\n\n## Quick Start\n\n```bash\n# Make sure you're in the right environment\nconda activate tflow\n\n# Single run (test mode)\npython src/agents/volume_agent.py --once\n\n# Continuous mode (checks every 4 hours)\npython src/agents/volume_agent.py\n\n# Run in background (24/7)\nnohup python src/agents/volume_agent.py > volume_agent.log 2>&1 &\n```\n\n---\n\n## Configuration\n\nAll settings are at the top of `volume_agent.py`:\n\n```python\n# Trade filtering\nEXCLUDED_TOKENS = ['BTC', 'ETH', 'SOL'] # Skip majors\nTOP_N = 15 # Top N altcoins to track\n\n# Check interval\nCHECK_INTERVAL = 4 * 60 * 60 # 4 hours\n\n# Data paths (auto-configured to project structure)\nDATA_DIR = \"src/data/volume_agent\"\n```\n\n---\n\n## Features\n\n### Data Collection\n- Real-time Hyperliquid API integration\n- Top 15 altcoins by 24h volume (majors excluded)\n- 4-hour volume change tracking\n- Price change monitoring (24h)\n- Rank movement detection\n- Funding rate analysis\n- Open interest tracking\n\n### AI Swarm Analysis\n- 5+ AI models query in parallel (via SwarmAgent)\n- Individual reasoning from each model\n- Consensus recommendation generation\n- Response time tracking\n- Success/failure handling\n\n### Terminal Output\n- Beautiful color-coded data tables\n- 170-character wide display for maximum data density\n- Auto-detected signals (NEW, VOL+50%, PUMP+30%, etc.)\n- Market snapshot summaries\n- Full AI recommendation display with reasoning\n- Clean data table for human analysis (after AI results)\n- Clean, scrollable format for all-day monitoring\n\n### Data Persistence\n- CSV logging of all volume snapshots (`volume_history.csv`)\n- JSONL logging of AI analysis (`agent_analysis.jsonl`)\n- Timestamped entries for historical analysis\n\n---\n\n## Terminal Output Example\n\n### Output Flow\n1. **Top 15 Altcoins Table** (with signals and colors)\n2. **Market Snapshot** (summary of key signals)\n3. **AI Swarm Analysis** (consensus + individual recommendations)\n4. **Data Table** (clean tabular view for human analysis)\n\n### Top 15 Altcoins Table\nShows all 15 tokens with:\n- Rank\n- Symbol\n- Price\n- 24H Volume\n- 4H Volume Change (GREEN = up, RED = down, YELLOW = new)\n- 24H Price Change (GREEN = up, RED = down)\n- Rank Movement (arrows showing up/down/stable)\n- Funding Rate (YELLOW = high, MAGENTA = negative)\n- Open Interest\n- Signals (auto-detected patterns)\n\n### Market Snapshot\nQuick summary showing:\n- New top-15 entries\n- Big 24H movers (>20%)\n- Volume accelerators (>50%)\n- Rank climbers\n\n### AI Swarm Analysis\n- **CONSENSUS RECOMMENDATION** (what all AIs agree on)\n- **INDIVIDUAL RECOMMENDATIONS** (all 5+ AIs with full reasoning)\n\n### Data Table (After AI Analysis)\nClean tabular view of all 15 tokens showing:\n- Rank, Symbol, Price\n- 24H Volume, 4H Volume Change, 24H Volume Change\n- 24H Price Change\n- Funding Rate, Open Interest\n\n**Purpose**: Compare AI recommendations with raw data to find your own edge!\n\n**Note**: 24H VOL Δ shows volume change over 24 hours (requires 6+ checks / 24h of history). Shows \"N/A\" for first day.\n\n---\n\n## Signals Explained\n\n- **NEW** - New top-15 entry\n- **VOL+50%** - Volume spiked >50% in 4h\n- **VOL+20%** - Volume increased >20% in 4h\n- **CLIMB+3** - Rank climbed 3+ positions\n- **PUMP+30%** - Price pumped >30% in 24h\n- **PUMP+15%** - Price pumped >15% in 24h\n\n---\n\n## Data Files\n\n### volume_history.csv\nAll volume snapshots with columns:\n- `timestamp`, `datetime`\n- `rank`, `symbol`\n- `volume_24h`, `price`\n- `change_24h_pct`, `funding_rate_pct`, `open_interest`\n\n### agent_analysis.jsonl\nAI swarm analysis logs with:\n- `timestamp`, `datetime`\n- `changes` - Array of market changes\n- `swarm_result` - Full swarm analysis with:\n - `consensus_summary` - AI consensus\n - `model_mapping` - Which AI corresponds to which provider\n - `responses` - Individual AI responses\n - `metadata` - Timing and success stats\n\n---\n\n## How It Works\n\n### 1. Data Fetching\n- `get_all_tokens_volume()` - Hits Hyperliquid API\n- `get_top_altcoins()` - Filters to top 15 altcoins\n- Uses Hyperliquid's `metaAndAssetCtxs` endpoint\n\n### 2. Change Calculation\n- `load_previous_snapshot()` - Loads last 4h snapshot from CSV\n- `calculate_changes()` - Compares current vs previous\n- Calculates:\n - 4-hour volume change percentage\n - Rank movement (up/down/new/stable)\n - Identifies new top-15 entries\n\n### 3. AI Swarm Analysis\n- `SwarmAgent()` - Initializes 5+ AI models\n- `swarm.query(prompt)` - Parallel queries with ThreadPoolExecutor\n- Process:\n 1. Creates detailed prompt with all 15 tokens + changes\n 2. Queries 5+ models in parallel\n 3. Collects individual responses\n 4. Generates consensus summary\n 5. Returns structured result with timing data\n\n### 4. Data Table Display\n- `display_data_table(changes)` - Shows clean tabular view\n- Displays after AI analysis for human comparison\n- Allows non-AI analysis and edge-finding\n- All 15 tokens with key metrics in one view\n\n### 5. Data Logging\n- `log_volume_snapshot(tokens)` - Appends to CSV\n- `log_agent_analysis(changes, swarm_result)` - Appends to JSONL\n\n---\n\n## Key Signals to Watch For\n\n### Volume Signals\n- **VOL+50%**: Massive volume spike - something BIG is happening\n- **VOL+20%**: Strong volume growth - increasing interest\n- Negative 4H volume: Cooling off, profit taking\n\n### Price Signals\n- **PUMP+30%**: Major price movement - verify volume confirmation\n- **PUMP+15%**: Solid momentum - check if sustainable\n- Price + Volume aligned: High conviction setup\n\n### Rank Signals\n- **CLIMB+3**: Token moving up ranks - gaining market share\n- **NEW**: Fresh entry to top 15 - catch early breakout\n- Stable rank: Established volume leader\n\n### Funding Rate\n- **YELLOW (>0.01%)**: Longs paying shorts - overheating warning\n- **MAGENTA (<-0.01%)**: Shorts paying longs - potential squeeze\n- **WHITE (normal)**: Balanced market\n\n### Liquidity (Open Interest)\n- **>$100M**: High liquidity - safe for larger positions\n- **$10M-$100M**: Medium liquidity - moderate position sizes\n- **<$10M**: Low liquidity - small positions only, risk of slippage\n\n---\n\n## Trading Strategy Ideas\n\n### Moon Dev's Approach: \"Data Dog Mode\"\n1. Watch all day - Terminal always open\n2. AI swarm validation - If 3+ AIs agree, high conviction\n3. Volume + Price confirmation - Both must align\n4. Check every 4 hours - Catch moves early\n5. Compare consensus changes - Track AI sentiment shifts\n\n### Signal Combinations\n1. **Strong Buy**: NEW + VOL+50% + PUMP+30% + AI consensus\n2. **Momentum Play**: CLIMB+3 + VOL+20% + High OI\n3. **Early Breakout**: NEW + Positive 4H volume + 3+ AI picks\n4. **Contrarian**: MAGENTA funding + Stable volume + High OI\n\n---\n\n## Dependencies\n\n### Core Libraries\n```bash\npip install requests termcolor\n```\n\n### Moon Dev Framework\n- `src/agents/swarm_agent.py` - Multi-model AI swarm\n- `src/models/model_factory.py` - Unified model interface\n\n### AI Model Providers (configured in `.env`)\n```bash\nDEEPSEEK_KEY=sk-your-deepseek-key\nGROK_API_KEY=xai-your-grok-key\nOPENROUTER_API_KEY=sk-or-your-openrouter-key\nANTHROPIC_KEY=sk-ant-your-claude-key\n# Add more as needed by SwarmAgent\n```\n\n---\n\n## API Costs\n\nRunning continuously with swarm mode:\n- **Per analysis**: ~5-6 models × 15 markets × 100 tokens = ~$0.10-0.50\n- **Per day**: 6 runs × $0.30 = ~$1.80/day\n- **Per month**: ~$54/month\n\nCost reduction:\n- Use cheaper models (DeepSeek, Groq are nearly free)\n- Reduce check frequency (e.g., 6 hours instead of 4)\n- Disable expensive models in SwarmAgent config\n\n---\n\n## Troubleshooting\n\n**Q: Module 'SwarmAgent' not found**\n- Ensure you're running from the project root\n- Check that `src/agents/swarm_agent.py` exists\n\n**Q: API key errors**\n- Verify `.env` file exists in project root\n- Check all required keys are present\n- Ensure keys are valid and have credit\n\n**Q: Connection refused to Hyperliquid**\n- Check internet connection\n- Hyperliquid API is public and requires no authentication\n- Verify API endpoint: `https://api.hyperliquid.xyz/info`\n\n**Q: Terminal output too wide**\n- Maximize terminal window\n- Or reduce width constant in code (currently 170 chars)\n\n---\n\n## Integration with Main Orchestrator\n\nTo add to `main.py`:\n\n```python\nfrom src.agents.volume_agent import run_check as volume_agent_check\n\n# In main loop:\nif should_run_agent('volume_agent'):\n volume_agent_check()\n```\n\nOr run standalone for 24/7 monitoring without orchestrator.\n\n---\n\n## Future Enhancements\n\nPlanned features:\n- Discord/Telegram notifications for high-conviction signals\n- Historical backtesting of AI consensus accuracy\n- Additional exchanges (dYdX, GMX, etc.)\n- Correlation analysis between tokens\n- Custom signal threshold configuration\n- Web dashboard for remote monitoring\n- Position size calculator based on liquidity\n- Stop-loss/take-profit suggestions from AI\n\n---\n\n## Disclaimers\n\n- **Not Financial Advice**: This is a research tool, not trading advice\n- **Use At Your Own Risk**: Trading crypto is highly risky\n- **No Guarantees**: Past performance ≠ future results\n- **API Costs**: Running 5+ AI models per check costs money\n- **Rate Limits**: Respect API rate limits for all services\n\n---\n\n## Support\n\nBuilt by Moon Dev for the Data Dogs\n\n**Location**: `/Users/md/Dropbox/dev/github/moon-dev-ai-agents-for-trading/src/agents/volume_agent.py`\n\n**Data**: `/Users/md/Dropbox/dev/github/moon-dev-ai-agents-for-trading/src/data/volume_agent/`\n\n---\n\nBuilt with Moon Dev 🌙\n\n*\"Catch the pumps BEFORE Crypto Twitter\"*\n"}}, "docs/volume_agent_README.md": {"cbc2ddf1162c53dbdaa01389a81b0c78aa1df7f8": {"t": 1785746625.1290216, "n": 17186, "h": "6a31e945f4c9d1bb", "c": "# Volume Agent - Hyperliquid Volume Tracker\n\n**Built by Moon Dev** 🌙\n\nAn autonomous AI-powered agent that monitors Hyperliquid's top 15 highest-volume altcoins every 4 hours and uses a multi-model AI swarm to identify volume acceleration patterns BEFORE they blow up on Crypto Twitter.\n\n---\n\n## 🎯 What It Does\n\nThe Volume Agent is a **pure volume tracker** that:\n\n1. **Fetches** top 15 highest-volume altcoins from Hyperliquid (excludes BTC/ETH/SOL)\n2. **Tracks** 4-hour and 24-hour volume changes\n3. **Detects** rank movements and new entries\n4. **Analyzes** with 5+ AI models running in parallel (SwarmAgent)\n5. **Provides** volume-only recommendations (NO price, funding, or OI data to AI)\n6. **Displays** clean data table for human analysis\n7. **Logs** all data to CSV/JSONL for historical tracking\n\n**The Edge**: Catch volume spikes BEFORE Crypto Twitter notices them!\n\n---\n\n## 🚀 Quick Start\n\n```bash\n# Make sure you're in the right environment\nconda activate tflow\n\n# Test run (single check)\npython src/agents/volume_agent.py --once\n\n# Continuous mode (checks every 4 hours)\npython src/agents/volume_agent.py\n\n# Background mode (24/7 monitoring)\nnohup python src/agents/volume_agent.py > volume_agent.log 2>&1 &\n```\n\n---\n\n## 📁 File Locations\n\n- **Agent**: `src/agents/volume_agent.py`\n- **Data Directory**: `src/data/volume_agent/`\n - `volume_history.csv` - All volume snapshots (every 4 hours)\n - `agent_analysis.jsonl` - AI swarm analysis results\n\n---\n\n## ⚙️ Configuration\n\nEdit constants at the top of `volume_agent.py`:\n\n```python\n# API\nHYPERLIQUID_API = \"https://api.hyperliquid.xyz/info\"\n\n# Data paths (auto-configured)\nDATA_DIR = \"src/data/volume_agent\"\n\n# Excluded tokens (skip majors)\nEXCLUDED_TOKENS = ['BTC', 'ETH', 'SOL']\n\n# Top N altcoins to track\nTOP_N = 15\n\n# Check interval (4 hours)\nCHECK_INTERVAL = 4 * 60 * 60\n```\n\n---\n\n## 📊 Terminal Output Flow\n\n### 1. Top 15 Altcoins Table (Colorful)\nShows all 15 tokens with:\n- Rank, Symbol, Price\n- 24H Volume\n- 4H Volume Change (GREEN = up, RED = down, YELLOW = new)\n- 24H Price Change\n- Rank Movement (arrows)\n- Funding Rate, Open Interest\n- **Auto-detected signals**: NEW, VOL+50%, VOL+20%, CLIMB+3, PUMP+30%, PUMP+15%\n\n### 2. Market Snapshot\nQuick summary showing:\n- New top-15 entries\n- Big 24H movers (>20%)\n- Volume accelerators (>50%)\n- Rank climbers (+3 or more)\n\n### 3. AI Swarm Analysis\n- **CONSENSUS RECOMMENDATION** (what all AIs agree on)\n- **INDIVIDUAL RECOMMENDATIONS** (all 5+ AIs with full reasoning)\n- Response times for each model\n- Success/failure stats\n\n### 4. Data Table (Clean View)\nRaw data table showing:\n- Rank, Symbol, Price\n- 24H Volume\n- **4H VOL Δ** (volume change over 4 hours)\n- **24H VOL Δ** (volume change over 24 hours)\n- 24H Price Change\n- Funding Rate, Open Interest\n\n**Purpose**: Compare AI picks with raw numbers to find your own edge!\n\n---\n\n## 🤖 AI Prompt Structure (VOLUME ONLY)\n\n### What the AI Receives\n\nThe AI swarm gets **VOLUME DATA ONLY** - no price, no funding, no open interest:\n\n```\nYou are a VOLUME TRACKER analyzing Hyperliquid volume patterns.\n\nYour ONLY job is to identify volume acceleration and momentum.\nDO NOT consider price, funding rates, or any other data.\n\n1. STRK:\n - Current 24H Volume: $65.10M\n - 4H Volume Change: NEW ENTRY\n - 24H Volume Change: +15.5%\n - Rank Movement: NEW ENTRY\n\n2. PUMP:\n - Current 24H Volume: $61.36M\n - 4H Volume Change: +12.4%\n - 24H Volume Change: -5.2%\n - Rank Movement: CLIMBED 3 spots\n```\n\n### AI Instructions\n\n```\nBased on VOLUME DATA ONLY, which token would you buy right now?\n\nConsider ONLY:\n- Volume acceleration (4H vs 24H trends)\n- Absolute volume size (bigger = more liquidity/interest)\n- Rank climbing patterns (gaining market share)\n- New entries with strong volume\n- Sustained volume growth vs flash spikes\n```\n\n### Why Volume Only?\n\n**No bias from:**\n- ❌ Price pumps without volume confirmation\n- ❌ Funding rates showing overheating\n- ❌ Open interest affecting risk assessment\n\n**Pure signal:**\n- ✅ Volume acceleration (NOW vs sustained)\n- ✅ Rank movements (market share shifts)\n- ✅ Absolute size (liquidity/interest)\n\n---\n\n## 📈 Key Metrics Explained\n\n### 4H VOL Δ (4-Hour Volume Change)\n- Shows volume change over the last 4 hours (since last check)\n- **NEW** = First time in top 15\n- Positive % = Volume increasing\n- Negative % = Volume decreasing\n\n### 24H VOL Δ (24-Hour Volume Change)\n- Shows volume change over the last 24 hours (6 checks ago)\n- **N/A** = Need 24+ hours of history (7+ checks)\n- Positive % = Sustained volume growth\n- Negative % = Volume declining over time\n\n### Comparing 4H vs 24H\n\n**Volume Acceleration Patterns:**\n\n- **4H > 24H**: Volume accelerating NOW (e.g., 4H: +45%, 24H: +22%)\n - 🔥 Strong short-term momentum\n\n- **4H < 24H**: Volume decelerating (e.g., 4H: +12%, 24H: +35%)\n - ⚠️ Momentum cooling off\n\n- **Both Positive**: Sustained growth (e.g., 4H: +20%, 24H: +18%)\n - ✅ Healthy uptrend\n\n- **Both Negative**: Sustained decline (e.g., 4H: -10%, 24H: -15%)\n - 🚨 Losing interest\n\n### Rank Movement\n- **CLIMBED X spots**: Moving up in volume rankings (gaining market share)\n- **DROPPED X spots**: Moving down in rankings (losing market share)\n- **STABLE**: Maintaining position\n- **NEW ENTRY**: Just entered top 15\n\n---\n\n## 🎨 Signal Explanations\n\nAuto-detected signals in the colorful table:\n\n- **🆕 NEW** - New top-15 entry (catch early breakouts)\n- **🔥 VOL+50%** - Volume spiked >50% in 4h (something BIG happening)\n- **📈 VOL+20%** - Volume increased >20% in 4h (strong interest)\n- **⬆️ CLIMB+3** - Rank climbed 3+ positions (gaining market share)\n- **🚀 PUMP+30%** - Price pumped >30% in 24h (verify with volume)\n- **💚 PUMP+15%** - Price pumped >15% in 24h (solid momentum)\n\n---\n\n## 📂 Data Files\n\n### volume_history.csv\n\nStores all volume snapshots (appends every 4 hours):\n\n```csv\ntimestamp,datetime,rank,symbol,volume_24h,price,change_24h_pct,funding_rate_pct,open_interest\n1762782524.398975,2025-11-10 09:48:44,1,STRK,65103000,0.3732,34.70,0.0013,265660000\n1762782524.398975,2025-11-10 09:48:44,2,PUMP,61360000,0.032184,11.30,0.0006,373810000\n```\n\n**Columns:**\n- `timestamp` - Unix timestamp\n- `datetime` - Human-readable datetime\n- `rank` - Position in top 15\n- `symbol` - Token symbol\n- `volume_24h` - 24-hour volume in USD\n- `price` - Current price\n- `change_24h_pct` - 24H price change %\n- `funding_rate_pct` - Funding rate %\n- `open_interest` - Open interest in USD\n\n### agent_analysis.jsonl\n\nStores AI swarm analysis (appends after each run):\n\n```json\n{\n \"timestamp\": 1762782524.3992379,\n \"datetime\": \"2025-11-10 09:48:44\",\n \"changes\": [...],\n \"swarm_result\": {\n \"consensus_summary\": \"All models picked STRK...\",\n \"model_mapping\": {\"AI #1\": \"DEEPSEEK\", \"AI #2\": \"XAI\", ...},\n \"responses\": {...},\n \"metadata\": {\"total_time\": 25.84, \"successful_responses\": 5}\n }\n}\n```\n\n---\n\n## 🧠 AI Swarm Configuration\n\nThe agent uses **SwarmAgent** with these models (configurable in `swarm_agent.py`):\n\n**Default Active Models:**\n- DeepSeek Chat (fast, cheap)\n- XAI Grok-4 (advanced reasoning)\n- Qwen 3 Max (via OpenRouter)\n- Claude Sonnet 4.5 (balanced)\n- GLM 4.6 (via OpenRouter)\n\n**Cost per run:** ~$0.10-0.50 (depends on models)\n\n**Edit models in:** `src/agents/swarm_agent.py` → `SWARM_MODELS` dict\n\n---\n\n## 💡 Trading Strategy Ideas\n\n### Moon Dev's \"Data Dog\" Approach\n\n1. **Watch all day** - Terminal always open\n2. **AI consensus validation** - If 3+ AIs agree, high conviction\n3. **Volume-only focus** - Pure acceleration signal\n4. **Compare 4H vs 24H** - Identify accelerating vs decelerating\n5. **Check every 4 hours** - Catch moves early\n\n### Volume Signal Combinations\n\n**Strong Buy Signals:**\n- NEW + 4H: NEW + 24H: +50% + AI consensus = Early high-volume breakout\n- CLIMB+3 + 4H: +45% + 24H: +22% + 3+ AI picks = Accelerating momentum\n- 4H: +50% + 24H: +30% + High volume ($100M+) = Sustained volume spike\n\n**Caution Signals:**\n- 4H: NEW + 24H: -20% = Fresh entry but volume declining (cooling off)\n- 4H: +10% + 24H: +60% = Decelerating (4H < 24H)\n- 4H: -15% + 24H: -30% = Sustained decline (avoid)\n\n**Neutral/Monitor:**\n- 4H: +20% + 24H: +18% = Steady growth (watch for acceleration)\n- NEW + 24H: N/A = Brand new, need more history\n\n---\n\n## 🔧 How It Works\n\n### 1. Data Fetching\n```python\nget_all_tokens_volume() # Hits Hyperliquid API\nget_top_altcoins() # Filters to top 15 altcoins (excludes BTC/ETH/SOL)\n```\n\nUses Hyperliquid's `metaAndAssetCtxs` endpoint - no API key required.\n\n### 2. Change Calculation\n```python\nload_previous_snapshot() # Loads 4h ago snapshot from CSV\nload_24h_snapshot() # Loads 24h ago snapshot (6 checks back)\ncalculate_changes() # Compares current vs previous\n```\n\nCalculates:\n- 4-hour volume change %\n- 24-hour volume change %\n- Rank movement (up/down/stable/new)\n\n### 3. AI Swarm Analysis\n```python\nswarm = SwarmAgent() # Initializes 5+ AI models\nresult = swarm.query(volume_prompt) # Parallel queries with ThreadPoolExecutor\n```\n\nProcess:\n1. Creates volume-only prompt (no price/funding/OI)\n2. Queries 5+ models in parallel (120s timeout per model)\n3. Collects individual responses\n4. Generates consensus summary using DeepSeek\n5. Returns structured result with timing data\n\n### 4. Data Display & Logging\n```python\ndisplay_changes() # Colorful table with signals\ndisplay_swarm_results() # AI consensus + individual picks\ndisplay_data_table() # Clean tabular view for humans\nlog_volume_snapshot() # Append to CSV\nlog_agent_analysis() # Append to JSONL\n```\n\n---\n\n## 📊 Example Output\n\n```\n==========================================================================================================\n📊 HYPERLIQUID TOP 15 ALTCOINS - COMPLETE MARKET VIEW 📊\n==========================================================================================================\n\n# SYMBOL PRICE 24H VOLUME 4H VOL Δ 24H PRICE Δ RANK Δ FUNDING OPEN INT SIGNALS\n──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\n1 STRK $0.3732 $65.10M NEW +34.70% NEW +0.0013% $265.66M 🆕NEW 🚀PUMP+30%\n2 PUMP $0.032184 $61.36M NEW +11.30% NEW +0.0006% $373.81M 🆕NEW\n3 VISTA $0.000009 $35.24M +45.60% +18.90% ↑ +3 +0.0008% $124.33M 🔥VOL+50% ⬆️CLIMB+3 💚PUMP+15%\n...\n\n==========================================================================================================\n🔍 MARKET SNAPSHOT:\n 🆕 New Top-15 Entries: STRK, PUMP, WLFI\n 🚀 24H Big Movers (>20%): STRK (+34.7%), VISTA (+18.9%)\n 🔥 Volume Accelerators (>50%): VISTA (+45.6%)\n ⬆️ Rank Climbers (+3 or more): VISTA (↑3)\n==========================================================================================================\n\n\n==========================================================================================================\n🧠 AI SWARM ANALYSIS - INDIVIDUAL RECOMMENDATIONS + CONSENSUS 🧠\n==========================================================================================================\n\n🎯 CONSENSUS RECOMMENDATION (ALL AIs AGREE):\n──────────────────────────────────────────────────────────────────────────────────────────────────────────\nAll five AI models unanimously selected VISTA as the best volume opportunity, citing explosive 4H volume\nacceleration (+45.6%), rank climbing (+3 spots), and strong absolute volume as key consensus factors.\n──────────────────────────────────────────────────────────────────────────────────────────────────────────\n\n📋 INDIVIDUAL AI RECOMMENDATIONS:\n──────────────────────────────────────────────────────────────────────────────────────────────────────────\n\n═══════════════════════════════════════════════════════════════════════════════════════════════════════════\n💬 AI #1: DEEPSEEK (Response Time: 6.35s)\n───────────────────────────────────────────────────────────────────────────────────────────────────────────\nBased on volume data, I would pick **VISTA**.\n\nVISTA shows explosive short-term acceleration (+45.6% in 4H) with a solid $35.24M absolute volume base.\nThe rank climb of 3 positions confirms genuine market interest shift, making it the strongest pure volume\nmomentum play right now.\n───────────────────────────────────────────────────────────────────────────────────────────────────────────\n\n[... other 4 AI responses ...]\n\n📊 SWARM STATS:\n ✅ Successful Responses: 5/5\n ⏱️ Total Analysis Time: 25.84s\n\n\n==========================================================================================================\n📊 TOP 15 DATA TABLE - RAW DATA FOR MOON DEV'S ANALYSIS 📊\n==========================================================================================================\n\nRANK SYMBOL PRICE 24H VOLUME 4H VOL Δ 24H VOL Δ 24H PRICE Δ FUNDING % OPEN INT\n──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\n1 STRK $0.373200 $65.10M NEW +15.50% +34.70% +0.0013% $265.66M\n2 PUMP $0.032184 $61.36M NEW -5.20% +11.30% +0.0006% $373.81M\n3 VISTA $0.000009 $35.24M +45.60% +22.10% +18.90% +0.0008% $124.33M\n...\n\n==========================================================================================================\n💡 Moon Dev Tip: Compare this data with AI consensus to find your edge!\n==========================================================================================================\n```\n\n---\n\n## 🛠️ Dependencies\n\n### Core Libraries\n```bash\npip install requests termcolor\n```\n\n### Moon Dev Framework\n- `src/agents/swarm_agent.py` - Multi-model AI swarm\n- `src/models/model_factory.py` - Unified model interface\n\n### AI Model API Keys (in `.env`)\n```bash\nDEEPSEEK_KEY=sk-your-deepseek-key\nGROK_API_KEY=xai-your-grok-key\nOPENROUTER_API_KEY=sk-or-your-openrouter-key\nANTHROPIC_KEY=sk-ant-your-claude-key\n# Add more as needed by SwarmAgent\n```\n\n---\n\n## 💰 Cost Estimation\n\n**Per check (every 4 hours):**\n- API calls: FREE (Hyperliquid public API)\n- AI swarm: ~$0.10-0.50 (5-6 models analyzing 15 tokens)\n\n**Daily cost:** 6 checks × $0.30 = ~$1.80/day\n\n**Monthly cost:** ~$54/month\n\n**Cost reduction tips:**\n- Use cheaper models (DeepSeek, Groq are nearly free)\n- Reduce check frequency (e.g., every 6 hours)\n- Disable expensive models in SwarmAgent config\n\n---\n\n## 🔥 Pro Tips\n\n### Finding Your Edge\n\n1. **Compare AI consensus with raw data** - Do the numbers support the AI pick?\n2. **Watch 4H vs 24H divergence** - Acceleration = opportunity\n3. **Track repeated picks** - If same token shows up in multiple runs = high conviction\n4. **Monitor new entries** - Fresh top-15 entries with growing volume = early catch\n5. **Check rank climbing** - Tokens moving up ranks = gaining market share\n\n### Example Analysis\n\n**AI says**: \"Buy VISTA\"\n**Your analysis**:\n- 4H VOL Δ: +45.6% ✅ (accelerating)\n- 24H VOL Δ: +22.10% ✅ (sustained growth)\n- Rank: CLIMBED 3 spots ✅ (gaining market share)\n- Volume: $35.24M ✅ (decent liquidity)\n\n**Decision**: Strong buy signal - all indicators align!\n\n---\n\n## ⚠️ Important Notes\n\n### Data Requirements\n\n- **First run**: Shows \"NEW\" for all tokens (no history yet)\n- **After 1 check (4h)**: Can calculate 4H VOL Δ\n- **After 7 checks (28h)**: Can calculate 24H VOL Δ\n\n**Best practice**: Let it run for 24-48 hours to build full dataset\n\n### Limitations\n\n- Hyperliquid only (not CEX or other DEXs)\n- Altcoins only (BTC/ETH/SOL excluded by default)\n- 4-hour intervals (not real-time tick data)\n- Requires internet connection\n- AI costs accumulate over time\n\n---\n\n## 🚨 Disclaimers\n\n- **Not Financial Advice**: This is a research tool, not trading advice\n- **Use At Your Own Risk**: Trading crypto is highly risky\n- **No Guarantees**: Past performance ≠ future results\n- **API Costs**: Running AI models costs money\n- **Educational Purpose**: For learning algorithmic trading patterns\n\n---\n\n## 📞 Support\n\n**Built by Moon Dev** for the Data Dogs 🐕\n\n**GitHub**: moon-dev-ai-agents-for-trading\n**Location**: `src/agents/volume_agent.py`\n**Data**: `src/data/volume_agent/`\n\n---\n\n## 🎯 Quick Reference\n\n### Commands\n```bash\n# Test run\npython src/agents/volume_agent.py --once\n\n# Continuous\npython src/agents/volume_agent.py\n\n# Background\nnohup python src/agents/volume_agent.py > volume_agent.log 2>&1 &\n\n# Stop background\npkill -f \"python src/agents/volume_agent.py\"\n```\n\n### Key Files\n- Agent: `src/agents/volume_agent.py`\n- Config: Edit constants at top of file\n- Data: `src/data/volume_agent/`\n- Swarm: `src/agents/swarm_agent.py`\n\n### Key Metrics\n- **4H VOL Δ**: Short-term volume change (last 4 hours)\n- **24H VOL Δ**: Long-term volume change (last 24 hours)\n- **Rank Movement**: Position change in top 15\n- **Signals**: NEW, VOL+50%, VOL+20%, CLIMB+3, PUMP+30%, PUMP+15%\n\n---\n\n**Built with Moon Dev** 🌙\n\n*\"Catch the volume pumps BEFORE Crypto Twitter\"*\n"}, "a1295e35a2c5db31009b706e6c4bdb3ce8cf412f": {"t": 1785766384.7905657, "n": 17186, "h": "6a31e945f4c9d1bb", "c": "# Volume Agent - Hyperliquid Volume Tracker\n\n**Built by Moon Dev** 🌙\n\nAn autonomous AI-powered agent that monitors Hyperliquid's top 15 highest-volume altcoins every 4 hours and uses a multi-model AI swarm to identify volume acceleration patterns BEFORE they blow up on Crypto Twitter.\n\n---\n\n## 🎯 What It Does\n\nThe Volume Agent is a **pure volume tracker** that:\n\n1. **Fetches** top 15 highest-volume altcoins from Hyperliquid (excludes BTC/ETH/SOL)\n2. **Tracks** 4-hour and 24-hour volume changes\n3. **Detects** rank movements and new entries\n4. **Analyzes** with 5+ AI models running in parallel (SwarmAgent)\n5. **Provides** volume-only recommendations (NO price, funding, or OI data to AI)\n6. **Displays** clean data table for human analysis\n7. **Logs** all data to CSV/JSONL for historical tracking\n\n**The Edge**: Catch volume spikes BEFORE Crypto Twitter notices them!\n\n---\n\n## 🚀 Quick Start\n\n```bash\n# Make sure you're in the right environment\nconda activate tflow\n\n# Test run (single check)\npython src/agents/volume_agent.py --once\n\n# Continuous mode (checks every 4 hours)\npython src/agents/volume_agent.py\n\n# Background mode (24/7 monitoring)\nnohup python src/agents/volume_agent.py > volume_agent.log 2>&1 &\n```\n\n---\n\n## 📁 File Locations\n\n- **Agent**: `src/agents/volume_agent.py`\n- **Data Directory**: `src/data/volume_agent/`\n - `volume_history.csv` - All volume snapshots (every 4 hours)\n - `agent_analysis.jsonl` - AI swarm analysis results\n\n---\n\n## ⚙️ Configuration\n\nEdit constants at the top of `volume_agent.py`:\n\n```python\n# API\nHYPERLIQUID_API = \"https://api.hyperliquid.xyz/info\"\n\n# Data paths (auto-configured)\nDATA_DIR = \"src/data/volume_agent\"\n\n# Excluded tokens (skip majors)\nEXCLUDED_TOKENS = ['BTC', 'ETH', 'SOL']\n\n# Top N altcoins to track\nTOP_N = 15\n\n# Check interval (4 hours)\nCHECK_INTERVAL = 4 * 60 * 60\n```\n\n---\n\n## 📊 Terminal Output Flow\n\n### 1. Top 15 Altcoins Table (Colorful)\nShows all 15 tokens with:\n- Rank, Symbol, Price\n- 24H Volume\n- 4H Volume Change (GREEN = up, RED = down, YELLOW = new)\n- 24H Price Change\n- Rank Movement (arrows)\n- Funding Rate, Open Interest\n- **Auto-detected signals**: NEW, VOL+50%, VOL+20%, CLIMB+3, PUMP+30%, PUMP+15%\n\n### 2. Market Snapshot\nQuick summary showing:\n- New top-15 entries\n- Big 24H movers (>20%)\n- Volume accelerators (>50%)\n- Rank climbers (+3 or more)\n\n### 3. AI Swarm Analysis\n- **CONSENSUS RECOMMENDATION** (what all AIs agree on)\n- **INDIVIDUAL RECOMMENDATIONS** (all 5+ AIs with full reasoning)\n- Response times for each model\n- Success/failure stats\n\n### 4. Data Table (Clean View)\nRaw data table showing:\n- Rank, Symbol, Price\n- 24H Volume\n- **4H VOL Δ** (volume change over 4 hours)\n- **24H VOL Δ** (volume change over 24 hours)\n- 24H Price Change\n- Funding Rate, Open Interest\n\n**Purpose**: Compare AI picks with raw numbers to find your own edge!\n\n---\n\n## 🤖 AI Prompt Structure (VOLUME ONLY)\n\n### What the AI Receives\n\nThe AI swarm gets **VOLUME DATA ONLY** - no price, no funding, no open interest:\n\n```\nYou are a VOLUME TRACKER analyzing Hyperliquid volume patterns.\n\nYour ONLY job is to identify volume acceleration and momentum.\nDO NOT consider price, funding rates, or any other data.\n\n1. STRK:\n - Current 24H Volume: $65.10M\n - 4H Volume Change: NEW ENTRY\n - 24H Volume Change: +15.5%\n - Rank Movement: NEW ENTRY\n\n2. PUMP:\n - Current 24H Volume: $61.36M\n - 4H Volume Change: +12.4%\n - 24H Volume Change: -5.2%\n - Rank Movement: CLIMBED 3 spots\n```\n\n### AI Instructions\n\n```\nBased on VOLUME DATA ONLY, which token would you buy right now?\n\nConsider ONLY:\n- Volume acceleration (4H vs 24H trends)\n- Absolute volume size (bigger = more liquidity/interest)\n- Rank climbing patterns (gaining market share)\n- New entries with strong volume\n- Sustained volume growth vs flash spikes\n```\n\n### Why Volume Only?\n\n**No bias from:**\n- ❌ Price pumps without volume confirmation\n- ❌ Funding rates showing overheating\n- ❌ Open interest affecting risk assessment\n\n**Pure signal:**\n- ✅ Volume acceleration (NOW vs sustained)\n- ✅ Rank movements (market share shifts)\n- ✅ Absolute size (liquidity/interest)\n\n---\n\n## 📈 Key Metrics Explained\n\n### 4H VOL Δ (4-Hour Volume Change)\n- Shows volume change over the last 4 hours (since last check)\n- **NEW** = First time in top 15\n- Positive % = Volume increasing\n- Negative % = Volume decreasing\n\n### 24H VOL Δ (24-Hour Volume Change)\n- Shows volume change over the last 24 hours (6 checks ago)\n- **N/A** = Need 24+ hours of history (7+ checks)\n- Positive % = Sustained volume growth\n- Negative % = Volume declining over time\n\n### Comparing 4H vs 24H\n\n**Volume Acceleration Patterns:**\n\n- **4H > 24H**: Volume accelerating NOW (e.g., 4H: +45%, 24H: +22%)\n - 🔥 Strong short-term momentum\n\n- **4H < 24H**: Volume decelerating (e.g., 4H: +12%, 24H: +35%)\n - ⚠️ Momentum cooling off\n\n- **Both Positive**: Sustained growth (e.g., 4H: +20%, 24H: +18%)\n - ✅ Healthy uptrend\n\n- **Both Negative**: Sustained decline (e.g., 4H: -10%, 24H: -15%)\n - 🚨 Losing interest\n\n### Rank Movement\n- **CLIMBED X spots**: Moving up in volume rankings (gaining market share)\n- **DROPPED X spots**: Moving down in rankings (losing market share)\n- **STABLE**: Maintaining position\n- **NEW ENTRY**: Just entered top 15\n\n---\n\n## 🎨 Signal Explanations\n\nAuto-detected signals in the colorful table:\n\n- **🆕 NEW** - New top-15 entry (catch early breakouts)\n- **🔥 VOL+50%** - Volume spiked >50% in 4h (something BIG happening)\n- **📈 VOL+20%** - Volume increased >20% in 4h (strong interest)\n- **⬆️ CLIMB+3** - Rank climbed 3+ positions (gaining market share)\n- **🚀 PUMP+30%** - Price pumped >30% in 24h (verify with volume)\n- **💚 PUMP+15%** - Price pumped >15% in 24h (solid momentum)\n\n---\n\n## 📂 Data Files\n\n### volume_history.csv\n\nStores all volume snapshots (appends every 4 hours):\n\n```csv\ntimestamp,datetime,rank,symbol,volume_24h,price,change_24h_pct,funding_rate_pct,open_interest\n1762782524.398975,2025-11-10 09:48:44,1,STRK,65103000,0.3732,34.70,0.0013,265660000\n1762782524.398975,2025-11-10 09:48:44,2,PUMP,61360000,0.032184,11.30,0.0006,373810000\n```\n\n**Columns:**\n- `timestamp` - Unix timestamp\n- `datetime` - Human-readable datetime\n- `rank` - Position in top 15\n- `symbol` - Token symbol\n- `volume_24h` - 24-hour volume in USD\n- `price` - Current price\n- `change_24h_pct` - 24H price change %\n- `funding_rate_pct` - Funding rate %\n- `open_interest` - Open interest in USD\n\n### agent_analysis.jsonl\n\nStores AI swarm analysis (appends after each run):\n\n```json\n{\n \"timestamp\": 1762782524.3992379,\n \"datetime\": \"2025-11-10 09:48:44\",\n \"changes\": [...],\n \"swarm_result\": {\n \"consensus_summary\": \"All models picked STRK...\",\n \"model_mapping\": {\"AI #1\": \"DEEPSEEK\", \"AI #2\": \"XAI\", ...},\n \"responses\": {...},\n \"metadata\": {\"total_time\": 25.84, \"successful_responses\": 5}\n }\n}\n```\n\n---\n\n## 🧠 AI Swarm Configuration\n\nThe agent uses **SwarmAgent** with these models (configurable in `swarm_agent.py`):\n\n**Default Active Models:**\n- DeepSeek Chat (fast, cheap)\n- XAI Grok-4 (advanced reasoning)\n- Qwen 3 Max (via OpenRouter)\n- Claude Sonnet 4.5 (balanced)\n- GLM 4.6 (via OpenRouter)\n\n**Cost per run:** ~$0.10-0.50 (depends on models)\n\n**Edit models in:** `src/agents/swarm_agent.py` → `SWARM_MODELS` dict\n\n---\n\n## 💡 Trading Strategy Ideas\n\n### Moon Dev's \"Data Dog\" Approach\n\n1. **Watch all day** - Terminal always open\n2. **AI consensus validation** - If 3+ AIs agree, high conviction\n3. **Volume-only focus** - Pure acceleration signal\n4. **Compare 4H vs 24H** - Identify accelerating vs decelerating\n5. **Check every 4 hours** - Catch moves early\n\n### Volume Signal Combinations\n\n**Strong Buy Signals:**\n- NEW + 4H: NEW + 24H: +50% + AI consensus = Early high-volume breakout\n- CLIMB+3 + 4H: +45% + 24H: +22% + 3+ AI picks = Accelerating momentum\n- 4H: +50% + 24H: +30% + High volume ($100M+) = Sustained volume spike\n\n**Caution Signals:**\n- 4H: NEW + 24H: -20% = Fresh entry but volume declining (cooling off)\n- 4H: +10% + 24H: +60% = Decelerating (4H < 24H)\n- 4H: -15% + 24H: -30% = Sustained decline (avoid)\n\n**Neutral/Monitor:**\n- 4H: +20% + 24H: +18% = Steady growth (watch for acceleration)\n- NEW + 24H: N/A = Brand new, need more history\n\n---\n\n## 🔧 How It Works\n\n### 1. Data Fetching\n```python\nget_all_tokens_volume() # Hits Hyperliquid API\nget_top_altcoins() # Filters to top 15 altcoins (excludes BTC/ETH/SOL)\n```\n\nUses Hyperliquid's `metaAndAssetCtxs` endpoint - no API key required.\n\n### 2. Change Calculation\n```python\nload_previous_snapshot() # Loads 4h ago snapshot from CSV\nload_24h_snapshot() # Loads 24h ago snapshot (6 checks back)\ncalculate_changes() # Compares current vs previous\n```\n\nCalculates:\n- 4-hour volume change %\n- 24-hour volume change %\n- Rank movement (up/down/stable/new)\n\n### 3. AI Swarm Analysis\n```python\nswarm = SwarmAgent() # Initializes 5+ AI models\nresult = swarm.query(volume_prompt) # Parallel queries with ThreadPoolExecutor\n```\n\nProcess:\n1. Creates volume-only prompt (no price/funding/OI)\n2. Queries 5+ models in parallel (120s timeout per model)\n3. Collects individual responses\n4. Generates consensus summary using DeepSeek\n5. Returns structured result with timing data\n\n### 4. Data Display & Logging\n```python\ndisplay_changes() # Colorful table with signals\ndisplay_swarm_results() # AI consensus + individual picks\ndisplay_data_table() # Clean tabular view for humans\nlog_volume_snapshot() # Append to CSV\nlog_agent_analysis() # Append to JSONL\n```\n\n---\n\n## 📊 Example Output\n\n```\n==========================================================================================================\n📊 HYPERLIQUID TOP 15 ALTCOINS - COMPLETE MARKET VIEW 📊\n==========================================================================================================\n\n# SYMBOL PRICE 24H VOLUME 4H VOL Δ 24H PRICE Δ RANK Δ FUNDING OPEN INT SIGNALS\n──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\n1 STRK $0.3732 $65.10M NEW +34.70% NEW +0.0013% $265.66M 🆕NEW 🚀PUMP+30%\n2 PUMP $0.032184 $61.36M NEW +11.30% NEW +0.0006% $373.81M 🆕NEW\n3 VISTA $0.000009 $35.24M +45.60% +18.90% ↑ +3 +0.0008% $124.33M 🔥VOL+50% ⬆️CLIMB+3 💚PUMP+15%\n...\n\n==========================================================================================================\n🔍 MARKET SNAPSHOT:\n 🆕 New Top-15 Entries: STRK, PUMP, WLFI\n 🚀 24H Big Movers (>20%): STRK (+34.7%), VISTA (+18.9%)\n 🔥 Volume Accelerators (>50%): VISTA (+45.6%)\n ⬆️ Rank Climbers (+3 or more): VISTA (↑3)\n==========================================================================================================\n\n\n==========================================================================================================\n🧠 AI SWARM ANALYSIS - INDIVIDUAL RECOMMENDATIONS + CONSENSUS 🧠\n==========================================================================================================\n\n🎯 CONSENSUS RECOMMENDATION (ALL AIs AGREE):\n──────────────────────────────────────────────────────────────────────────────────────────────────────────\nAll five AI models unanimously selected VISTA as the best volume opportunity, citing explosive 4H volume\nacceleration (+45.6%), rank climbing (+3 spots), and strong absolute volume as key consensus factors.\n──────────────────────────────────────────────────────────────────────────────────────────────────────────\n\n📋 INDIVIDUAL AI RECOMMENDATIONS:\n──────────────────────────────────────────────────────────────────────────────────────────────────────────\n\n═══════════════════════════════════════════════════════════════════════════════════════════════════════════\n💬 AI #1: DEEPSEEK (Response Time: 6.35s)\n───────────────────────────────────────────────────────────────────────────────────────────────────────────\nBased on volume data, I would pick **VISTA**.\n\nVISTA shows explosive short-term acceleration (+45.6% in 4H) with a solid $35.24M absolute volume base.\nThe rank climb of 3 positions confirms genuine market interest shift, making it the strongest pure volume\nmomentum play right now.\n───────────────────────────────────────────────────────────────────────────────────────────────────────────\n\n[... other 4 AI responses ...]\n\n📊 SWARM STATS:\n ✅ Successful Responses: 5/5\n ⏱️ Total Analysis Time: 25.84s\n\n\n==========================================================================================================\n📊 TOP 15 DATA TABLE - RAW DATA FOR MOON DEV'S ANALYSIS 📊\n==========================================================================================================\n\nRANK SYMBOL PRICE 24H VOLUME 4H VOL Δ 24H VOL Δ 24H PRICE Δ FUNDING % OPEN INT\n──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\n1 STRK $0.373200 $65.10M NEW +15.50% +34.70% +0.0013% $265.66M\n2 PUMP $0.032184 $61.36M NEW -5.20% +11.30% +0.0006% $373.81M\n3 VISTA $0.000009 $35.24M +45.60% +22.10% +18.90% +0.0008% $124.33M\n...\n\n==========================================================================================================\n💡 Moon Dev Tip: Compare this data with AI consensus to find your edge!\n==========================================================================================================\n```\n\n---\n\n## 🛠️ Dependencies\n\n### Core Libraries\n```bash\npip install requests termcolor\n```\n\n### Moon Dev Framework\n- `src/agents/swarm_agent.py` - Multi-model AI swarm\n- `src/models/model_factory.py` - Unified model interface\n\n### AI Model API Keys (in `.env`)\n```bash\nDEEPSEEK_KEY=sk-your-deepseek-key\nGROK_API_KEY=xai-your-grok-key\nOPENROUTER_API_KEY=sk-or-your-openrouter-key\nANTHROPIC_KEY=sk-ant-your-claude-key\n# Add more as needed by SwarmAgent\n```\n\n---\n\n## 💰 Cost Estimation\n\n**Per check (every 4 hours):**\n- API calls: FREE (Hyperliquid public API)\n- AI swarm: ~$0.10-0.50 (5-6 models analyzing 15 tokens)\n\n**Daily cost:** 6 checks × $0.30 = ~$1.80/day\n\n**Monthly cost:** ~$54/month\n\n**Cost reduction tips:**\n- Use cheaper models (DeepSeek, Groq are nearly free)\n- Reduce check frequency (e.g., every 6 hours)\n- Disable expensive models in SwarmAgent config\n\n---\n\n## 🔥 Pro Tips\n\n### Finding Your Edge\n\n1. **Compare AI consensus with raw data** - Do the numbers support the AI pick?\n2. **Watch 4H vs 24H divergence** - Acceleration = opportunity\n3. **Track repeated picks** - If same token shows up in multiple runs = high conviction\n4. **Monitor new entries** - Fresh top-15 entries with growing volume = early catch\n5. **Check rank climbing** - Tokens moving up ranks = gaining market share\n\n### Example Analysis\n\n**AI says**: \"Buy VISTA\"\n**Your analysis**:\n- 4H VOL Δ: +45.6% ✅ (accelerating)\n- 24H VOL Δ: +22.10% ✅ (sustained growth)\n- Rank: CLIMBED 3 spots ✅ (gaining market share)\n- Volume: $35.24M ✅ (decent liquidity)\n\n**Decision**: Strong buy signal - all indicators align!\n\n---\n\n## ⚠️ Important Notes\n\n### Data Requirements\n\n- **First run**: Shows \"NEW\" for all tokens (no history yet)\n- **After 1 check (4h)**: Can calculate 4H VOL Δ\n- **After 7 checks (28h)**: Can calculate 24H VOL Δ\n\n**Best practice**: Let it run for 24-48 hours to build full dataset\n\n### Limitations\n\n- Hyperliquid only (not CEX or other DEXs)\n- Altcoins only (BTC/ETH/SOL excluded by default)\n- 4-hour intervals (not real-time tick data)\n- Requires internet connection\n- AI costs accumulate over time\n\n---\n\n## 🚨 Disclaimers\n\n- **Not Financial Advice**: This is a research tool, not trading advice\n- **Use At Your Own Risk**: Trading crypto is highly risky\n- **No Guarantees**: Past performance ≠ future results\n- **API Costs**: Running AI models costs money\n- **Educational Purpose**: For learning algorithmic trading patterns\n\n---\n\n## 📞 Support\n\n**Built by Moon Dev** for the Data Dogs 🐕\n\n**GitHub**: moon-dev-ai-agents-for-trading\n**Location**: `src/agents/volume_agent.py`\n**Data**: `src/data/volume_agent/`\n\n---\n\n## 🎯 Quick Reference\n\n### Commands\n```bash\n# Test run\npython src/agents/volume_agent.py --once\n\n# Continuous\npython src/agents/volume_agent.py\n\n# Background\nnohup python src/agents/volume_agent.py > volume_agent.log 2>&1 &\n\n# Stop background\npkill -f \"python src/agents/volume_agent.py\"\n```\n\n### Key Files\n- Agent: `src/agents/volume_agent.py`\n- Config: Edit constants at top of file\n- Data: `src/data/volume_agent/`\n- Swarm: `src/agents/swarm_agent.py`\n\n### Key Metrics\n- **4H VOL Δ**: Short-term volume change (last 4 hours)\n- **24H VOL Δ**: Long-term volume change (last 24 hours)\n- **Rank Movement**: Position change in top 15\n- **Signals**: NEW, VOL+50%, VOL+20%, CLIMB+3, PUMP+30%, PUMP+15%\n\n---\n\n**Built with Moon Dev** 🌙\n\n*\"Catch the volume pumps BEFORE Crypto Twitter\"*\n"}}}} |