lunarcrush-provider 1.0.3

LunarCrush sentiment data provider

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

# In your FreqTrade strategy
from lunarcrush_provider 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

export LUNARCRUSH_BEARER_TOKEN="your_api_token_here"

3. Basic Usage

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

provider = get_lunarcrush_provider(
    bearer_token="your_token",
    cache_dir="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

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

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

import logging
logging.getLogger('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

License

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