Crate hyperliquid_backtest

Hyperliquid Backtester

A comprehensive Rust library that integrates Hyperliquid trading data with the rs-backtester framework to enable sophisticated backtesting of trading strategies using real Hyperliquid market data, including perpetual futures mechanics and funding rate calculations.

Features

• 🚀 Async Data Fetching: Efficiently fetch historical OHLC data from Hyperliquid API
• 💰 Funding Rate Support: Complete funding rate data and perpetual futures mechanics
• 🔄 Seamless Integration: Drop-in replacement for rs-backtester with enhanced features
• 📊 Enhanced Reporting: Comprehensive metrics including funding PnL and arbitrage analysis
• ⚡ High Performance: Optimized for large datasets and complex multi-asset strategies
• 🛡️ Type Safety: Comprehensive error handling with detailed error messages
• 📈 Advanced Strategies: Built-in funding arbitrage and enhanced technical indicators

API Stability

This crate follows semantic versioning (SemVer):

• Major version (0.x.y → 1.0.0): Breaking API changes
• Minor version (0.1.x → 0.2.0): New features, backward compatible
• Patch version (0.1.0 → 0.1.1): Bug fixes, backward compatible

Current version: 0.1.0 (Pre-1.0 development phase)

Stability Guarantees

• Public API: All items in the prelude module are considered stable within minor versions
• Data Structures: HyperliquidData, HyperliquidBacktest, and HyperliquidCommission are stable
• Error Types: HyperliquidBacktestError variants may be added but not removed in minor versions
• Strategy Interface: HyperliquidStrategy trait is stable for implementors

Quick Start

Add this to your Cargo.toml:

[dependencies]
hyperliquid-backtester = "0.1"
tokio = { version = "1.0", features = ["full"] }

Basic Backtesting Example

use hyperliquid_backtest::prelude::*;
use chrono::{DateTime, FixedOffset, Utc};

#[tokio::main]
async fn main() -> Result<(), HyperliquidBacktestError> {
    // Define time range (last 30 days)
    let end_time = Utc::now().timestamp() as u64;
    let start_time = end_time - (30 * 24 * 60 * 60); // 30 days ago
     
    // Fetch historical data for BTC with 1-hour intervals
    let data = HyperliquidData::fetch("BTC", "1h", start_time, end_time).await?;
     
    // Create a simple moving average crossover strategy
    let strategy = enhanced_sma_cross(10, 20, Default::default())?;
     
    // Set up backtest with $10,000 initial capital
    let mut backtest = HyperliquidBacktest::new(
        data,
        strategy,
        10000.0,
        HyperliquidCommission::default(),
    )?;
     
    // Run backtest including funding calculations
    backtest.calculate_with_funding()?;
     
    // Generate comprehensive report
    let report = backtest.enhanced_report()?;
     
    println!("📊 Backtest Results:");
    println!("Total Return: {:.2}%", report.total_return * 100.0);
    println!("Trading PnL: ${:.2}", report.trading_pnl);
    println!("Funding PnL: ${:.2}", report.funding_pnl);
    println!("Sharpe Ratio: {:.3}", report.sharpe_ratio);
     
    Ok(())
}

Funding Arbitrage Strategy Example

use hyperliquid_backtest::prelude::*;

#[tokio::main]
async fn main() -> Result<(), HyperliquidBacktestError> {
    let data = HyperliquidData::fetch("ETH", "1h", start_time, end_time).await?;
     
    // Create funding arbitrage strategy with 0.01% threshold
    let strategy = funding_arbitrage_strategy(0.0001)?;
     
    let mut backtest = HyperliquidBacktest::new(
        data,
        strategy,
        50000.0, // Higher capital for arbitrage
        HyperliquidCommission::default(),
    )?;
     
    backtest.calculate_with_funding()?;
     
    // Get detailed funding analysis
    let funding_report = backtest.funding_report()?;
     
    println!("💰 Funding Arbitrage Results:");
    println!("Total Funding Received: ${:.2}", funding_report.total_funding_received);
    println!("Total Funding Paid: ${:.2}", funding_report.total_funding_paid);
    println!("Net Funding PnL: ${:.2}", funding_report.net_funding_pnl);
    println!("Average Funding Rate: {:.4}%", funding_report.avg_funding_rate * 100.0);
     
    Ok(())
}

Migration from rs-backtester

This library is designed as a drop-in enhancement to rs-backtester. See the migration guide for detailed instructions on upgrading existing rs-backtester code.

Error Handling

All fallible operations return Result<T, HyperliquidBacktestError>. The error type provides detailed context and suggestions for resolution:

use hyperliquid_backtest::prelude::*;

match HyperliquidData::fetch("INVALID", "1h", start, end).await {
    Ok(data) => println!("Success!"),
    Err(HyperliquidBacktestError::HyperliquidApi(msg)) => {
        eprintln!("API Error: {}", msg);
        // Handle API-specific errors
    },
    Err(HyperliquidBacktestError::UnsupportedInterval(interval)) => {
        eprintln!("Unsupported interval: {}", interval);
        eprintln!("Supported intervals: {:?}", HyperliquidDataFetcher::supported_intervals());
    },
    Err(e) => eprintln!("Other error: {}", e),
}

Re-exports

pub use data::HyperliquidData;

pub use data::HyperliquidDataFetcher;

pub use data::FundingStatistics;

pub use backtest::HyperliquidBacktest;

pub use backtest::HyperliquidCommission;

pub use backtest::OrderType;

pub use backtest::TradingScenario;

pub use backtest::CommissionTracker;

pub use backtest::CommissionStats;

pub use backtest::OrderTypeStrategy;

pub use strategies::HyperliquidStrategy;

pub use strategies::TradingSignal;

pub use strategies::SignalStrength;

pub use strategies::FundingAwareConfig;

pub use strategies::funding_arbitrage_strategy;

pub use strategies::enhanced_sma_cross;

pub use errors::HyperliquidBacktestError;

pub use errors::Result;

pub use indicators::FundingPredictionModel;

pub use indicators::FundingPredictionConfig;

pub use indicators::FundingPrediction;

pub use indicators::FundingDirection;

pub use indicators::FundingVolatility;

pub use indicators::FundingMomentum;

pub use indicators::FundingCycle;

pub use indicators::FundingAnomaly;

pub use indicators::FundingArbitrageOpportunity;

pub use indicators::FundingPriceCorrelation;

pub use indicators::OpenInterestData;

pub use indicators::OpenInterestChange;

pub use indicators::LiquidationData;

pub use indicators::LiquidationImpact;

pub use indicators::BasisIndicator;

pub use indicators::FundingRatePredictor;

pub use funding_report::FundingReport;

pub use funding_report::FundingDistribution;

pub use funding_report::FundingRatePoint;

pub use funding_report::FundingDirectionStats;

pub use funding_report::FundingMetricsByPeriod;

pub use funding_report::FundingPeriodMetric;

pub use backtest::FundingPayment;

pub use csv_export::EnhancedCsvExport;

pub use csv_export::EnhancedCsvExportExt;

pub use csv_export::StrategyComparisonData;

pub use trading_mode::TradingMode;

pub use trading_mode::TradingConfig;

pub use trading_mode::RiskConfig;

pub use trading_mode::SlippageConfig;

pub use trading_mode::ApiConfig;

pub use trading_mode::TradingModeError;

pub use trading_mode_impl::TradingModeManager;

pub use trading_mode_impl::TradingResult;

pub use unified_data::Position;

pub use unified_data::OrderRequest;

pub use unified_data::OrderResult;

pub use unified_data::MarketData;

pub use unified_data::Signal;

pub use unified_data::SignalDirection;

pub use unified_data::OrderSide;

pub use unified_data::OrderType as TradingOrderType;

pub use unified_data::TimeInForce;

pub use unified_data::OrderStatus;

pub use unified_data::TradingStrategy;

pub use unified_data::OrderBookLevel;

pub use unified_data::OrderBookSnapshot;

pub use unified_data::Trade;

pub use paper_trading::PaperTradingEngine;

pub use paper_trading::PaperTradingError;

pub use paper_trading::SimulatedOrder;

pub use paper_trading::PaperTradingMetrics;

pub use paper_trading::TradeLogEntry;

pub use paper_trading::PaperTradingReport;

pub use real_time_data_stream::RealTimeDataStream;

pub use real_time_data_stream::RealTimeDataError;

pub use real_time_data_stream::SubscriptionType;

pub use real_time_data_stream::DataSubscription;

pub use risk_manager::RiskManager;

pub use risk_manager::RiskError;

pub use risk_manager::RiskOrder;

pub use risk_manager::Result as RiskResult;

pub use live_trading::LiveTradingEngine;

pub use live_trading::LiveTradingError;

pub use live_trading::LiveOrder;

pub use mode_reporting::ModeReportingManager;

pub use mode_reporting::CommonPerformanceMetrics;

pub use mode_reporting::PaperTradingReport as ModeSpecificPaperTradingReport;

pub use mode_reporting::LiveTradingReport;

pub use mode_reporting::RealTimePnLReport;

pub use mode_reporting::MonitoringDashboardData;

pub use mode_reporting::FundingImpactAnalysis;

pub use mode_reporting::RiskMetrics;

pub use mode_reporting::ConnectionMetrics;

pub use mode_reporting::AlertEntry;

pub use mode_reporting::OrderSummary;

pub use real_time_monitoring::MonitoringServer;

pub use real_time_monitoring::MonitoringClient;

pub use real_time_monitoring::MonitoringManager;

pub use real_time_monitoring::MonitoringError;

pub use real_time_monitoring::MonitoringMessage;

pub use real_time_monitoring::TradeExecutionUpdate;

pub use real_time_monitoring::ConnectionStatusUpdate;

pub use real_time_monitoring::ConnectionStatus;

pub use real_time_monitoring::PerformanceMetricsUpdate;

Modules

api_docs

API Documentation and Stability Guarantees

backtest

Enhanced Backtesting Functionality with Hyperliquid-specific Features

csv_export

CSV export functionality for Hyperliquid backtesting

data

Data Structures and Utilities for Hyperliquid Market Data

errors

Error types for Hyperliquid backtesting operations

funding_report

Funding report and analysis tools

indicators

Indicators and analysis tools for funding rates and market data

live_trading

live_trading_safety

logging

Logging and debugging utilities Logging and debugging utilities for the hyperliquid-backtester crate.

migration

Migration Guide from rs-backtester

mode_reporting

Mode-specific reporting functionality for different trading modes

paper_trading

prelude

Prelude module for convenient imports

real_time_data_stream

real_time_monitoring

Real-time monitoring capabilities for trading systems

risk_manager

Risk Management System

strategies

Strategy Implementations for Hyperliquid Backtesting

trading_mode

Trading Mode Management

trading_mode_impl

unified_data

Unified Data Structures

unified_data_impl

Unified Data Structures Implementation

utils

Utility functions and helpers for Hyperliquid backtesting