lunarcrush-freqtrade-provider 1.0.1
LunarCrush sentiment data provider for FreqTrade
Requires Python: >=3.8

# LunarCrush FreqTrade External Data Provider

A professional-grade external data provider that integrates LunarCrush sentiment data with FreqTrade for cryptocurrency trading strategies.

## Overview

This provider fetches real-time cryptocurrency sentiment and social metrics from the LunarCrush API and makes them available to FreqTrade strategies. It includes advanced features like intelligent caching, timeframe conversion, and robust error handling.

## Features

- ✅ **22 Sentiment & Market Data Fields** - Complete coverage including social dominance, galaxy scores, and market metrics
- ✅ **Intelligent Caching** - Efficient data storage with configurable cache management
- ✅ **Timeframe Conversion** - Automatic conversion between different timeframes (1m to 1M)
- ✅ **Robust Error Handling** - Graceful degradation and comprehensive logging
- ✅ **Professional Testing** - 100% test coverage with 32 passing tests
- ✅ **Production Ready** - Clean architecture with proper separation of concerns

## Quick Start

### 1. Setup

```python
# In your FreqTrade strategy
from external_data_providers.lunarcrush import get_lunarcrush_provider

def __init__(self, config: dict):
    super().__init__(config)
    
    # Initialize LunarCrush provider
    bearer_token = os.environ.get('LUNARCRUSH_BEARER_TOKEN')
    if bearer_token:
        self.lunarcrush_provider = get_lunarcrush_provider(bearer_token)
```

### 2. Environment Variables

```bash
export LUNARCRUSH_BEARER_TOKEN="your_api_token_here"
```

### 3. Basic Usage

```python
def feature_engineering_expand_all(self, dataframe, period, metadata):
    if self.lunarcrush_provider:
        # Get sentiment features
        sentiment_df = self.lunarcrush_provider.get_sentiment_features(
            pair=metadata['pair'],
            timeframe=metadata['tf'],
            since_ms=int(dataframe['date'].iloc[0].timestamp() * 1000)
        )
        
        # Merge with price data
        if not sentiment_df.empty:
            dataframe = pd.concat([dataframe, sentiment_df], axis=1)
    
    return dataframe
```

## Available Data Fields

### Sentiment Metrics

- `lc_sentiment` - Overall sentiment score (-1 to 1)
- `lc_sentiment_absolute` - Absolute sentiment strength
- `lc_sentiment_relative` - Relative sentiment vs market
- `lc_social_dominance` - Social media dominance percentage
- `lc_social_volume` - Total social media mentions
- `lc_galaxy_score` - LunarCrush proprietary score (0-100)

### Market Data

- `lc_circulating_supply` - Circulating token supply
- `lc_market_cap` - Market capitalization
- `lc_market_dominance` - Market dominance percentage
- `lc_volume_24h` - 24-hour trading volume

### Community Metrics

- `lc_contributors_active` - Active social contributors
- `lc_interactions` - Social media interactions
- `lc_posts_active` - Active posts count

### Ranking Data

- `lc_alt_rank` - Alternative rank
- `lc_market_cap_rank` - Market cap rank
- `lc_correlation_rank` - Price correlation rank

*Plus additional technical indicators and scores*

## Configuration

```python
provider = get_lunarcrush_provider(
    bearer_token="your_token",
    cache_dir="external_data_providers/lunarcrush/data",  # Cache location
    update_interval_hours=1,                              # Update frequency
    max_cache_age_days=30                                # Cache retention
)
```

## Supported Timeframes

All standard FreqTrade timeframes:

- Intraday: `1m`, `3m`, `5m`, `15m`, `30m`, `1h`, `4h`, `12h`
- Daily+: `1d`, `3d`, `1w`, `2w`, `1M`

## Architecture

```mermaid
graph LR
    A[FreqTrade Strategy] --> B[LunarCrush Provider]
    B --> C[LunarCrush API]
    B --> D[Cache System + Converter]
```

### Key Components

- **`provider.py`** - Main API interface and caching logic
- **`converter.py`** - Timeframe conversion and data processing  
- **`client.py`** - HTTP client for LunarCrush API
- **`cache.py`** - Intelligent data caching system

**Test Coverage:**

- ✅ 32 tests passed (100% success rate)
- ⏭️ 4 tests skipped (external dependencies)
- 🧪 Covers all core functionality, edge cases, and integrations

### Test Categories

- **Converter Tests** - Field extraction, timeframe conversion, NaN handling
- **Provider Tests** - API integration, caching, datetime compatibility  
- **Strategy Integration** - End-to-end workflow validation

## Troubleshooting

### Common Issues

1. **Empty Data Returns**
   - Verify `LUNARCRUSH_BEARER_TOKEN` is set correctly
   - Check that the cryptocurrency is supported by LunarCrush
   - Ensure sufficient API credits remain

2. **Cache Issues**
   - Clear cache: `rm -rf external_data_providers/lunarcrush/data/`
   - Check disk space and permissions

3. **Timeframe Errors**
   - Verify timeframe format (e.g., `'1h'`, `'4h'`, `'1d'`)
   - Check that requested timeframe is supported

### Debug Mode

Enable verbose logging:

```python
import logging
logging.getLogger('external_data_providers.lunarcrush').setLevel(logging.DEBUG)
```

## API Limits

- **Rate Limit**: 10 requests/minute, 2000 requests/day
- **Caching**: Automatic to minimize API usage
- **Backoff**: Smart retry logic for rate limit handling

## Examples

See [`EnhancedBambooAI_SentimentROI.py`](../../strategies/EnhancedBambooAI_SentimentROI.py) for a complete implementation example.

## License

This external data provider is designed for use with FreqTrade and requires a valid LunarCrush API subscription.