Advanced Production-Ready Whale Tracking & Intelligence System for Hyperliquid DEX

These details have not been verified by PyPI

Project links

Project description

Hyperliquid Monitor Plus

💝 Found this library useful? Support continued development:
🔗 Wallet: 0xB05675CE390c895133dE8Aa1A873484f1FA1Df2C (Any amount appreciated!)

Advanced Production-Ready Whale Tracking & Intelligence System for Hyperliquid DEX

A comprehensive, enterprise-grade Python library for real-time monitoring, tracking, and analyzing whale wallet transactions on Hyperliquid DEX. Built with production-ready features including ML-powered intelligence, cross-chain tracking, advanced analytics, PnL management, and real-time dashboards.

🚀 Key Features

Core Monitoring

Real-time Trade Tracking: Monitor whale wallet fills (executed trades) with WebSocket streaming
Multi-Address Support: Track multiple wallet addresses simultaneously
Thread-Safe Operations: Production-ready with concurrent access handling
Automatic Database Storage: SQLite-based persistent storage with optimized queries
Correct Side Mapping: Properly handles Hyperliquid's side encoding (A=SELL, B=BUY)

Advanced Analytics & Intelligence

Whale Tier Classification: Automatic categorization (Minnow, Dolphin, Whale, Mega Whale, Giant Whale)
Market Impact Analysis: Predict price impact, slippage, and optimal entry timing
Volume Anomaly Detection: Identify unusual trading volumes and patterns
Correlation Engine: Track correlations between whale movements and market behavior
Sentiment Analysis: Integrate social sentiment into trading decisions
Pattern Recognition: ML-powered detection of recurring whale behaviors

PnL & Position Management

Real-Time PnL Tracking: Automatic profit/loss calculation per coin and portfolio
Position Tracking: Live position monitoring with liquidation risk alerts
Unrealized PnL: Dynamic calculation with current market prices
Portfolio Analytics: Comprehensive statistics, win rates, best/worst performers
Risk Assessment: Leverage tracking, margin monitoring, liquidation distance

Smart Alert System

Flexible Conditions: Custom alerts based on volume, price, coins, addresses
Alert Levels: Info, Warning, Critical with different notification strategies
Filter System: Advanced trade filtering by multiple criteria
Alert History: Track and analyze past alerts
Callback Support: Integrate with Discord, Telegram, or custom notifications

ML & Advanced Features (Phase 3)

Machine Learning Models: Predict whale behavior and price movements
Cross-Chain Analytics: Track whale activity across multiple blockchains
Portfolio Optimization: AI-powered position sizing and risk management
Real-Time Dashboard: Beautiful web interface with live updates
Predictive Intelligence: Forecast whale movements and market trends

Notifications & Integrations

Discord Integration: Automated alerts to Discord channels
Telegram Bots: Real-time notifications via Telegram
Custom Webhooks: Integrate with any external service
Report Generation: Automated HTML, PDF, and JSON reports

📦 Installation

Basic Installation

pip install hyperliquid-monitor-plus

Installation with Optional Features

# For visualization support (charts, graphs)
pip install hyperliquid-monitor-plus[viz]

# For machine learning features
pip install hyperliquid-monitor-plus[ml]

# For web dashboard
pip install hyperliquid-monitor-plus[web]

# For Discord/Telegram notifications
pip install hyperliquid-monitor-plus[notifications]

# For development (testing, linting, type checking)
pip install hyperliquid-monitor-plus[dev]

# Install everything
pip install hyperliquid-monitor-plus[all]

From Source

git clone https://github.com/Pezhman5252/hyperliquid_monitor_plus.git
cd hyperliquid_monitor_plus
pip install -e .

🎯 Quick Start

1. Basic Whale Monitoring

from hyperliquid_monitor_plus import HyperliquidMonitor, Trade

# Define callback for trades
def on_trade(trade: Trade):
    print(f"🐋 Whale Trade Detected!")
    print(f"   Coin: {trade.coin}")
    print(f"   Side: {trade.side}")
    print(f"   Size: {trade.size} @ ${trade.price}")
    print(f"   Value: ${trade.size * trade.price:,.2f}")
    print(f"   Address: {trade.address[:10]}...")
    if trade.leverage:
        print(f"   Leverage: {trade.leverage}x")
    print()

# Initialize monitor
monitor = HyperliquidMonitor(
    addresses=[
        "0x1234567890123456789012345678901234567890",  # Replace with actual whale address
        "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"   # Add more addresses
    ],
    db_path="whale_trades.db",  # Optional: store trades in database
    callback=on_trade,
    track_pnl=True  # Enable automatic PnL tracking
)

# Start monitoring
monitor.start()

2. Monitor with Alert System

from hyperliquid_monitor_plus import (
    HyperliquidMonitor,
    AlertManager,
    AlertCondition,
    AlertLevel,
    AlertType
)

# Create alert callback
def on_alert(alert):
    print(f"🚨 ALERT [{alert.level}]: {alert.message}")
    if alert.level == "CRITICAL":
        # Send urgent notification
        print(f"   URGENT: {alert.trade.coin} - ${alert.trade.size * alert.trade.price:,.0f}")

# Setup alert manager
alert_manager = AlertManager(alert_callback=on_alert)

# Add alert conditions
alert_manager.add_condition(
    AlertCondition(
        name="Large BTC Trade",
        alert_type=AlertType.LARGE_TRADE,
        level=AlertLevel.CRITICAL,
        min_volume_usd=1_000_000,  # $1M+ trades
        coins=["BTC"]
    )
)

alert_manager.add_condition(
    AlertCondition(
        name="ETH Whale Activity",
        alert_type=AlertType.WHALE_ACTIVITY,
        level=AlertLevel.WARNING,
        min_volume_usd=500_000,  # $500K+ trades
        coins=["ETH"]
    )
)

alert_manager.add_condition(
    AlertCondition(
        name="Any SELL Over $250K",
        alert_type=AlertType.VOLUME_SPIKE,
        level=AlertLevel.INFO,
        min_volume_usd=250_000,
        sides=["SELL"]
    )
)

# Start monitoring with alerts
monitor = HyperliquidMonitor(
    addresses=["0x1234..."],
    db_path="whale_trades.db",
    alert_callback=on_alert,
    track_pnl=True
)

monitor.start()

3. Advanced PnL Tracking

from hyperliquid_monitor_plus import HyperliquidMonitor, PnLManager

# Create PnL callback
def on_pnl_update(pnl_record):
    if pnl_record.pnl > 0:
        print(f"✅ Profitable Close: {pnl_record.coin}")
    else:
        print(f"❌ Loss Taken: {pnl_record.coin}")
    print(f"   PnL: ${pnl_record.pnl:,.2f}")
    print(f"   Entry: ${pnl_record.entry_price:.2f} -> Exit: ${pnl_record.exit_price:.2f}")
    print(f"   Size: {pnl_record.size}")

# Initialize with PnL tracking
monitor = HyperliquidMonitor(
    addresses=["0x1234..."],
    db_path="whale_trades.db",
    pnl_callback=on_pnl_update,
    track_pnl=True
)

# Access PnL manager
pnl_manager = monitor.pnl_manager

# Start monitoring
monitor.start()

# In another thread/after some trades, you can query:
# Get portfolio statistics
stats = pnl_manager.get_statistics()
print(f"Total Realized PnL: ${stats['total_realized_pnl']:,.2f}")
print(f"Total Unrealized PnL: ${stats['total_unrealized_pnl']:,.2f}")
print(f"Net PnL (after fees): ${stats['net_pnl']:,.2f}")
print(f"Win Rate: {stats['win_rate']:.1f}%")

# Get specific coin PnL
btc_pnl = pnl_manager.get_coin_pnl("BTC")
if btc_pnl:
    print(f"BTC Trades: {btc_pnl.trades_count}")
    print(f"BTC Realized PnL: ${btc_pnl.realized_pnl:,.2f}")
    print(f"BTC Win/Loss: {btc_pnl.winning_trades}/{btc_pnl.losing_trades}")

# Generate summary report
report = pnl_manager.get_summary_report()
print(report)

4. Live Position Tracking

from hyperliquid_monitor_plus import PositionTracker

# Create position change callback
def on_position_change(change):
    print(f"📍 Position {change.event_type}: {change.coin}")
    if change.old_position:
        print(f"   Old: {change.old_position.side} {change.old_position.size}")
    if change.new_position:
        print(f"   New: {change.new_position.side} {change.new_position.size}")
    print(f"   Size Change: {change.size_change:+.4f}")
    print(f"   PnL Change: ${change.pnl_change:+,.2f}")

# Initialize position tracker
tracker = PositionTracker(
    address="0x1234567890123456789012345678901234567890",
    position_callback=on_position_change
)

# Fetch current positions
snapshot = tracker.fetch_positions()
print(f"Total Unrealized PnL: ${snapshot.total_unrealized_pnl:,.2f}")
print(f"Margin Used: ${snapshot.total_margin_used:,.2f}")
print(f"Account Value: ${snapshot.account_value:,.2f}")

# Get open positions
open_positions = tracker.get_open_positions()
for coin, position in open_positions.items():
    print(f"{coin}: {position.side} {position.size} @ ${position.entry_price:.2f}")
    print(f"  Mark Price: ${position.mark_price:.2f}")
    print(f"  Unrealized PnL: ${position.unrealized_pnl:,.2f} ({position.pnl_percentage:+.2f}%)")
    print(f"  Leverage: {position.leverage}x")
    if position.liquidation_price:
        print(f"  Liquidation: ${position.liquidation_price:.2f} ({position.distance_to_liquidation:.1f}% away)")

# Check risky positions
risky = tracker.get_risky_positions(threshold=15.0)  # 15% from liquidation
if risky:
    print(f"⚠️ WARNING: {len(risky)} position(s) at risk!")
    for pos in risky:
        print(f"  {pos.coin}: {pos.distance_to_liquidation:.1f}% to liquidation")

# Get comprehensive statistics
stats = tracker.get_statistics()
print(f"Open Positions: {stats['open_positions_count']}")
print(f"Best Position: {stats['best_position']} (${stats['best_pnl']:,.2f})")
print(f"Worst Position: {stats['worst_position']} (${stats['worst_pnl']:,.2f})")

📚 Comprehensive Usage Guide

Working with the Database

from hyperliquid_monitor_plus import Database, init_database

# Initialize database
db_path = "whale_trades.db"
db = init_database(db_path)

# Or use Database class directly
db = Database(db_path)

# Query recent trades
recent_trades = db.get_recent_trades(limit=10)
for trade in recent_trades:
    print(f"{trade.timestamp} - {trade.coin} {trade.side} {trade.size} @ ${trade.price}")

# Query trades by coin
btc_trades = db.get_trades_by_coin("BTC", limit=50)
print(f"Found {len(btc_trades)} BTC trades")

# Query trades by address
whale_trades = db.get_trades_by_address("0x1234...", limit=100)

# Query trades by date range
from datetime import datetime, timedelta
start_date = datetime.now() - timedelta(days=7)
end_date = datetime.now()
weekly_trades = db.get_trades_by_date_range(start_date, end_date)

# Get trade statistics
stats = db.get_trade_statistics(coin="ETH")
print(f"Total ETH Volume: ${stats['total_volume']:,.2f}")
print(f"Average Trade Size: {stats['avg_size']:.4f}")
print(f"Largest Trade: {stats['max_size']:.4f} @ ${stats['max_price']:.2f}")

# Get unique coins and addresses
coins = db.get_unique_coins()
addresses = db.get_unique_addresses()

# Close database when done
db.close()

Advanced Alert Configuration

from hyperliquid_monitor_plus import (
    AlertManager,
    AlertCondition,
    AlertLevel,
    AlertType,
    TradeFilter
)

alert_manager = AlertManager()

# Multi-coin large trade alert
alert_manager.add_condition(
    AlertCondition(
        name="Major Altcoin Movement",
        alert_type=AlertType.LARGE_TRADE,
        level=AlertLevel.WARNING,
        min_volume_usd=100_000,
        coins=["SOL", "AVAX", "ARB", "OP"],
        message_template="🔔 Large {side} on {coin}: {size} @ ${price} (${volume_usd:,.0f})"
    )
)

# Specific address monitoring
alert_manager.add_condition(
    AlertCondition(
        name="Known Whale Activity",
        alert_type=AlertType.WHALE_ACTIVITY,
        level=AlertLevel.CRITICAL,
        addresses=["0xspecificwhale..."],
        min_volume_usd=50_000,
        message_template="🐋 Known whale {address} {side} {coin}: ${volume_usd:,.0f}"
    )
)

# Liquidation monitoring (based on side patterns)
alert_manager.add_condition(
    AlertCondition(
        name="Possible Liquidations",
        alert_type=AlertType.LIQUIDATION,
        level=AlertLevel.INFO,
        min_volume_usd=200_000,
        sides=["SELL"],
        message_template="⚡ Potential liquidation: {coin} - ${volume_usd:,.0f}"
    )
)

# Enable/disable conditions dynamically
alert_manager.disable_condition("Known Whale Activity")
alert_manager.enable_condition("Known Whale Activity")

# Update condition parameters
alert_manager.update_condition(
    "Major Altcoin Movement",
    min_volume_usd=150_000,
    level=AlertLevel.CRITICAL
)

# Get alert statistics
stats = alert_manager.get_statistics()
print(f"Total Conditions: {stats['total_conditions']}")
print(f"Enabled: {stats['enabled_conditions']}")
print(f"Total Triggered: {stats['total_triggered']}")

# Get alert history
recent_alerts = alert_manager.get_history(limit=20)
for alert in recent_alerts:
    print(f"[{alert.timestamp}] {alert.level}: {alert.message}")

Strategy Analysis

from hyperliquid_monitor_plus import StrategyAnalyzer

# Initialize analyzer with trade history
analyzer = StrategyAnalyzer(address="0x1234...")

# Analyze trading patterns
metrics = analyzer.analyze_trading_strategy(
    start_date=datetime.now() - timedelta(days=30),
    end_date=datetime.now()
)

print("📊 Strategy Metrics:")
print(f"  Total Trades: {metrics.total_trades}")
print(f"  Win Rate: {metrics.win_rate:.1f}%")
print(f"  Profit Factor: {metrics.profit_factor:.2f}")
print(f"  Sharpe Ratio: {metrics.sharpe_ratio:.2f}")
print(f"  Max Drawdown: {metrics.max_drawdown:.1f}%")
print(f"  Average Trade Duration: {metrics.avg_trade_duration}")

# Identify trade patterns
patterns = analyzer.identify_patterns()
for pattern in patterns:
    print(f"Pattern: {pattern.type}")
    print(f"  Frequency: {pattern.frequency}")
    print(f"  Success Rate: {pattern.success_rate:.1f}%")
    print(f"  Avg PnL: ${pattern.avg_pnl:,.2f}")

# Time-based analysis
time_analysis = analyzer.analyze_by_time_of_day()
print("\n⏰ Trading Activity by Hour:")
for hour, stats in time_analysis.items():
    print(f"  {hour}:00 - Trades: {stats['count']}, Win Rate: {stats['win_rate']:.1f}%")

# Coin performance comparison
coin_comparison = analyzer.compare_coin_performance()
print("\n💰 Best Performing Coins:")
for coin, metrics in coin_comparison[:5]:
    print(f"  {coin}: ${metrics.total_pnl:,.2f} ({metrics.win_rate:.1f}% win rate)")

Whale Bot Intelligence System

from hyperliquid_monitor_plus import (
    WhaleBotCore,
    WhaleBotConfig,
    EnhancedTrade,
    WhaleDetectionEvent
)

# Configure whale bot
config = WhaleBotConfig(
    min_whale_threshold=100_000,  # $100K minimum
    mega_whale_threshold=1_000_000,  # $1M for mega whale
    giant_whale_threshold=5_000_000,  # $5M for giant whale
    max_response_time_ms=100,  # 100ms max processing time
    follow_ratio=0.1,  # Follow with 10% of whale size
    max_position_risk=0.05,  # Max 5% of portfolio per position
    enable_real_time_alerts=True,
    dashboard=False
)

# Create whale bot
whale_bot = WhaleBotCore(config)

# Add detection callback
def on_whale_detected(enhanced_trade: EnhancedTrade):
    print(f"🐋 {enhanced_trade.whale_tier.value} Detected!")
    print(f"   {enhanced_trade.coin}: {enhanced_trade.whale_direction}")
    print(f"   Size: ${enhanced_trade.size_usd:,.0f}")
    print(f"   Urgency: {enhanced_trade.urgency}")
    print(f"   Market Impact: {enhanced_trade.market_impact:.3f}%")
    print(f"   Slippage: {enhanced_trade.slippage:.3f}%")
    print(f"   Follow Opportunity: {enhanced_trade.follow_opportunity}")

whale_bot.add_detection_callback(on_whale_detected)

# Add follow recommendation callback
def on_follow_recommendation(recommendation):
    if recommendation.action == "FOLLOW":
        print(f"✅ FOLLOW RECOMMENDATION")
        print(f"   Confidence: {recommendation.confidence:.1%}")
        print(f"   Reasoning: {recommendation.reasoning}")
        print(f"   Position Size: {recommendation.position_size_ratio:.1%}")
        print(f"   Entry Delay: {recommendation.optimal_entry_delay}s")
        print(f"   Stop Loss: {recommendation.stop_loss_ratio:.1%}")
        print(f"   Take Profit Levels: {recommendation.take_profit_levels}")
    elif recommendation.action == "HEDGE":
        print(f"⚠️ HEDGE RECOMMENDED: {recommendation.reasoning}")
    else:
        print(f"🚫 SKIP: {recommendation.reasoning}")

whale_bot.add_follow_callback(on_follow_recommendation)

# Start whale monitoring
addresses = ["0xwhale1...", "0xwhale2..."]
whale_bot.start_monitoring(addresses, db_path="whale_intelligence.db")

# Get bot statistics
stats = whale_bot.get_bot_statistics()
print(f"Status: {stats['status']}")
print(f"Whales Detected: {stats['performance']['whales_detected']}")
print(f"Follow Recommendations: {stats['performance']['follow_recommendations']}")
print(f"Avg Processing Time: {stats['performance']['avg_processing_time_ms']:.1f}ms")

Report Generation

from hyperliquid_monitor_plus import (
    ReportGenerator,
    ReportConfig,
    ReportFormat,
    ReportType,
    ReportPeriod
)

# Configure report
report_config = ReportConfig(
    report_type=ReportType.PORTFOLIO,
    period=ReportPeriod.WEEKLY,
    format=ReportFormat.HTML,
    include_charts=True,
    include_trades_table=True,
    include_pnl_breakdown=True,
    output_path="reports/"
)

# Create report generator
generator = ReportGenerator(
    db_path="whale_trades.db",
    config=report_config
)

# Generate report
report = generator.generate_report(
    start_date=datetime.now() - timedelta(days=7),
    end_date=datetime.now()
)

print(f"Report generated: {report.file_path}")
print(f"Report size: {report.file_size_kb:.1f} KB")
print(f"Trades analyzed: {report.trades_count}")
print(f"Charts generated: {report.charts_count}")

# Generate multiple formats
for fmt in [ReportFormat.HTML, ReportFormat.PDF, ReportFormat.JSON]:
    report_config.format = fmt
    report = generator.generate_report()
    print(f"Generated {fmt.value} report: {report.file_path}")

Notification Integration

from hyperliquid_monitor_plus import (
    NotificationManager,
    TelegramConfig,
    DiscordConfig,
    NotificationPriority
)

# Setup Telegram
telegram_config = TelegramConfig(
    bot_token="YOUR_BOT_TOKEN",
    chat_id="YOUR_CHAT_ID",
    parse_mode="Markdown"
)

# Setup Discord
discord_config = DiscordConfig(
    webhook_url="YOUR_DISCORD_WEBHOOK_URL",
    username="Whale Bot",
    avatar_url="https://example.com/whale-icon.png"
)

# Create notification manager
notif_manager = NotificationManager()
notif_manager.add_telegram(telegram_config)
notif_manager.add_discord(discord_config)

# Send notifications
def on_large_trade(trade):
    message = f"""
🐋 **Large Whale Trade Detected**

**Coin:** {trade.coin}
**Side:** {trade.side}
**Size:** {trade.size:,.4f}
**Price:** ${trade.price:,.2f}
**Value:** ${trade.size * trade.price:,.0f}
**Leverage:** {trade.leverage}x
**Address:** `{trade.address[:10]}...`
    """
    
    # Send to both Telegram and Discord
    notif_manager.send(
        message=message,
        priority=NotificationPriority.HIGH,
        channels=["telegram", "discord"]
    )

# Use with monitor
monitor = HyperliquidMonitor(
    addresses=["0x1234..."],
    callback=on_large_trade
)

🎓 Advanced Features

Phase 3: ML & Advanced Analytics

from hyperliquid_monitor_plus import (
    WhaleBotCore,
    Phase3Config,
    get_phase3_config
)
import asyncio

# Configure Phase 3 features
phase3_config = get_phase3_config("advanced")
phase3_config.ml_model_enabled = True
phase3_config.cross_chain_enabled = True
phase3_config.dashboard_enabled = True
phase3_config.dashboard_port = 8080
phase3_config.portfolio_optimization_enabled = True

# Create whale bot with Phase 3 capabilities
whale_bot = WhaleBotCore(
    config=whale_bot_config,
    phase3_config=phase3_config
)

# Start advanced features
async def run_advanced_features():
    # Start ML models, cross-chain tracking, and dashboard
    await whale_bot.start_advanced_features()
    
    # Monitor whale activity
    whale_bot.start_monitoring(addresses, "advanced_whale_db.db")
    
    # Run ML prediction for a trade
    prediction = await whale_bot.run_ml_prediction(enhanced_trade)
    if prediction:
        print(f"ML Prediction: {prediction['behavior_score']:.2f}")
        print(f"Price Forecast: ${prediction['predicted_price']:.2f}")
    
    # Track cross-chain activity
    cross_chain_data = await whale_bot.track_cross_chain_activity(enhanced_trade)
    if cross_chain_data:
        print(f"Cross-chain activity detected: {cross_chain_data['chains']}")
    
    # Run portfolio optimization
    optimization = await whale_bot.optimize_portfolio()
    if optimization:
        print("Recommended portfolio adjustments:")
        for coin, recommendation in optimization['adjustments'].items():
            print(f"  {coin}: {recommendation['action']} {recommendation['size']}")
    
    # Get Phase 3 status
    status = await whale_bot.get_phase3_status()
    print(f"ML Models Active: {status['components']['ml_manager']['active_models']}")
    print(f"Cross-chain Whales Tracked: {status['components']['cross_chain_tracker']['whales_tracked']}")
    print(f"Dashboard Running: Port {status['components']['dashboard']['port']}")

# Run the async application
asyncio.run(run_advanced_features())

Cross-Chain Whale Tracking

from hyperliquid_monitor_plus import CrossChainAnalytics, CrossChainMonitor

# Initialize cross-chain analytics
cross_chain = CrossChainAnalytics(
    chains=["ethereum", "arbitrum", "optimism", "base"],
    whale_address="0x1234..."
)

# Track whale across chains
async def track_whale_movements():
    # Get whale activity summary
    summary = await cross_chain.get_whale_summary()
    print(f"Total Value Across Chains: ${summary['total_value_usd']:,.0f}")
    print(f"Active Chains: {summary['active_chains']}")
    
    # Check for coordinated movements
    movements = await cross_chain.detect_coordinated_movements()
    if movements:
        print("⚠️ Coordinated cross-chain activity detected!")
        for movement in movements:
            print(f"  Chain: {movement['chain']}")
            print(f"  Action: {movement['action']}")
            print(f"  Value: ${movement['value_usd']:,.0f}")
            print(f"  Timing: {movement['timing_correlation']:.1%} correlated")

asyncio.run(track_whale_movements())

Real-Time Dashboard

The library includes a beautiful real-time web dashboard for monitoring whale activity:

from hyperliquid_monitor_plus import RealTimeDashboard, AdvancedWhaleBot

# Create whale bot
whale_bot = AdvancedWhaleBot(config)

# Create dashboard
dashboard = RealTimeDashboard(
    whale_bot=whale_bot,
    port=8080,
    host="0.0.0.0"
)

# Start dashboard
async def run_dashboard():
    await dashboard.start_dashboard()
    print("Dashboard running at http://localhost:8080")
    
    # Keep running
    while True:
        await asyncio.sleep(1)

asyncio.run(run_dashboard())

Visit http://localhost:8080 to see:

Real-time whale trade feed
Interactive charts and graphs
Position tracking
PnL visualization
Alert notifications
Market impact analysis

🛠️ CLI Tools

Hyperliquid Monitor CLI

# Basic monitoring
hyperliquid-monitor --address 0x1234... --db whale_trades.db

# Multiple addresses
hyperliquid-monitor --addresses 0x1234... 0x5678... --db trades.db

# With alerts
hyperliquid-monitor --address 0x1234... --alert-discord --db trades.db

# Telegram alerts (requires TELEGRAM_BOT_TOKEN env var)
hyperliquid-monitor --address 0x1234... --alert-telegram

# Silent mode (only database storage)
hyperliquid-monitor --address 0x1234... --db trades.db --silent

# Verbose logging
hyperliquid-monitor --address 0x1234... --db trades.db --verbose

# Disable PnL tracking
hyperliquid-monitor --address 0x1234... --db trades.db --no-pnl

# Dry run (test configuration)
hyperliquid-monitor --address 0x1234... --dry-run

Whale Bot CLI

# Conservative mode (default)
hyperliquid-whale-bot --address 0x1234... --config config.yaml

# Aggressive mode
hyperliquid-whale-bot --addresses 0x1234... 0x5678... --aggressive-mode

# Demo mode (no real trading)
hyperliquid-whale-bot --address 0x1234... --demo

# Custom parameters
hyperliquid-whale-bot --address 0x1234... \
    --min-whale-size 500000 \
    --max-whales 10 \
    --log-level DEBUG

# Multiple addresses with aggressive strategy
hyperliquid-whale-bot --addresses 0x1234... 0x5678... 0x9abc... \
    --aggressive-mode \
    --min-whale-size 1000000

🛡️ Advanced Risk Management System

Comprehensive risk monitoring and management system for whale tracking.

Core Risk Classes

from hyperliquid_monitor_plus.risk import (
    AdvancedRiskManager,
    RiskMetrics,
    PositionRisk,
    MarketRisk,
    RiskAlert
)

Key Features

Real-time Risk Monitoring: Continuous assessment of portfolio and position risks
Position-specific Analysis: Individual position risk breakdown
Market Regime Detection: Automatic identification of market conditions
Correlation Risk Assessment: Cross-asset correlation analysis
Automated Risk Alerts: Configurable risk threshold alerts

Risk Management Example

# Initialize risk manager
risk_manager = AdvancedRiskManager(config)

# Monitor portfolio risk
risk_metrics = await risk_manager.assess_portfolio_risk(positions)
print(f"Portfolio Risk: {risk_metrics.portfolio_risk:.2%}")
print(f"Position Risk: {risk_metrics.position_risk:.2%}")
print(f"Correlation Risk: {risk_metrics.correlation_risk:.2%}")

# Analyze specific position
position_risk = await risk_manager.analyze_position_risk("BTC", position)
if position_risk.risk_level == "HIGH":
    print(f"⚠️ High risk position: {position_risk.symbol}")
    print(f"   Risk Score: {position_risk.total_risk:.2%}")
    print(f"   Var 95%: ${position_risk.var_95_usd:,.2f}")

# Check market conditions
market_risk = await risk_manager.assess_market_conditions()
print(f"Market Regime: {market_risk.market_regime}")
print(f"Volatility Level: {market_risk.volatility_level:.2%}")
print(f"Liquidity: {market_risk.liquidity_conditions}")

# Get risk alerts
alerts = await risk_manager.get_active_risk_alerts()
for alert in alerts:
    print(f"🚨 {alert.severity}: {alert.message}")
    print(f"   Recommended Action: {alert.recommended_action}")

💼 Portfolio Optimization System

AI-powered portfolio optimization with whale intelligence integration.

Core Optimization Classes

from hyperliquid_monitor_plus.optimization import (
    PortfolioOptimizer,
    RiskAnalyzer,
    WhaleOpportunityDetector,
    PortfolioMetrics,
    OptimizationConstraints
)

Key Features

AI-powered Portfolio Rebalancing: Intelligent allocation optimization
Whale Trading Opportunity Detection: Identify follow/hedge opportunities
Risk-adjusted Optimization: VaR and volatility constrained optimization
Correlation-aware Allocation: Multi-asset correlation consideration
Real-time Portfolio Monitoring: Live portfolio performance tracking

Portfolio Optimization Example

# Initialize portfolio optimizer
optimizer = PortfolioOptimizer(config)

# Optimize current portfolio
optimization_result = await optimizer.optimize_portfolio(positions)
print("📊 Portfolio Optimization Results:")
print(f"Expected Return: {optimization_result.expected_return:.2%}")
print(f"Portfolio Risk: {optimization_result.portfolio_risk:.2%}")
print(f"Sharpe Ratio: {optimization_result.sharpe_ratio:.2f}")

print("\n📈 Recommended Allocation:")
for asset, weight in optimization_result.recommended_weights.items():
    current_weight = positions.get(asset, {}).get('weight', 0)
    change = weight - current_weight
    print(f"  {asset}: {weight:.2%} (change: {change:+.2%})")

# Detect whale opportunities
opportunities = await optimizer.opportunity_detector.detect_follow_opportunities(whale_trades)
for opp in opportunities:
    print(f"\n🐋 Whale Opportunity Detected:")
    print(f"   Asset: {opp.asset}")
    print(f"   Type: {opp.opportunity_type}")
    print(f"   Expected Return: {opp.expected_return:.2%}")
    print(f"   Confidence: {opp.confidence:.1%}")
    print(f"   Suggested Allocation: {opp.suggested_allocation:.2%}")
    print(f"   Entry Timing: {opp.entry_timing}")

# Get portfolio metrics
metrics = optimizer.risk_analyzer.calculate_portfolio_risk(positions)
print(f"\n📊 Portfolio Metrics:")
print(f"   Total Value: ${metrics.total_value_usd:,.2f}")
print(f"   Daily Return: {metrics.daily_return:.2%}")
print(f"   Sharpe Ratio: {metrics.sharpe_ratio:.2f}")
print(f"   Max Drawdown: {metrics.max_drawdown:.2%}")
print(f"   VaR 95%: ${metrics.var_95:,.2f}")

⚙️ Advanced Configuration Management

Comprehensive configuration system for all library features.

Configuration Classes

from hyperliquid_monitor_plus.config import (
    Config,
    Phase3Config,
    WhaleBotConfig
)

Configuration Methods

Environment Variables

# Basic API Configuration
export HYPERLIQUID_API_URL="https://api.hyperliquid.xyz"
export HYPERLIQUID_WS_URL="wss://ws.hyperliquid.xyz"
export DATABASE_PATH="whale_trades.db"

# Risk Management Settings
export MAX_POSITION_SIZE=0.25
export MAX_PORTFOLIO_RISK=0.15
export RISK_WARNING_THRESHOLD=0.10
export CRITICAL_RISK_THRESHOLD=0.20

# Portfolio Optimization
export ENABLE_PORTFOLIO_OPTIMIZATION=true
export OPTIMIZATION_INTERVAL_HOURS=1
export MAX_WHALE_CORRELATION=0.7
export REBALANCE_THRESHOLD=0.05

# ML and Intelligence
export ML_MODEL_PATH="/models/"
export ENABLE_SENTIMENT_ANALYSIS=true
export CROSS_CHAIN_ENABLED=true
export SENTIMENT_UPDATE_INTERVAL=300

# Notifications
export DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/..."
export TELEGRAM_BOT_TOKEN="your_bot_token"
export TELEGRAM_CHAT_ID="your_chat_id"

Configuration Files (YAML)

# config.yaml - Complete Configuration

# Core Whale Bot Settings
whale_bot:
  min_whale_threshold: 100000      # $100K minimum
  mega_whale_threshold: 1000000    # $1M for mega whale
  giant_whale_threshold: 5000000   # $5M for giant whale
  max_response_time_ms: 100
  max_whales: 10
  follow_ratio: 0.1               # Follow with 10% of whale size
  max_position_risk: 0.05          # Max 5% risk per position
  enable_real_time_alerts: true
  alert_cooldown_seconds: 30

# Advanced Risk Management
risk_management:
  enabled: true
  max_position_size: 0.25          # 25% max per position
  max_portfolio_risk: 0.15         # 15% max portfolio risk
  high_risk_threshold: 0.10        # Warning at 10%
  critical_risk_threshold: 0.20    # Critical at 20%
  auto_position_management: true
  liquidation_buffer: 0.05         # 5% buffer from liquidation

# Portfolio Optimization
portfolio_optimization:
  enabled: true
  optimization_frequency: "hourly"  # hourly, daily, weekly
  risk_budget: 0.15                # Risk allocation
  correlation_limit: 0.7           # Max correlation between assets
  rebalance_threshold: 0.05        # 5% drift triggers rebalance
  min_trade_size_usd: 1000
  max_turnover: 0.20               # 20% max turnover

# Phase 3 Advanced Features
phase3:
  ml_model_enabled: true
  ml_model_config:
    model_path: "/models/whale_behavior_v3.pkl"
    confidence_threshold: 0.75
    auto_update: true
    update_frequency: "daily"
  
  cross_chain_enabled: true
  cross_chain_config:
    enabled_chains: ["ethereum", "arbitrum", "optimism", "base"]
    sync_frequency_seconds: 30
    enable_coordination_detection: true
  
  dashboard_enabled: true
  dashboard_config:
    port: 8080
    host: "0.0.0.0"
    enable_api: true
    enable_websockets: true
    auth_enabled: false
  
  portfolio_optimization_enabled: true
  optimization_config:
    risk_model: "historical"
    optimization_algorithm: "mean_variance"
    rebalance_frequency: "weekly"
  
  sentiment_analysis_enabled: true
  sentiment_config:
    data_sources: ["twitter", "reddit", "discord"]
    update_interval: 300           # 5 minutes
    sentiment_threshold: 0.1       # Alert threshold

# Notification Channels
notifications:
  discord:
    enabled: true
    webhook_url: "${DISCORD_WEBHOOK_URL}"
    username: "Whale Bot"
    avatar_url: "https://example.com/whale-icon.png"
    alert_levels: ["WARNING", "CRITICAL"]
  
  telegram:
    enabled: true
    bot_token: "${TELEGRAM_BOT_TOKEN}"
    chat_id: "${TELEGRAM_CHAT_ID}"
    parse_mode: "Markdown"
    alert_levels: ["INFO", "WARNING", "CRITICAL"]
  
  email:
    enabled: false
    smtp_server: "smtp.gmail.com"
    smtp_port: 587
    username: "your_email@gmail.com"
    password: "your_app_password"
    recipients: ["admin@yourcompany.com"]

# Database Configuration
database:
  path: "whale_trades.db"
  backup_enabled: true
  backup_interval_hours: 24
  retention_days: 365
  vacuum_interval_days: 7

# Logging Configuration
logging:
  level: "INFO"
  format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
  file_path: "logs/whale_monitor.log"
  max_file_size_mb: 100
  backup_count: 5
  enable_console: true

Configuration Loading Example

# Load configuration from multiple sources
config = Config()

# Load from environment variables
config.load_from_env()

# Load from YAML file
config.load_from_file("config.yaml")

# Load from JSON file
config.load_from_file("config.json")

# Create specific configurations
whale_config = WhaleBotConfig(
    min_whale_threshold=100_000,
    mega_whale_threshold=1_000_000,
    giant_whale_threshold=5_000_000,
    follow_ratio=0.1
)

phase3_config = Phase3Config(
    ml_model_enabled=True,
    cross_chain_enabled=True,
    dashboard_enabled=True,
    dashboard_port=8080
)

# Validate configuration
validation_result = config.validate()
if not validation_result.is_valid:
    print("Configuration errors:")
    for error in validation_result.errors:
        print(f"  - {error}")

📊 Advanced Type System Reference

Comprehensive type definitions for all library features.

Enhanced Trade Types

from hyperliquid_monitor_plus.core_types.types import (
    EnhancedTrade,
    WhaleTier,
    WhaleDetectionEvent,
    MarketImpactAnalysis,
    TradeUrgency
)

# Trade Urgency Levels
class TradeUrgency(str, Enum):
    LOW = "LOW"        # Normal trading activity
    MEDIUM = "MEDIUM"  # Elevated activity
    HIGH = "HIGH"      # Unusual activity
    CRITICAL = "CRITICAL"  # Emergency/liquidation

# Whale Tier Classification
whale_tier = EnhancedTrade(
    coin="BTC",
    size=100.5,
    price=45000,
    whale_tier=WhaleTier.MEGA_WHALE,
    urgency=TradeUrgency.HIGH,
    market_impact=0.0025,  # 0.25% price impact
    follow_opportunity=True
)

Strategy & Risk Types

from hyperliquid_monitor_plus.core_types.strategy_types import (
    StrategyMetrics,
    RiskAssessment,
    PositionRisk,
    MarketRisk,
    PatternType,
    RecommendationType
)

# Strategy Performance Metrics
metrics = StrategyMetrics(
    total_trades=150,
    win_rate=0.68,
    profit_factor=1.45,
    sharpe_ratio=1.23,
    max_drawdown=0.08,
    avg_trade_duration=timedelta(hours=4.5),
    best_trade_pnl=5000.0,
    worst_trade_pnl=-1200.0
)

# Risk Assessment Types
risk_assessment = RiskAssessment(
    overall_risk_score=0.65,      # 0-1 scale
    position_risk_score=0.45,
    correlation_risk_score=0.78,
    liquidity_risk_score=0.23,
    volatility_risk_score=0.56,
    recommended_actions=[
        "Reduce BTC exposure by 5%",
        "Increase stable coin allocation",
        "Set tighter stop losses"
    ]
)

Portfolio & Optimization Types

from hyperliquid_monitor_plus.optimization.portfolio_optimizer import (
    PortfolioMetrics,
    OptimizationConstraints,
    WhaleOpportunity,
    PortfolioPosition
)

# Portfolio Position
position = PortfolioPosition(
    asset="BTC",
    current_weight=0.25,
    target_weight=0.20,
    market_value_usd=25000,
    entry_price=44000,
    current_price=45000,
    unrealized_pnl=1000,
    whale_exposure=True,
    risk_contribution=0.15
)

# Whale Trading Opportunity
opportunity = WhaleOpportunity(
    opportunity_id="btc_follow_001",
    asset="BTC",
    opportunity_type="FOLLOW",
    expected_return=0.035,        # 3.5% expected return
    confidence=0.78,              # 78% confidence
    risk_level="MEDIUM",
    whale_address="0x1234...",
    suggested_allocation=0.05,    # 5% of portfolio
    entry_timing="immediate"      # immediate, 5min, 15min, 1hour
)

Alert & Notification Types

from hyperliquid_monitor_plus.risk.risk_manager import RiskAlert
from hyperliquid_monitor_plus.alerts.types import AlertType, AlertLevel

# Risk Alert
risk_alert = RiskAlert(
    alert_type="HIGH_RISK_POSITION",
    severity="WARNING",
    message="BTC position approaching liquidation threshold",
    recommended_action="Reduce position size or add margin",
    position_details={
        "symbol": "BTC",
        "size": 2.5,
        "leverage": 10,
        "distance_to_liquidation": 0.08  # 8% away
    }
)

# Alert Condition Types
class AlertType(str, Enum):
    LARGE_TRADE = "LARGE_TRADE"
    WHALE_ACTIVITY = "WHALE_ACTIVITY"
    VOLUME_SPIKE = "VOLUME_SPIKE"
    LIQUIDATION = "LIQUIDATION"
    RISK_ALERT = "RISK_ALERT"
    PORTFOLIO_ALERT = "PORTFOLIO_ALERT"

class AlertLevel(str, Enum):
    INFO = "INFO"
    WARNING = "WARNING"
    CRITICAL = "CRITICAL"
    EMERGENCY = "EMERGENCY"

Dashboard & Visualization Types

from hyperliquid_monitor_plus.visualization.dashboard_components import (
    TradingMetrics,
    AlertData,
    ChartConfig
)

# Real-time Trading Metrics
metrics = TradingMetrics(
    timestamp=datetime.now(),
    total_volume_24h=1_250_000_000,
    whale_volume_24h=250_000_000,
    active_whales=15,
    avg_trade_size=125_000,
    largest_trade_size=5_000_000,
    volume_change_24h=0.15,  # 15% increase
    whale_activity_score=0.78
)

# Chart Configuration
chart_config = ChartConfig(
    chart_type="line",
    timeframe="1h",
    indicators=["SMA", "RSI", "Volume"],
    colors=["#1f77b4", "#ff7f0e", "#2ca02c"],
    width=1200,
    height=600,
    show_grid=True,
    show_legend=True
)

🎨 Advanced Visualization System

Comprehensive visualization and dashboard system with real-time updates.

Chart Classes

from hyperliquid_monitor_plus.visualization import (
    WhaleVolumeChart,
    MarketImpactPlot,
    TradeDistributionChart,
    PortfolioPerformanceChart,
    SentimentAnalysisPlot,
    CorrelationHeatmap,
    RealTimeWhaleTracker,
    
    # Dashboard Components
    TradingMetricsWidget,
    AlertDistributionWidget,
    PerformanceDashboard,
    RealTimeChart,
    
    # Exporters
    ChartExporter,
    HTMLReportGenerator,
    PDFReportGenerator
)

Key Features

Interactive Charts: Plotly-based interactive visualizations
Real-time Updates: Live data streaming and chart updates
Multiple Export Formats: PNG, PDF, SVG, HTML export
Dashboard Components: Reusable dashboard widgets
Custom Styling: Configurable themes and styling

Visualization Examples

# Create interactive whale volume chart
chart = WhaleVolumeChart(figsize=(14, 10))
chart.plot_whale_volume_tracking(trade_data, time_range="7d")
chart.add_market_impact_overlay()
chart.set_title("Whale Activity Analysis - Last 7 Days")

# Market impact analysis
impact_plot = MarketImpactPlot(figsize=(16, 12))
impact_plot.plot_market_impact_analysis(whale_trades)
impact_plot.add_price_correlation_lines()
impact_plot.add_volatility_bands()

# Portfolio performance chart
portfolio_chart = PortfolioPerformanceChart(figsize=(14, 8))
portfolio_chart.plot_portfolio_performance(positions, period="1y")
portfolio_chart.add_benchmark_comparison("BTC")
portfolio_chart.add_drawdown_periods()

# Real-time whale tracker
tracker = RealTimeWhaleTracker(update_interval=5000)  # 5 seconds
tracker.start_real_time_tracking(whale_addresses)

# Dashboard widgets
metrics_widget = TradingMetricsWidget(update_interval=10000)
alert_widget = AlertDistributionWidget()
performance_dashboard = PerformanceDashboard()

# Export charts
exporter = ChartExporter()
exporter.export_chart(chart, "whale_analysis.png", format="png", dpi=300)
exporter.export_chart(impact_plot, "market_impact.pdf", format="pdf")

# Generate comprehensive HTML report
html_generator = HTMLReportGenerator()
report_path = html_generator.generate_comprehensive_report(
    trade_data=trade_data,
    whale_addresses=whale_addresses,
    period="30d",
    include_charts=True,
    include_metrics=True,
    output_path="reports/monthly_report.html"
)

print(f"Report generated: {report_path}")

Advanced Dashboard Integration

from hyperliquid_monitor_plus.visualization.dashboard_components import (
    RealTimeDashboard,
    DashboardIntegration
)

# Create comprehensive dashboard
dashboard = RealTimeDashboard(
    whale_bot=whale_bot,
    port=8080,
    host="0.0.0.0",
    enable_api=True,
    enable_websockets=True,
    theme="dark"
)

# Add custom widgets
dashboard.add_widget(TradingMetricsWidget(), position=(0, 0), size=(6, 4))
dashboard.add_widget(RealTimeChart(chart_type="whale_volume"), position=(6, 0), size=(6, 4))
dashboard.add_widget(AlertDistributionWidget(), position=(0, 4), size=(12, 4))
dashboard.add_widget(PerformanceDashboard(), position=(0, 8), size=(12, 4))

# Start dashboard
async def run_dashboard():
    await dashboard.start_dashboard()
    print("🌐 Dashboard running at http://localhost:8080")
    print("📊 Available endpoints:")
    print("   /metrics - Trading metrics API")
    print("   /trades - Real-time trade stream")
    print("   /alerts - Alert management")
    print("   /portfolio - Portfolio analytics")
    
    # Keep running
    while True:
        await asyncio.sleep(1)

# Access via web browser or API
dashboard_url = "http://localhost:8080"
api_endpoints = [
    f"{dashboard_url}/api/v1/metrics",
    f"{dashboard_url}/api/v1/trades",
    f"{dashboard_url}/api/v1/whales",
    f"{dashboard_url}/api/v1/alerts",
    f"{dashboard_url}/api/v1/portfolio"
]

🧠 ML Integration & Advanced Intelligence

Machine learning powered whale intelligence system with social sentiment analysis.

Intelligence Classes

from hyperliquid_monitor_plus.intelligence import (
    WhaleIntelligence,
    SocialSentimentAnalyzer,
    IntelligenceEnhancements,
    MLModelManager
)

Key Features

Social Sentiment Analysis: Real-time sentiment from social media
Pattern Recognition: ML-powered behavior pattern detection
Predictive Analytics: Whale behavior prediction models
Market Regime Detection: Automatic market condition classification
Cross-chain Intelligence: Multi-blockchain activity analysis

ML Intelligence Examples

# Initialize intelligence system
intelligence = WhaleIntelligence(config)

# Analyze trade with ML enhancement
enhanced_trade = await intelligence.analyze_trade_with_ml(trade)
print(f"🤖 ML Analysis Results:")
print(f"   Behavior Score: {enhanced_trade.ml_prediction.behavior_score:.2f}")
print(f"   Confidence: {enhanced_trade.ml_prediction.confidence:.1%}")
print(f"   Pattern Match: {enhanced_trade.ml_prediction.pattern_type}")
print(f"   Predicted Follow Success: {enhanced_trade.ml_prediction.follow_success_rate:.1%}")

# Social sentiment analysis
sentiment_analyzer = SocialSentimentAnalyzer()
sentiment_score = await sentiment_analyzer.analyze_sentiment(
    symbol="BTC",
    timeframe="1h",
    data_sources=["twitter", "reddit", "discord"]
)
print(f"📱 Social Sentiment Analysis:")
print(f"   Overall Score: {sentiment_score.overall_score:.2f}")
print(f"   Positive: {sentiment_score.positive:.1%}")
print(f"   Negative: {sentiment_score.negative:.1%}")
print(f"   Neutral: {sentiment_score.neutral:.1%}")
print(f"   Volume: {sentiment_score.volume_score:.2f}")
print(f"   Trend: {sentiment_score.trend}")

# Market regime detection
regime_analysis = await intelligence.detect_market_regime(
    price_data=recent_prices,
    volume_data=recent_volumes,
    whale_activity=whale_trades
)
print(f"📈 Market Regime Detection:")
print(f"   Current Regime: {regime_analysis.regime}")
print(f"   Confidence: {regime_analysis.confidence:.1%}")
print(f"   Volatility Level: {regime_analysis.volatility_level}")
print(f"   Liquidity Condition: {regime_analysis.liquidity_condition}")
print(f"   Recommended Strategy: {regime_analysis.recommended_strategy}")

# Cross-chain intelligence
cross_chain_data = await intelligence.analyze_cross_chain_activity(
    whale_address="0x1234...",
    time_window="24h"
)
if cross_chain_data:
    print(f"🔗 Cross-chain Analysis:")
    print(f"   Active Chains: {cross_chain_data.active_chains}")
    print(f"   Total Value: ${cross_chain_data.total_value_usd:,.2f}")
    print(f"   Coordination Score: {cross_chain_data.coordination_score:.2f}")
    print(f"   Suspicious Activity: {cross_chain_data.suspicious_patterns}")

Advanced ML Model Management

# ML Model Manager
ml_manager = MLModelManager(config)

# Load and manage models
models = await ml_manager.load_models([
    "whale_behavior_model_v3.pkl",
    "market_regime_classifier.pkl",
    "sentiment_analyzer.pkl"
])

# Update model with new data
await ml_manager.update_model(
    model_name="whale_behavior_model_v3",
    new_training_data=recent_whale_trades,
    validation_split=0.2
)

# Get model performance metrics
performance = await ml_manager.get_model_performance("whale_behavior_model_v3")
print(f"🎯 Model Performance:")
print(f"   Accuracy: {performance.accuracy:.2%}")
print(f"   Precision: {performance.precision:.2%}")
print(f"   Recall: {performance.recall:.2%}")
print(f"   F1-Score: {performance.f1_score:.2%}")
print(f"   Last Updated: {performance.last_updated}")

🔗 Integration & External Services

Seamless integration with external services and platforms.

Dashboard Integration

from hyperliquid_monitor_plus.integration import (
    RealTimeDashboard,
    DashboardIntegration,
    ExternalAPI
)

Integration Examples

# Create dashboard integration
integration = DashboardIntegration(
    whale_bot=whale_bot,
    port=8080,
    host="0.0.0.0",
    enable_api=True,
    enable_websockets=True,
    enable_auth=False
)

# Add webhook endpoints
integration.add_webhook_endpoint(
    path="/whale-alert",
    methods=["POST"],
    callback=external_alert_handler,
    auth_required=False
)

integration.add_webhook_endpoint(
    path="/portfolio-update",
    methods=["POST"],
    callback=portfolio_update_handler,
    auth_required=True,
    api_key="your_api_key"
)

# External API integration
external_api = ExternalAPI(
    base_url="https://api.yourplatform.com",
    api_key="your_api_key",
    timeout=30
)

# Subscribe to external data feeds
await integration.subscribe_to_price_feed(
    symbols=["BTC", "ETH", "SOL"],
    callback=on_price_update
)

await integration.subscribe_to_social_sentiment(
    platforms=["twitter", "reddit"],
    callback=on_sentiment_update
)

# Start integration service
async def run_integration():
    await integration.start_integration()
    print("🔗 Integration services running:")
    print("   WebSocket: ws://localhost:8080/ws")
    print("   REST API: http://localhost:8080/api/v1/")
    print("   Webhooks: http://localhost:8080/webhook/")
    
    # Monitor integration health
    while True:
        health = await integration.get_health_status()
        if not health.is_healthy:
            print(f"⚠️ Integration issue: {health.error}")
        await asyncio.sleep(60)

# External service callbacks
async def external_alert_handler(data):
    """Handle external webhook alerts"""
    alert_type = data.get('type')
    message = data.get('message')
    
    # Process external alert
    if alert_type == 'whale_detected':
        await process_external_whale_alert(message)
    elif alert_type == 'risk_alert':
        await process_external_risk_alert(message)

async def portfolio_update_handler(data):
    """Handle portfolio updates from external system"""
    positions = data.get('positions', [])
    await whale_bot.update_external_positions(positions)

Third-party Service Integration

# TradingView integration
from hyperliquid_monitor_plus.integration.tradingview import TradingViewConnector

tv_connector = TradingViewConnector(
    webhook_secret="your_webhook_secret",
    chart_template="whale_analysis"
)

await tv_connector.send_chart_update(
    symbol="BTCUSDT",
    timeframe="1h",
    chart_data=chart_data
)

# Trading platform integration
from hyperliquid_monitor_plus.integration.broker import BrokerConnector

broker_connector = BrokerConnector(
    broker_type="binance",
    api_key="your_api_key",
    secret_key="your_secret_key"
)

# Execute trades based on whale signals
async def execute_whale_follow_signal(signal):
    if signal.action == "FOLLOW":
        order = await broker_connector.create_order(
            symbol=signal.symbol,
            side="BUY",
            quantity=signal.quantity,
            order_type="MARKET"
        )
        print(f"✅ Follow order executed: {order.order_id}")

📁 Examples Directory & Usage Guide

Complete examples for all library features with detailed documentation.

Directory Structure

examples/
├── README.md                          # This guide
├── run_examples.py                    # Master script to run all examples
│
├── core/                              # Core whale bot examples
│   └── whale_bot_example.py          # Full whale bot implementation
│
├── monitoring/                        # Basic monitoring examples
│   └── basic_monitoring.py           # Simple monitoring setup
│
├── analysis/                          # Market analysis examples
│   └── market_analysis.py            # Market impact & correlation analysis
│
├── intelligence/                      # ML and AI examples
│   └── intelligence_demo.py          # Social sentiment & ML integration
│
├── tracking/                          # Advanced tracking examples
│   └── advanced_tracking.py          # Cross-chain & real-time tracking
│
├── configuration/                     # Configuration examples
│   └── advanced_config.py            # Complex configuration management
│
├── database/                          # Database examples
│   └── data_analysis.py              # Database queries & analytics
│
├── integration/                       # Integration examples
│   └── dashboard_integration.py      # Dashboard & API integration
│
├── notifications/                     # Alert examples
│   └── alert_system.py               # Multi-channel notification system
│
├── strategy/                          # Strategy analysis examples
│   └── strategy_analyzer.py          # Strategy performance analysis
│
└── visualization/                     # Chart and visualization examples
    ├── simple_demo.py                # Basic chart creation
    └── comprehensive_demo.py         # Advanced visualization suite

Running Examples

Run All Examples

# Run all examples in sequence
python examples/run_examples.py

# Run with specific configuration
python examples/run_examples.py --config advanced_config.yaml --output reports/

# Run only specific modules
python examples/run_examples.py --modules core,monitoring,analysis

Run Individual Examples

# Core whale bot
python examples/core/whale_bot_example.py \
    --addresses 0x1234... 0x5678... \
    --config config.yaml \
    --output whale_bot.log

# Basic monitoring
python examples/monitoring/basic_monitoring.py \
    --address 0x1234... \
    --db trades.db \
    --alert-discord

# Market analysis
python examples/analysis/market_analysis.py \
    --db trades.db \
    --period 30d \
    --charts \
    --output analysis_report.html

# Intelligence demo
python examples/intelligence/intelligence_demo.py \
    --ml-enabled \
    --sentiment-enabled \
    --cross-chain-enabled

# Advanced tracking
python examples/tracking/advanced_tracking.py \
    --addresses addr1 addr2 addr3 \
    --dashboard-enabled \
    --ml-predictions \
    --real-time

# Configuration examples
python examples/configuration/advanced_config.py \
    --generate-config \
    --validate-config \
    --export-examples

# Database analysis
python examples/database/data_analysis.py \
    --db trades.db \
    --export-csv \
    --generate-stats

# Dashboard integration
python examples/integration/dashboard_integration.py \
    --port 8080 \
    --enable-websockets \
    --api-key your_key

# Notification system
python examples/notifications/alert_system.py \
    --discord-webhook $DISCORD_WEBHOOK \
    --telegram-token $TELEGRAM_TOKEN \
    --test-alerts

# Strategy analyzer
python examples/strategy/strategy_analyzer.py \
    --address 0x1234... \
    --period 90d \
    --export-report

# Visualization demos
python examples/visualization/simple_demo.py
python examples/visualization/comprehensive_demo.py \
    --export-pdf \
    --export-html \
    --real-time

Example Customization

Create Custom Example

#!/usr/bin/env python3
"""
Custom Whale Monitoring Example
Demonstrates custom implementation using hyperliquid-monitor-plus
"""

import asyncio
import logging
from datetime import datetime
from typing import List

from hyperliquid_monitor_plus import (
    HyperliquidMonitor,
    AlertManager,
    PortfolioOptimizer,
    AdvancedRiskManager
)

# Configure logging
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
logger = logging.getLogger(__name__)

class CustomWhaleMonitor:
    """Custom whale monitoring implementation"""
    
    def __init__(self, config):
        self.config = config
        self.monitor = None
        self.alert_manager = AlertManager()
        self.risk_manager = AdvancedRiskManager(config)
        self.portfolio_optimizer = PortfolioOptimizer(config)
        
    async def setup_alerts(self):
        """Setup custom alert conditions"""
        # Add custom alert for large BTC trades
        await self.alert_manager.add_condition(
            AlertCondition(
                name="Major BTC Movement",
                alert_type=AlertType.LARGE_TRADE,
                level=AlertLevel.CRITICAL,
                min_volume_usd=2_000_000,
                coins=["BTC"],
                message_template="🚨 Major BTC movement: ${volume_usd:,.0f}"
            )
        )
        
    async def on_whale_detected(self, trade):
        """Custom whale detection handler"""
        logger.info(f"🐋 Whale detected: {trade.coin} {trade.side}")
        
        # Analyze with ML
        enhanced_trade = await self.enhance_trade_with_ml(trade)
        
        # Check risk
        risk_score = await self.risk_manager.assess_trade_risk(enhanced_trade)
        
        # Generate portfolio recommendation
        if enhanced_trade.follow_opportunity:
            recommendation = await self.portfolio_optimizer.analyze_opportunity(
                enhanced_trade
            )
            
            if recommendation.confidence > 0.8:
                logger.info(f"✅ High-confidence follow opportunity: {recommendation}")
                
    async def enhance_trade_with_ml(self, trade):
        """Enhance trade with ML analysis"""
        # Add ML predictions here
        # This is a simplified example
        enhanced_trade = trade.copy()
        enhanced_trade.ml_prediction = {
            'behavior_score': 0.85,
            'confidence': 0.78,
            'pattern_type': 'accumulation',
            'follow_success_rate': 0.72
        }
        return enhanced_trade
        
    async def start_monitoring(self, addresses: List[str]):
        """Start the custom monitoring system"""
        await self.setup_alerts()
        
        self.monitor = HyperliquidMonitor(
            addresses=addresses,
            db_path="custom_whale.db",
            callback=self.on_whale_detected,
            alert_callback=self.alert_manager.check_trade,
            track_pnl=True
        )
        
        logger.info("🚀 Starting custom whale monitor...")
        await self.monitor.start()

async def main():
    """Main execution function"""
    # Configuration
    addresses = [
        "0x1234567890123456789012345678901234567890",
        "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
    ]
    
    # Initialize and start monitor
    monitor = CustomWhaleMonitor(config)
    await monitor.start_monitoring(addresses)

if __name__ == "__main__":
    asyncio.run(main())

🚨 Advanced Alert & Notification System

Comprehensive alert and notification system with multiple channels and advanced filtering.

Alert Classes

from hyperliquid_monitor_plus.alerts import (
    AlertManager,
    AlertCondition,
    AlertLevel,
    AlertType,
    TradeFilter,
    AlertFilter
)

from hyperliquid_monitor_plus.notifications import (
    NotificationManager,
    TelegramConfig,
    DiscordConfig,
    NotificationPriority
)

Advanced Alert Features

Multi-level Alerting: INFO, WARNING, CRITICAL, EMERGENCY
Smart Filtering: Advanced trade and address filtering
Channel Management: Multiple notification channels
Alert History: Persistent alert tracking and analysis
Escalation Rules: Automatic alert escalation
Alert Correlation: Intelligent alert grouping

Advanced Alert Examples

# Setup comprehensive alert system
alert_manager = AlertManager()

# 1. Large Trade Alert with Geographic Filter
alert_manager.add_condition(
    AlertCondition(
        name="Major Altcoin Alert",
        alert_type=AlertType.LARGE_TRADE,
        level=AlertLevel.WARNING,
        min_volume_usd=500_000,
        coins=["SOL", "AVAX", "ARB", "OP", "MATIC"],
        exclude_addresses=["0xexcluded1...", "0xexcluded2..."],
        message_template="🔔 Large {side} on {coin}: {size} @ ${price} (${volume_usd:,.0f})",
        cooldown_seconds=300  # 5-minute cooldown
    )
)

# 2. Whale Activity Pattern Detection
alert_manager.add_condition(
    AlertCondition(
        name="Whale Pattern Detection",
        alert_type=AlertType.WHALE_ACTIVITY,
        level=AlertLevel.CRITICAL,
        addresses=["0xknownwhale1...", "0xknownwhale2..."],
        min_volume_usd=1_000_000,
        pattern_detection=True,
        correlation_threshold=0.8,
        message_template="🐋 Known whale {address} pattern detected: ${volume_usd:,.0f}"
    )
)

# 3. Liquidation Risk Alert
alert_manager.add_condition(
    AlertCondition(
        name="Liquidation Risk Monitor",
        alert_type=AlertType.LIQUIDATION,
        level=AlertLevel.EMERGENCY,
        min_volume_usd=2_000_000,
        sides=["SELL"],
        liquidation_probability_threshold=0.7,
        message_template="⚡ HIGH LIQUIDATION RISK: {coin} - ${volume_usd:,.0f}"
    )
)

# 4. Portfolio Risk Alert
alert_manager.add_condition(
    AlertCondition(
        name="Portfolio Risk Monitor",
        alert_type=AlertType.PORTFOLIO_ALERT,
        level=AlertLevel.CRITICAL,
        min_portfolio_risk=0.15,  # 15% portfolio risk
        risk_increase_threshold=0.05,  # 5% increase
        message_template="⚠️ Portfolio risk elevated: {risk_level:.1%}"
    )
)

# Advanced Trade Filtering
trade_filter = TradeFilter()
trade_filter.add_condition("min_volume_usd", 100_000)
trade_filter.add_condition("coins", ["BTC", "ETH"])
trade_filter.add_condition("exclude_addresses", ["0xspam1...", "0xspam2..."])
trade_filter.add_condition("time_range", {
    "start": datetime.now() - timedelta(hours=1),
    "end": datetime.now()
})

# Alert Correlation and Escalation
alert_correlation = {
    "time_window": 300,  # 5 minutes
    "similarity_threshold": 0.7,
    "escalation_rules": [
        {"condition": "3_alerts_in_5min", "action": "increase_level"},
        {"condition": "same_whale_multiple_trades", "action": "combine_alerts"}
    ]
}

# Get alert analytics
analytics = alert_manager.get_analytics(time_range="7d")
print(f"📊 Alert Analytics (7 days):")
print(f"   Total Alerts: {analytics.total_alerts}")
print(f"   Critical Alerts: {analytics.critical_count}")
print(f"   False Positives: {analytics.false_positive_rate:.1%}")
print(f"   Average Response Time: {analytics.avg_response_time:.1f}s")
print(f"   Most Active Coin: {analytics.most_active_coin}")

Multi-Channel Notification System

# Setup notification manager
notification_manager = NotificationManager()

# Discord Configuration
discord_config = DiscordConfig(
    webhook_url="https://discord.com/api/webhooks/...",
    username="🐋 Whale Monitor",
    avatar_url="https://example.com/whale-icon.png",
    embed_color=0x0099ff,
    mention_everyone=False
)

# Telegram Configuration
telegram_config = TelegramConfig(
    bot_token="your_bot_token",
    chat_id="your_chat_id",
    parse_mode="Markdown",
    disable_web_page_preview=True
)

# Email Configuration
email_config = EmailConfig(
    smtp_server="smtp.gmail.com",
    smtp_port=587,
    username="your_email@gmail.com",
    password="your_app_password",
    recipients=["admin@company.com", "trader@company.com"],
    use_tls=True
)

# Slack Configuration
slack_config = SlackConfig(
    webhook_url="https://hooks.slack.com/...",
    channel="#whale-alerts",
    username="Whale Bot",
    icon_emoji=":whale:"
)

# Add notification channels
notification_manager.add_discord(discord_config)
notification_manager.add_telegram(telegram_config)
notification_manager.add_email(email_config)
notification_manager.add_slack(slack_config)

# Create rich notification messages
async def create_rich_whale_alert(trade):
    """Create comprehensive whale alert"""
    alert_message = f"""
🐋 **WHALE ALERT DETECTED**

**Trade Details:**
• **Coin:** {trade.coin}
• **Side:** {trade.side}
• **Size:** {trade.size:,.4f}
• **Price:** ${trade.price:,.2f}
• **Value:** ${trade.size * trade.price:,.0f}
• **Address:** `{trade.address[:10]}...`

**Market Impact:**
• **Estimated Impact:** {trade.estimated_impact:.3f}%
• **Slippage:** {trade.estimated_slippage:.3f}%
• **Follow Opportunity:** {'✅ Yes' if trade.follow_opportunity else '❌ No'}

**Alert Level:** {get_alert_level(trade)}
**Timestamp:** {trade.timestamp.strftime('%Y-%m-%d %H:%M:%S UTC')}
    """
    
    return alert_message

# Send alerts with different priorities
async def send_whale_alert(trade):
    """Send comprehensive whale alert"""
    message = await create_rich_whale_alert(trade)
    
    # Send to all channels
    await notification_manager.send(
        message=message,
        priority=NotificationPriority.HIGH,
        channels=["discord", "telegram", "slack"],
        format_message=True
    )
    
    # Send urgent alerts via email
    if trade.size * trade.price > 5_000_000:  # $5M+ trades
        await notification_manager.send(
            message=message,
            priority=NotificationPriority.EMERGENCY,
            channels=["email"],
            format_message=True
        )

# Alert Management Dashboard
class AlertDashboard:
    """Real-time alert management dashboard"""
    
    def __init__(self, alert_manager, notification_manager):
        self.alert_manager = alert_manager
        self.notification_manager = notification_manager
        
    async def get_alert_dashboard(self):
        """Get real-time alert dashboard data"""
        dashboard_data = {
            "active_alerts": await self.alert_manager.get_active_alerts(),
            "recent_alerts": await self.alert_manager.get_recent_alerts(limit=10),
            "alert_statistics": await self.alert_manager.get_statistics(),
            "notification_status": await self.notification_manager.get_status(),
            "alert_rules": await self.alert_manager.list_conditions()
        }
        return dashboard_data
        
    async def enable_alert_rule(self, rule_name: str):
        """Enable specific alert rule"""
        return await self.alert_manager.enable_condition(rule_name)
        
    async def disable_alert_rule(self, rule_name: str):
        """Disable specific alert rule"""
        return await self.alert_manager.disable_condition(rule_name)
        
    async def test_alert_rule(self, rule_name: str):
        """Test alert rule with sample data"""
        test_trade = create_test_trade()
        result = await self.alert_manager.test_condition(rule_name, test_trade)
        return result

📈 Performance Monitoring & Optimization

Built-in performance monitoring and optimization tools for production environments.

Performance Classes

from hyperliquid_monitor_plus.monitoring import (
    PerformanceMonitor,
    ResourceMonitor,
    MetricsCollector,
    OptimizationEngine
)

Performance Features

Real-time Metrics: Latency, throughput, memory usage
Resource Monitoring: CPU, memory, network utilization
Database Optimization: Query performance and indexing
WebSocket Health: Connection monitoring and auto-reconnect
API Rate Limiting: Compliance and optimization

Performance Monitoring Examples

# Initialize performance monitoring
perf_monitor = PerformanceMonitor()
resource_monitor = ResourceMonitor()
metrics_collector = MetricsCollector()

# Start monitoring
perf_monitor.start_monitoring()
resource_monitor.start_monitoring()

# Get performance statistics
stats = perf_monitor.get_performance_stats()
print(f"⚡ Performance Statistics:")
print(f"   Average Latency: {stats.avg_latency_ms:.1f}ms")
print(f"   95th Percentile Latency: {stats.p95_latency_ms:.1f}ms")
print(f"   Throughput: {stats.trades_per_second:.1f} trades/sec")
print(f"   Error Rate: {stats.error_rate:.2%}")
print(f"   Uptime: {stats.uptime_hours:.1f} hours")

# Resource usage monitoring
resource_stats = resource_monitor.get_resource_stats()
print(f"💻 Resource Usage:")
print(f"   CPU Usage: {resource_stats.cpu_usage:.1f}%")
print(f"   Memory Usage: {resource_stats.memory_usage_mb:.1f} MB")
print(f"   Memory Peak: {resource_stats.memory_peak_mb:.1f} MB")
print(f"   Disk I/O: {resource_stats.disk_io_mb:.1f} MB/s")
print(f"   Network I/O: {resource_stats.network_io_mb:.1f} MB/s")

# Database performance
db_stats = perf_monitor.get_database_stats()
print(f"💾 Database Performance:")
print(f"   Query Response Time: {db_stats.avg_query_time_ms:.1f}ms")
print(f"   Connection Pool: {db_stats.active_connections}/{db_stats.max_connections}")
print(f"   Cache Hit Rate: {db_stats.cache_hit_rate:.1%}")
print(f"   Slow Queries: {db_stats.slow_query_count}")

# WebSocket connection health
ws_stats = perf_monitor.get_websocket_stats()
print(f"🔌 WebSocket Health:")
print(f"   Active Connections: {ws_stats.active_connections}")
print(f"   Reconnection Rate: {ws_stats.reconnection_rate:.2%}")
print(f"   Message Rate: {ws_stats.messages_per_second:.1f}/sec")
print(f"   Connection Quality: {ws_stats.connection_quality:.1%}")

# Performance optimization suggestions
optimization_engine = OptimizationEngine()
suggestions = optimization_engine.analyze_performance(stats)
print(f"🔧 Optimization Suggestions:")
for suggestion in suggestions:
    print(f"   • {suggestion.title}")
    print(f"     Impact: {suggestion.impact}")
    print(f"     Implementation: {suggestion.implementation}")

Performance Optimization Configuration

# Performance optimization settings
optimization_config = {
    "database": {
        "connection_pool_size": 20,
        "query_timeout_ms": 5000,
        "enable_wal_mode": True,
        "enable_cache": True,
        "cache_size_mb": 512
    },
    
    "websocket": {
        "max_reconnect_attempts": 5,
        "reconnect_delay_ms": 1000,
        "heartbeat_interval_ms": 30000,
        "message_buffer_size": 1000
    },
    
    "api": {
        "rate_limit_requests": 100,
        "rate_limit_window_ms": 60000,
        "timeout_ms": 10000,
        "retry_attempts": 3
    },
    
    "monitoring": {
        "metrics_collection_interval": 10000,  # 10 seconds
        "performance_logging": True,
        "alert_thresholds": {
            "latency_ms": 100,
            "error_rate": 0.01,
            "memory_usage_mb": 1024
        }
    }
}

# Apply optimizations
optimization_engine = OptimizationEngine(optimization_config)
await optimization_engine.apply_optimizations()

Performance Benchmarking

class PerformanceBenchmark:
    """Performance benchmarking suite"""
    
    def __init__(self, whale_bot):
        self.whale_bot = whale_bot
        
    async def run_comprehensive_benchmark(self):
        """Run full performance benchmark suite"""
        results = {}
        
        # Trade processing benchmark
        results["trade_processing"] = await self.benchmark_trade_processing()
        
        # Database operations benchmark
        results["database"] = await self.benchmark_database_operations()
        
        # WebSocket performance benchmark
        results["websocket"] = await self.benchmark_websocket_performance()
        
        # Memory usage benchmark
        results["memory"] = await self.benchmark_memory_usage()
        
        # Alert system benchmark
        results["alerts"] = await self.benchmark_alert_system()
        
        return results
        
    async def benchmark_trade_processing(self):
        """Benchmark trade processing performance"""
        # Generate test trades
        test_trades = self.generate_test_trades(count=1000)
        
        start_time = time.time()
        processed_count = 0
        
        for trade in test_trades:
            await self.whale_bot.process_trade(trade)
            processed_count += 1
            
        end_time = time.time()
        
        return {
            "total_trades": processed_count,
            "processing_time_seconds": end_time - start_time,
            "trades_per_second": processed_count / (end_time - start_time),
            "avg_latency_ms": ((end_time - start_time) / processed_count) * 1000
        }
        
    def generate_test_trades(self, count=100):
        """Generate test trade data"""
        import random
        
        test_trades = []
        for i in range(count):
            trade = {
                "coin": random.choice(["BTC", "ETH", "SOL"]),
                "side": random.choice(["BUY", "SELL"]),
                "size": random.uniform(0.1, 100),
                "price": random.uniform(20000, 50000),
                "address": f"0x{random.randint(1000000000000000000000000000000000000000, 9999999999999999999999999999999999999999):040x}",
                "timestamp": datetime.now()
            }
            test_trades.append(trade)
            
        return test_trades

# Run benchmarks
benchmark = PerformanceBenchmark(whale_bot)
results = await benchmark.run_comprehensive_benchmark()

print(f"🏁 Benchmark Results:")
for category, result in results.items():
    print(f"\n📊 {category.upper()}:")
    for metric, value in result.items():
        print(f"   {metric}: {value}")

📖 API Reference

Core Classes

`HyperliquidMonitor`

Main monitoring class for tracking whale trades.

Parameters:

addresses (List[str]): List of Ethereum addresses to monitor
db_path (Optional[str]): Path to SQLite database for storage
callback (Optional[TradeCallback]): Callback function for each trade
silent (bool): Suppress callback notifications
alert_callback (Optional[AlertCallback]): Callback for alerts
pnl_callback (Optional[PnLCallback]): Callback for PnL events
track_pnl (bool): Enable automatic PnL tracking

Methods:

start(): Start monitoring
stop(): Stop monitoring
cleanup(): Clean up resources

`Database` / `TradeDatabase`

SQLite database for persistent trade storage.

Methods:

store_fill(fill, address): Store a trade fill
get_recent_trades(limit): Get recent trades
get_trades_by_coin(coin, limit): Filter by coin
get_trades_by_address(address, limit): Filter by address
get_trades_by_date_range(start, end): Filter by date
get_trade_statistics(coin): Get statistics
get_unique_coins(): List all traded coins
get_unique_addresses(): List all monitored addresses
close(): Close database connection

`PnLManager`

Profit & Loss tracking and analysis.

Methods:

process_trade(trade): Process trade and update PnL
update_prices(prices): Update current prices
get_position(coin): Get position for coin
get_all_positions(): Get all positions
get_open_positions(): Get only open positions
get_coin_pnl(coin): Get PnL statistics for coin
get_portfolio_pnl(): Get overall portfolio PnL
get_statistics(): Get comprehensive statistics
get_summary_report(): Generate text report
reset(): Reset all tracking data

`PositionTracker`

Real-time position tracking from exchange.

Methods:

fetch_positions(): Fetch current positions
get_position(coin): Get specific position
get_all_positions(): Get all positions
get_open_positions(): Get open positions only
get_account_state(): Get account state
get_risky_positions(threshold): Get at-risk positions
get_statistics(): Get position statistics
get_summary_report(): Generate text report

`AlertManager`

Smart alert system with conditions.

Methods:

add_condition(condition): Add alert condition
remove_condition(name): Remove condition
update_condition(name, **kwargs): Update condition
enable_condition(name): Enable condition
disable_condition(name): Disable condition
get_condition(name): Get specific condition
list_conditions(): List all conditions
check_trade(trade): Check trade against conditions
get_history(limit): Get alert history
get_statistics(): Get alert statistics

`WhaleBotCore`

Advanced whale bot with intelligence.

Methods:

start_monitoring(addresses, db_path): Start monitoring
stop_monitoring(): Stop monitoring
add_detection_callback(callback): Add whale detection callback
add_follow_callback(callback): Add follow recommendation callback
get_bot_statistics(): Get comprehensive statistics
start_advanced_features(): Start Phase 3 features (async)
run_ml_prediction(trade): Run ML prediction (async)
track_cross_chain_activity(trade): Track cross-chain (async)
optimize_portfolio(): Run portfolio optimization (async)

Type Classes

`Trade`

Basic trade data structure.

Attributes:

timestamp: Trade timestamp
address: Wallet address
coin: Coin symbol
side: "BUY" or "SELL"
size: Trade size
price: Trade price
trade_type: "FILL"
tx_hash: Transaction hash
fee: Trade fee
closed_pnl: Closed PnL
leverage: Position leverage

`EnhancedTrade`

Extended trade with whale intelligence.

Additional Attributes:

whale_tier: WhaleTier enum (MINNOW to GIANT_WHALE)
urgency: Trade urgency level
size_usd: USD value
whale_direction: "LONG", "SHORT", or "UNKNOWN"
market_impact: Predicted price impact
slippage: Expected slippage
follow_opportunity: Follow recommendation

`Position`

Position tracking (PnL system).

Attributes:

coin: Coin symbol
side: "LONG", "SHORT", or "NEUTRAL"
size: Position size
avg_entry_price: Average entry price
realized_pnl: Realized profit/loss

`LivePosition`

Live position from exchange.

Attributes:

coin: Coin symbol
side: "LONG", "SHORT", or "NEUTRAL"
size: Position size
entry_price: Entry price
mark_price: Current mark price
liquidation_price: Liquidation price
unrealized_pnl: Unrealized PnL
margin_used: Margin used
leverage: Position leverage
pnl_percentage: PnL percentage
distance_to_liquidation: Distance to liquidation (%)

🔧 Configuration

Environment Variables

Create a .env file:

# Hyperliquid API (optional - uses mainnet by default)
HYPERLIQUID_USE_TESTNET=false

# Discord Notifications (optional)
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

# Telegram Notifications (optional)
TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_CHAT_ID=your_chat_id_here

# Database (optional)
DATABASE_PATH=whale_trades.db

# Whale Thresholds (optional)
MIN_WHALE_THRESHOLD=100000
MEGA_WHALE_THRESHOLD=1000000
GIANT_WHALE_THRESHOLD=5000000

# ML & Advanced Features (optional)
ENABLE_ML_MODELS=true
ENABLE_CROSS_CHAIN=true
ENABLE_DASHBOARD=true
DASHBOARD_PORT=8080

Configuration Files

Create config.yaml:

whale_bot:
  # Thresholds
  min_whale_threshold: 100000
  mega_whale_threshold: 1000000
  giant_whale_threshold: 5000000
  
  # Performance
  max_response_time_ms: 100
  max_whales: 10
  
  # Trading
  follow_ratio: 0.1
  max_position_risk: 0.05
  max_market_impact_threshold: 0.01
  max_slippage_threshold: 0.005
  
  # Alerts
  enable_real_time_alerts: true
  alert_cooldown_seconds: 30
  
  # Features
  dashboard: false
  track_pnl: true
  
phase3:
  ml_model_enabled: true
  cross_chain_enabled: true
  dashboard_enabled: true
  dashboard_port: 8080
  portfolio_optimization_enabled: true
  
notifications:
  discord:
    enabled: true
    webhook_url: ${DISCORD_WEBHOOK_URL}
  
  telegram:
    enabled: true
    bot_token: ${TELEGRAM_BOT_TOKEN}
    chat_id: ${TELEGRAM_CHAT_ID}

🧪 Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=hyperliquid_monitor_plus --cov-report=html

# Run specific test module
pytest tests/test_monitor.py

# Run with verbose output
pytest -v

# Run only fast tests (skip slow integration tests)
pytest -m "not slow"

📊 Examples

The library includes comprehensive examples in the examples/ directory:

Basic Examples

examples/monitoring/basic_monitoring.py - Basic whale monitoring
examples/database/data_analysis.py - Database queries and analysis
examples/notifications/alert_system.py - Alert configuration

Advanced Examples

examples/core/whale_bot_example.py - Full whale bot setup
examples/analysis/market_analysis.py - Market impact analysis
examples/tracking/advanced_tracking.py - Advanced position tracking
examples/strategy/strategy_analyzer.py - Strategy analysis
examples/intelligence/intelligence_demo.py - ML and intelligence
examples/integration/dashboard_integration.py - Dashboard setup
examples/configuration/advanced_config.py - Advanced configuration

Run any example:

python -m hyperliquid_monitor_plus.examples.monitoring.basic_monitoring
python -m hyperliquid_monitor_plus.examples.core.whale_bot_example

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

# Clone repository
git clone https://github.com/Pezhman5252/hyperliquid_monitor_plus.git
cd hyperliquid_monitor_plus

# Install with development dependencies
pip install -e .[dev]

# Run tests
pytest

# Format code
black hyperliquid_monitor_plus/

# Lint code
flake8 hyperliquid_monitor_plus/

# Type checking
mypy hyperliquid_monitor_plus/

Guidelines

Follow PEP 8 style guidelines
Add tests for new features
Update documentation
Ensure all tests pass
Use type hints

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built on top of the official Hyperliquid Python SDK
Inspired by the amazing Hyperliquid community
Special thanks to all contributors

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Email: Prtsianboy.1991g@gmail.com

💝 Support This Project's Future

❤️ Your Support Fuels Innovation

Building production-ready trading tools takes countless hours of development, testing, and optimization. This library has already saved traders thousands of hours of development time, but it needs your support to continue evolving.

🔗 Support the Developer:

0xB05675CE390c895133dE8Aa1A873484f1FA1Df2C

✨ What Your Support Enables:

🚀 New Features: Advanced ML models, cross-chain analytics
🔧 Reliability: Bug fixes, performance optimizations
📈 Scaling: Handle larger datasets and more complex strategies
🎯 Innovation: Cutting-edge whale tracking and market analysis
🛡️ Security: Regular security audits and updates
📚 Documentation: Better guides and learning resources

💡 How Your Support Helps:

Even $5-10 covers server costs for one month
$50 enables a week of full-time development
$100+ fuels major feature development

🌟 What You Get Back:

Priority Support - Issues resolved faster
Early Access - New features before public release
Direct Impact - Your suggestions shape future development
Community Recognition - As a project supporter

🎯 Why This Matters

This isn't just a library—it's a complete ecosystem for DeFi intelligence. Every donation directly translates into:

More robust algorithms
Better market insights
Enhanced user experience
New trading opportunities

💎 Your Contribution Matters - No amount is too small. Every crypto donation, big or small, helps push the boundaries of what's possible in DeFi analytics.

🤝 Join Our Mission: Help us build the most advanced whale tracking system in the crypto space. Together, we can make institutional-grade tools accessible to everyone.

🗺️ Roadmap

Completed ✅

Core monitoring system
Multi-address support
Database storage
PnL tracking
Position tracking
Alert system
Whale bot intelligence
ML predictions
Cross-chain tracking
Real-time dashboard
Portfolio optimization

Planned 🔜

Advanced charting and visualization
Automated trading execution
Risk management system
Backtesting framework
Mobile app integration
More ML models
Additional DEX support
Cloud deployment guides

⚡ Performance

Real-time Processing: < 100ms latency for trade detection
Concurrent Support: Thread-safe for multiple addresses
Database: Optimized SQLite with indexes
Memory Efficient: Circular buffers for history
Scalable: Handles 1000+ trades/minute

🔐 Security

No private keys stored or required
Read-only API access
Secure WebSocket connections
Safe database operations
Input validation and sanitization

📈 Version History

v3.0.0 (Latest)

Added Phase 3: ML & Advanced Features
Cross-chain whale tracking
Portfolio optimization
Real-time dashboard
Improved performance and stability

v2.0.0

Major refactoring for production
Added PnL tracking system
Position tracking from exchange
Strategy analyzer
Report generation
Notification integrations

v1.0.0

Initial release
Basic whale monitoring
Database storage
Alert system

Made with ❤️ by Pezhman Hajipour

Star ⭐ this repository if you find it helpful!

Project details

These details have not been verified by PyPI

Project links

Release history Release notifications | RSS feed

This version

4.0.0

Nov 25, 2025

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hyperliquid_monitor_plus-4.0.0.tar.gz (273.9 kB view details)

Uploaded Nov 25, 2025 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

hyperliquid_monitor_plus-4.0.0-py3-none-any.whl (308.2 kB view details)

Uploaded Nov 25, 2025 Python 3

File details

Details for the file hyperliquid_monitor_plus-4.0.0.tar.gz.

File metadata

Download URL: hyperliquid_monitor_plus-4.0.0.tar.gz
Upload date: Nov 25, 2025
Size: 273.9 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.11.2

File hashes

Hashes for hyperliquid_monitor_plus-4.0.0.tar.gz
Algorithm	Hash digest
SHA256	`ba9b00027abbda880179497cabaadf6847077fbe5685dac81df0e6107fd99337`
MD5	`6bbbb0698a5149f65e40efd2d60ecdc2`
BLAKE2b-256	`9c93c0f209d70f3ad4958a2b6bc600a5306039ef2190e2f659b0a740d3f8cab5`

See more details on using hashes here.

File details

Details for the file hyperliquid_monitor_plus-4.0.0-py3-none-any.whl.

File metadata

Download URL: hyperliquid_monitor_plus-4.0.0-py3-none-any.whl
Upload date: Nov 25, 2025
Size: 308.2 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.11.2

File hashes

Hashes for hyperliquid_monitor_plus-4.0.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`77a6ab7b5dcc2815b9f181c0affd82820d3b7e257b51ed5cfc4663a319f1fa61`
MD5	`2a8d400d92f62bf4cea7c0f3aa2bb766`
BLAKE2b-256	`7382f540115aad1063b7e5dc97d43bb7bd85faf424e56221187bf3c7fd0a03b0`

See more details on using hashes here.

hyperliquid-monitor-plus 4.0.0

Navigation

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Project description

Hyperliquid Monitor Plus

🚀 Key Features

Core Monitoring

Advanced Analytics & Intelligence

PnL & Position Management

Smart Alert System

ML & Advanced Features (Phase 3)

Notifications & Integrations

📦 Installation

Basic Installation

Installation with Optional Features

From Source

🎯 Quick Start

1. Basic Whale Monitoring

2. Monitor with Alert System

3. Advanced PnL Tracking

4. Live Position Tracking

📚 Comprehensive Usage Guide

Working with the Database

Advanced Alert Configuration

Strategy Analysis

Whale Bot Intelligence System

Report Generation

Notification Integration

🎓 Advanced Features

Phase 3: ML & Advanced Analytics

Cross-Chain Whale Tracking

Real-Time Dashboard

🛠️ CLI Tools

Hyperliquid Monitor CLI

Whale Bot CLI

🛡️ Advanced Risk Management System

Core Risk Classes

Key Features

Risk Management Example

💼 Portfolio Optimization System

Core Optimization Classes

Key Features

Portfolio Optimization Example

⚙️ Advanced Configuration Management

Configuration Classes

Configuration Methods

Environment Variables

Configuration Files (YAML)

Configuration Loading Example

📊 Advanced Type System Reference

Enhanced Trade Types

Strategy & Risk Types

Portfolio & Optimization Types

Alert & Notification Types

Dashboard & Visualization Types

🎨 Advanced Visualization System

Chart Classes

Key Features

Visualization Examples

Advanced Dashboard Integration

🧠 ML Integration & Advanced Intelligence

Intelligence Classes

Key Features

ML Intelligence Examples

Advanced ML Model Management

🔗 Integration & External Services

Dashboard Integration

Integration Examples

Third-party Service Integration

📁 Examples Directory & Usage Guide

Directory Structure

Running Examples

Run All Examples

Run Individual Examples

Example Customization

`HyperliquidMonitor`

`Database` / `TradeDatabase`

`PnLManager`

`PositionTracker`

`AlertManager`

`WhaleBotCore`

`Trade`

`EnhancedTrade`

`Position`

`LivePosition`