TradingAgents/crypto_trading/docs/CRYPTO_PHASE1_README.md

# Crypto Market Support - Phase 1 Implementation Complete ✅

## Overview

Phase 1 of the crypto market migration has been successfully implemented! The TradingAgents framework now supports cryptocurrency market analysis alongside traditional equities.

## What's Been Implemented

### 1. **Data Infrastructure** ✅

#### CCXT Integration (Multi-Exchange Support)
- **File**: `tradingagents/dataflows/ccxt_vendor.py`
- **Features**:
  - OHLCV data from 100+ exchanges (Binance, Coinbase, Kraken, etc.)
  - Real-time ticker data
  - Order book depth analysis
  - Recent trades history
  - Exchange-level fundamentals (liquidity, volume)
- **No API key required** for public market data

#### Glassnode Integration (On-Chain Analytics)
- **File**: `tradingagents/dataflows/glassnode_vendor.py`
- **Features**:
  - Network health metrics (active addresses, transactions)
  - Exchange flow analysis (inflows/outflows)
  - Whale activity tracking
  - Valuation metrics (NVT ratio, MVRV)
  - Supply profitability analysis
- **Requires**: Glassnode API key (paid service)

#### Messari Integration (Crypto Fundamentals)
- **File**: `tradingagents/dataflows/messari_vendor.py`
- **Features**:
  - Asset profiles and tokenomics
  - Market metrics (price, volume, market cap)
  - Crypto news aggregation
  - Supply schedule analysis
  - Project fundamentals (consensus, technology)
- **Works without API key** (limited data)

### 2. **Configuration System** ✅

#### Crypto-Specific Config
- **File**: `tradingagents/crypto_config.py`
- **Key Settings**:
  ```python
  "data_vendors": {
      "core_stock_apis": "ccxt",
      "fundamental_data": "messari",
      "onchain_data": "glassnode"
  }
  ```
- **Risk Parameters** (adjusted for crypto volatility):
  - Max position size: 5% (vs 10% for stocks)
  - Max drawdown: 30% (vs 15% for stocks)
  - Risk multiplier: 3.0x (crypto is 3x more volatile)
- **Asset Tiers**:
  - BTC: 20% max position
  - ETH: 15% max position
  - Major altcoins: 5% max
  - Small caps: 2% max

#### Vendor Abstraction Layer
- **File**: `tradingagents/dataflows/interface.py` (updated)
- Seamlessly routes to appropriate data vendor based on config
- Supports fallback vendors if primary fails
- New category: "onchain_data" for crypto-specific metrics

### 3. **Environment Configuration** ✅

#### Updated .env.example
```bash
# Crypto Exchange Keys (optional - for authenticated endpoints)
BINANCE_API_KEY=your_key
BINANCE_API_SECRET=your_secret
COINBASE_API_KEY=your_key
COINBASE_API_SECRET=your_secret
KRAKEN_API_KEY=your_key
KRAKEN_API_SECRET=your_secret

# Crypto Data Providers
GLASSNODE_API_KEY=your_key
MESSARI_API_KEY=your_key
```

### 4. **Testing Suite** ✅

#### Test Script
- **File**: `test_crypto_data.py`
- **Tests**:
  - ✅ CCXT OHLCV data fetching
  - ✅ CCXT ticker and order book
  - ✅ Messari fundamentals and news
  - ✅ Glassnode on-chain metrics (if API key set)
- **Run**: `python test_crypto_data.py`

### 5. **Dependencies** ✅

#### Updated requirements.txt
```
ccxt              # Multi-exchange crypto data
glassnode         # On-chain analytics
python-dotenv     # Environment variable management
```

## Quick Start

### Installation

```bash
# 1. Install dependencies
pip install -r requirements.txt

# 2. Set up environment (optional - for premium features)
cp .env.example .env
# Edit .env with your API keys

# 3. Test the implementation
python test_crypto_data.py
```

### Basic Usage

#### Using CCXT for Crypto Market Data

```python
from tradingagents.dataflows.ccxt_vendor import get_crypto_ohlcv, get_crypto_ticker

# Get Bitcoin OHLCV data
btc_data = get_crypto_ohlcv(
    symbol="BTC/USDT",
    timeframe="1d",
    limit=30,
    exchange="binance"
)
print(btc_data)

# Get current ETH ticker
eth_ticker = get_crypto_ticker("ETH/USDT", "binance")
print(eth_ticker)
```

#### Using Messari for Fundamentals

```python
from tradingagents.dataflows.messari_vendor import get_crypto_fundamentals_messari

# Get Bitcoin fundamentals
btc_fundamentals = get_crypto_fundamentals_messari("bitcoin")
print(btc_fundamentals)
```

#### Using Glassnode for On-Chain Metrics

```python
from tradingagents.dataflows.glassnode_vendor import get_onchain_metrics

# Get BTC on-chain metrics (requires API key)
btc_onchain = get_onchain_metrics("BTC", days=30)
print(btc_onchain)
```

#### Using Crypto Config

```python
from tradingagents.crypto_config import get_crypto_config
from tradingagents.dataflows.config import set_config

# Switch to crypto configuration
crypto_config = get_crypto_config()
set_config(crypto_config)

# Now the framework uses crypto data vendors by default
```

## Architecture Changes

### Data Flow Comparison

**Before (Stocks Only)**:
```
Agent → interface.py → Alpha Vantage/yfinance → Stock Data
```

**After (Multi-Asset)**:
```
Agent → interface.py → Route based on config:
                      ├─ Alpha Vantage/yfinance → Stock Data
                      ├─ CCXT → Crypto Market Data
                      ├─ Messari → Crypto Fundamentals
                      └─ Glassnode → On-Chain Metrics
```

### New Data Categories

| Category | Stock Vendor | Crypto Vendor |
|----------|-------------|---------------|
| **Price Data** | yfinance | CCXT |
| **Fundamentals** | Alpha Vantage | Messari |
| **News** | Alpha Vantage | Messari |
| **On-Chain** | N/A | Glassnode |

## What Works Without API Keys

✅ **CCXT**: All public market data (OHLCV, tickers, order books)
✅ **Messari**: Basic fundamentals, news, market overview
❌ **Glassnode**: Requires paid API key for on-chain data

## API Rate Limits

| Service | Free Tier | Rate Limit |
|---------|-----------|------------|
| **CCXT** | ✅ Yes | Varies by exchange (~1200/min) |
| **Messari** | ✅ Yes (limited) | 20 requests/min |
| **Glassnode** | ❌ Paid only | 60 requests/min |

## Testing Results

Run the test suite to validate your setup:

```bash
python test_crypto_data.py
```

Expected output:
```
===============================================================================
  CRYPTO DATA INFRASTRUCTURE TEST SUITE - PHASE 1
===============================================================================

✅ CCXT: PASSED
✅ MESSARI: PASSED
⚠️  GLASSNODE: SKIPPED (API key required)

Results: 2/2 tests passed

🎉 All crypto data tests passed! Phase 1 implementation complete.
```

## Next Steps (Phase 2-5)

### Phase 2: Agent Adaptation (3-4 weeks)
- [ ] Create on-chain analyst agent
- [ ] Update fundamentals analyst prompts for tokenomics
- [ ] Enhance technical analyst with crypto indicators
- [ ] Adapt sentiment analyst for crypto social media

### Phase 3: Backtesting Validation (3-4 weeks)
- [ ] Build crypto backtesting engine
- [ ] Validate on historical bull/bear cycles
- [ ] Test multiple asset types (BTC, ETH, altcoins)
- [ ] Calibrate risk parameters

### Phase 4: Paper Trading (4-8 weeks)
- [ ] Exchange API integration for trading
- [ ] 24/7 monitoring system
- [ ] Validate execution quality
- [ ] Test emergency procedures

### Phase 5: Live Deployment (Ongoing)
- [ ] Start with BTC/ETH only
- [ ] Gradual altcoin expansion
- [ ] Continuous monitoring

## File Structure

```
TradingAgents/
├── tradingagents/
│   ├── dataflows/
│   │   ├── ccxt_vendor.py           # NEW: CCXT integration
│   │   ├── glassnode_vendor.py      # NEW: Glassnode integration
│   │   ├── messari_vendor.py        # NEW: Messari integration
│   │   └── interface.py             # UPDATED: Added crypto routing
│   ├── crypto_config.py             # NEW: Crypto configuration
│   └── default_config.py            # UNCHANGED: Stock config
├── test_crypto_data.py              # NEW: Test suite
├── CRYPTO_MIGRATION_PLAN.md         # Migration roadmap
├── CRYPTO_PHASE1_README.md          # This file
├── requirements.txt                 # UPDATED: Added crypto libs
└── .env.example                     # UPDATED: Added crypto keys
```

## Troubleshooting

### Import Errors
```bash
# Reinstall dependencies
pip install -r requirements.txt --upgrade
```

### CCXT Connection Issues
```python
# Test exchange connectivity
import ccxt
binance = ccxt.binance()
print(binance.fetch_ticker('BTC/USDT'))
```

### Glassnode 401 Errors
- Check that `GLASSNODE_API_KEY` is set correctly
- Verify your subscription is active
- Note: Free tier not available for Glassnode

## Known Limitations

1. **Glassnode requires paid subscription** - On-chain analytics are premium features
2. **CCXT rate limits vary** - Each exchange has different limits
3. **Messari free tier is limited** - Some endpoints require paid API key
4. **No trading execution yet** - Phase 1 is data-only (trading in Phase 4)

## Support & Documentation

- **CCXT Docs**: https://docs.ccxt.com/
- **Glassnode API**: https://docs.glassnode.com/
- **Messari API**: https://messari.io/api/docs

## Contributors

Phase 1 implementation completed on October 7, 2025.

---

**Status**: ✅ Phase 1 Complete - Ready for Phase 2 (Agent Adaptation)