Jesse Crypto Trading Framework

The Jesse backtesting engine has undergone a performance overhaul, achieving up to a 2.88x overall speedup. The improvements are split between jesse-rust (core kernels) and jesse (Python call-sites).

Performance Gains:

• Fast Mode (fast_mode=True): Skips the simulator. Typically sees 2.1x–2.5x speedup. This is the default for Dashboard and MCP users.
• Step Mode (fast_mode=False): Full per-minute simulator. Typically sees 2.4x–4.5x speedup.

Correctness Guarantee: All optimizations are bit-identical to the baseline. Correctness is verified using:

• Fingerprint Gate: A trades_hash (sha256 over every closed trade's prices, quantity, fees, and timestamps) and key metrics must match the baseline exactly.
• Regression Tests: Real-strategy tests ensure that complex multi-timeframe systems produce identical results to the pre-optimization version.

Higher-timeframe candle arrays are not automatically provided. You must implement them using self.get_candles() as a @property. Jesse handles lookahead bias internally, so you do not need to manually shift higher-timeframe values.

@property
def candles_6h(self):
    return self.get_candles(self.exchange, self.symbol, '6h')

@property
def big_trend(self):
    # Using 1D candles to determine trend
    k, d = ta.srsi(self.get_candles(self.exchange, self.symbol, '1D'))
    return 1 if k > d else -1 if k < d else 0

To determine if a strategy is overfit, compare the original backtest metric against the distribution of candles MC scenarios. For higher-is-better metrics (e.g., sharpe_ratio, net_profit_percentage, win_rate, calmar_ratio), use this rule:

Note: worst_5 (the 5th-percentile) is used to assess the downside tail (e.g., "how bad does it get?") rather than overfitting.

When using indicators that support sequential mode, set sequential=True to receive a full series of values as a numpy array. This is useful for accessing historical values for trend analysis or debugging.

• sequential=True: Returns a numpy array of all indicator values.
• sequential=False (default): Typically returns only the current value.

# Returns a numpy array of all RSI values
rsi_series = ta.rsi(self.candles, period=14, sequential=True)

# Access current value
current_rsi = rsi_series[-1]

# Access previous values for trend analysis
prev_rsi = rsi_series[-2]

To use Jesse's genetic algorithm optimization, define a hyperparameters() method that returns a list of dictionaries. Each dictionary defines a parameter's name, type, range, and default value.

Supported Types:

• int
• float
• 'categorical' (requires options list)

Access these values during strategy execution via self.hp['parameter_name'].

def hyperparameters(self) -> list:
    return [
        {'name': 'sma_period', 'type': int, 'min': 10, 'max': 200, 'default': 50},
        {'name': 'stop_loss', 'type': float, 'min': 1, 'max': 5, 'step': 0.1, 'default': 2.5},
        {'name': 'trend_method', 'type': 'categorical', 'options': ['supertrend', 'ema'], 'default': 'supertrend'},
    ]

@property
def sma(self):
    # Accessing an optimized hyperparameter
    return ta.sma(self.candles, self.hp['sma_period'])

Trades MC shuffles the order of trades but does not change the trades themselves. Therefore:

• Invariant Metrics: total_return, win_rate, and other non-path-dependent metrics are noise in Trades MC. Do not report their percentiles or use them for overfit detection.
• Informative Metric: Only max_drawdown (and derived calmar_ratio) is meaningful. It answers: "How bad could the equity-curve drawdown have been if the wins and losses arrived in a different order?"

Reporting Rule: For Trades MC, report only max_drawdown percentiles (original, worst_5, median, best_5).

To prevent errors when calculating indicators (like RSI or Bollinger Bands), always verify that the available candle count meets the indicator's required period. Use max() to determine the minimum required candles if using multiple indicators.

# CORRECT
def should_long(self):
    required_candles = max(self.rsi_period, self.bb_period, self.slow_ma_period)
    if len(self.candles) < required_candles:
        return False
    return rsi < 30

In Jesse, you can coordinate logic across multiple routes (different symbols) within a single strategy run using self.shared_vars. This is a dictionary shared across every route in the run.

To implement a multi-route strategy (like Pairs Trading):

1. Leading Route: Perform calculations (e.g., cointegration, z-score) and write decisions into self.shared_vars.
2. Follower Routes: Read the keys set by the leading route in should_long, should_short, or update_position to mirror the actions.

Useful utility functions for multi-route math:

• utils.prices_to_returns(...)
• utils.z_score(...)
• utils.are_cointegrated(...)
• utils.calculate_alpha_beta(...) to determine margin weighting between legs.