Jesse

https://docs.jesse.trade/
Admin
Jesse is an advanced, self-hosted Python algorithmic trading framework designed for simplicity,...
Tokens:110,806
Snippets:1,266
Trust Score:7.2
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install Live Trading Plugin

Source: https://docs.jesse.trade/docs/livetrade

Command to automatically download and install the live trading plugin for native environment setups.

```sh
jesse install-live
```

--------------------------------

### Install Redis

Source: https://docs.jesse.trade/docs/getting-started/environment-setup

Installs the Redis server via apt-get.

```sh
sudo apt-get install redis-server
```

--------------------------------

### Install Dependencies

Source: https://docs.jesse.trade/docs/getting-started/environment-setup

Install Redis and PostgreSQL using Homebrew.

```sh
brew install redis postgresql@17
```

--------------------------------

### Install and Start Redis on WSL

Source: https://docs.jesse.trade/docs/getting-started/environment-setup

Commands to update packages, install the Redis server, and verify the installation within the Ubuntu WSL environment.

```sh
    sudo apt-get update
    sudo apt-get upgrade
    sudo apt-get install redis-server
    redis-cli -v
```

```sh
redis-server
```

--------------------------------

### Jesse Startup Terminal Output

Source: https://docs.jesse.trade/docs/mcp/setup

Example of the terminal output displayed when the Jesse MCP server starts successfully.

```text
     ██╗███████╗███████╗███████╗███████╗
     ██║██╔════╝██╔════╝██╔════╝██╔════╝
     ██║█████╗  ███████╗███████╗█████╗
██   ██║██╔══╝  ╚════██║╚════██║██╔══╝
╚█████╔╝███████╗███████║███████║███████╗
 ╚════╝ ╚══════╝╚══════╝╚══════╝╚══════╝


  Jesse v1.13.8  ·  Live Plugin v2.1.2

Checking for new database migrations...

Starting Python Language Server...
LSP WS started at ws://localhost:9002/lsp

┌───────────────────────────────────────────────────────┐
│  ⬡ Dashboard is available at http://localhost:9001  │
└───────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│  ✓ MCP Server is running at http://localhost:9002/mcp  │
└─────────────────────────────────────────────────────────┘

INFO:     Started server process [89370]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
```

--------------------------------

### Install Jesse via pip

Source: https://docs.jesse.trade/docs/getting-started

Install the Jesse framework in a native environment.

```bash
pip install jesse
```

--------------------------------

### Application startup output

Source: https://docs.jesse.trade/docs/getting-started

Example console output indicating the server is running.

```text
INFO:     Started server process [66103]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:9000 (Press CTRL+C to quit)
```

--------------------------------

### Start the Jesse application

Source: https://docs.jesse.trade/docs/getting-started

Launch the application from within the project directory.

```sh
jesse run
```

--------------------------------

### Example output (show_params=True)

Source: https://docs.jesse.trade/docs/research/optimize

Sample output showing the table format with raw parameter dictionaries.

```text
Completed 30 / 30 trials  |  Objective: sharpe

Rank  Trial     Fitness  Train Sharpe Ratio  Test Sharpe Ratio  Params
----  --------  -------  ------------------  -----------------  ------
#1    Trial 17  0.1966   0.7962              0.8909             {'entry_atr_multiplier': 0.92, 'stop_loss': 2.81, 'adx_threshold': 36}
#2    Trial 6   0.1765   0.8148              1.5286             {'entry_atr_multiplier': 0.59, 'stop_loss': 2.80, 'adx_threshold': 43}
...
```

--------------------------------

### Install PostgreSQL

Source: https://docs.jesse.trade/docs/getting-started/environment-setup

Installs PostgreSQL and its contribution modules via apt-get.

```sh
sudo apt-get install postgresql postgresql-contrib
```

--------------------------------

### Install Miniconda

Source: https://docs.jesse.trade/docs/getting-started/environment-setup

Runs the downloaded Miniconda installer script.

```sh
bash {name of the file you downloaded}
```

--------------------------------

### Install Docker on Ubuntu

Source: https://docs.jesse.trade/docs/getting-started/docker

Use the official script to install Docker and Docker Compose on Ubuntu systems.

```sh
# install docker and docker compose 
curl -fsSL https://get.docker.com -o get-docker.sh && sudo sh get-docker.sh
```

--------------------------------

### Update Live Trade Plugin via Native Setup

Source: https://docs.jesse.trade/docs/getting-started/update

Remove the existing plugin package before installing the latest version.

```bash
# delete the already installed version
pip uninstall jesse-live -y
# install the latest version
jesse install-live
```

--------------------------------

### Install Cython

Source: https://docs.jesse.trade/docs/getting-started/environment-setup

Install the Cython package using pip to enable Jesse functionality.

```bash
pip install cython
```

--------------------------------

### Start Jesse Containers

Source: https://docs.jesse.trade/docs/getting-started/docker

Navigate to the docker directory and launch services in detached mode.

```sh
# open the `docker` directory
cd docker
# run without the "-d" flag to see the output
docker compose up -d
```

--------------------------------

### Install Homebrew

Source: https://docs.jesse.trade/docs/getting-started/environment-setup

Run this command to install the Homebrew package manager if it is not already present on your system.

```sh
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
```

--------------------------------

### Install Jesse stack on Ubuntu 22.04

Source: https://docs.jesse.trade/docs/getting-started/environment-setup

Executes a bash script to install the required stack and pip packages on a fresh Ubuntu 22.04 LTS installation.

```sh
source <(curl -fsSL https://raw.githubusercontent.com/jesse-ai/stack-installer/master/ubuntu-22.04.sh)
```

--------------------------------

### Example strategy implementation

Source: https://docs.jesse.trade/docs/mcp/example-workflow

A sample strategy structure demonstrating signal calculation, entry logic, and position management using Jesse's strategy API.

```python
from jesse.strategies import Strategy
import jesse.indicators as ta
from jesse import utils


class DOGEUSDTSharpeHunter2026(Strategy):
    def _signals(self):
        fast = ta.ema(self.candles, period=21)
        slow = ta.ema(self.candles, period=55)
        adx = ta.adx(self.candles, period=14)
        rsi = ta.rsi(self.candles, period=14)
        atr = ta.atr(self.candles, period=14)
        return fast, slow, adx, rsi, atr

    def should_long(self) -> bool:
        if len(self.candles) < 60:
            return False
        fast, slow, adx, rsi, _ = self._signals()
        return fast > slow and adx > 20 and rsi > 52 and rsi < 72

    def should_short(self) -> bool:
        return False

    def go_long(self):
        _, _, _, _, atr = self._signals()
        qty = utils.size_to_qty(self.available_margin * 0.06, self.price, fee_rate=self.fee_rate)
        self.buy = qty, self.price
        self.stop_loss = qty, self.price - (1.3 * atr)
        self.take_profit = qty, self.price + (3.5 * atr)

    def go_short(self):
        pass

    def should_cancel_entry(self) -> bool:
        return False

    def update_position(self):
        fast, slow, _, _, _ = self._signals()
        if self.is_long and fast < slow:
            self.liquidate()
```

--------------------------------

### Install JupyterLab

Source: https://docs.jesse.trade/docs/research/jupyter

Command to install JupyterLab via pip.

```bash
pip install jupyterlab
```

--------------------------------

### Backtest Usage Example

Source: https://docs.jesse.trade/docs/research/backtest

A complete example demonstrating how to generate fake candles, define a strategy, prepare inputs, and execute a backtest.

```python
# imports
import jesse.helpers as jh
from jesse.strategies import Strategy
from jesse import utils
from jesse.research import backtest, candles_from_close_prices

# generate fake candles
prices01 = [10, 11, 12, 12, 11, 13, 14, 12, 11, 15]
fake_candles01 = candles_from_close_prices(prices01)

# strategy
class ResearchStrategy(Strategy):
    def should_long(self):
        return True

    def should_short(self):
        return False

    def should_cancel_entry(self):
        return True

    def go_long(self):
        entry_price = self.price
        qty = utils.size_to_qty(self.balance * 0.5, entry_price)
        self.buy = qty, entry_price

    def go_short(self):
        pass

# prepare inputs
exchange_name = 'Fake Exchange'
symbol = 'BTC-USDT'
timeframe = '4h'
config = {
    'starting_balance': 10_000,
    'fee': 0,
    'type': 'futures',
    'futures_leverage': 2,
    'futures_leverage_mode': 'cross',
    'exchange': exchange_name,
    'warm_up_candles': 0
}
routes = [
    {'exchange': exchange_name, 'strategy': ResearchStrategy, 'symbol': symbol, 'timeframe': timeframe}
]
data_routes = []
candles = {
    jh.key(exchange_name, symbol): {
        'exchange': exchange_name,
        'symbol': symbol,
        'candles': fake_candles01,
    },
}

# execute backtest
result = backtest(
    config,
    routes,
    data_routes,
    candles,
    generate_equity_curve=True,
    generate_logs=True,
)
# access the metrics dict:
result['metrics']
# access the equity curve list:
result['equity_curve']
# access the logs list:
result['logs']
```

--------------------------------

### Install Miniconda on Windows

Source: https://docs.jesse.trade/docs/getting-started/environment-setup

Downloads and installs Miniconda silently using PowerShell.

```sh
curl https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe -o .\miniconda.exe
start /wait "" .\miniconda.exe /S
del .\miniconda.exe
```

--------------------------------

### Watch List Implementation Example

Source: https://docs.jesse.trade/docs/strategies/api

Demonstrates how to implement the watch_list method to track indicator values and signals during live trading.

```python
@property
def short_ema(self):
    return ta.ema(self.candles, 50)

@property
def long_ema(self):
    return ta.ema(self.candles, 100)

def watch_list(self):
    return [
        ('Short EMA', self.short_ema),
        ('Long EMA', self.long_ema),
        ('Trend', 1 if self.short_ema > self.long_ema else -1),
    ]
```

--------------------------------

### Start Jupyter Notebook or Lab

Source: https://docs.jesse.trade/docs/research/jupyter

Commands to launch the Jupyter interface.

```bash
# to start Jupyter Notebook
jupyter notebook
# to start Jupyter Lab
jupyter-lab
```

--------------------------------

### Start to Finish Balance Display

Source: https://docs.jesse.trade/docs/backtest/results

Shows the starting and ending portfolio values for the backtest period.

```text
Start => Finish Balance: 10000 => 23049.95
```

--------------------------------

### Implement a working short position strategy

Source: https://docs.jesse.trade/docs/strategies/entering-and-exiting

Example of a functional go_short implementation using current price and price extremes.

```python
def go_short(self):
    qty = 1

    # opens position with a MARKET order
    self.sell = qty, self.price
    self.stop_loss = qty, self.high + 10
    self.take_profit = qty, self.low - 10
```

--------------------------------

### Install Miniconda

Source: https://docs.jesse.trade/docs/getting-started/environment-setup

Download and install Miniconda to manage isolated Python environments. Choose the version corresponding to your processor architecture.

```sh
mkdir -p ~/miniconda3
curl https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh -o ~/miniconda3/miniconda.sh
bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3
rm ~/miniconda3/miniconda.sh
```

```sh
mkdir -p ~/miniconda3
curl https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh -o ~/miniconda3/miniconda.sh
bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3
rm ~/miniconda3/miniconda.sh
```

--------------------------------

### Monte Carlo Analysis Output Example

Source: https://docs.jesse.trade/docs/research/monte_carlo

Example of the console output generated after running a Monte Carlo simulation for candles and trade-order shuffling.

```text
   Metric                | Original | Worst 5% | Median | Best 5%
   ----------------------+----------+----------+--------+--------
   Net Profit Percentage | 81.8%    | 19.0%    | 55.5%  | 101.7% 
   Max Drawdown (%)      | -10.4%   | -5.5%    | -3.0%  | -1.2%  
   Sharpe Ratio          | 3.28     | 2.64     | 4.49   | 6.46   
   Win Rate (%)          | 70.8%    | 98.2%    | 99.2%  | 100.0% 
   Total                 | 154.0    | 162.6    | 266.0  | 429.5  
   Annual Return         | 227.2%   | 41.3%    | 140.0% | 302.1% 
   Calmar Ratio          | 21.95    | 11.68    | 46.79  | 125.79 
   Expectancy Percentage | 0.5%     | 0.1%     | 0.2%   | 0.3%   

   📊 Interpretation:
   • This tests how your strategy performs across different market conditions under resampled candles
Number of Monte Carlo candles scenarios found: 39
Saved Monte Carlo candles chart to: /Users/salehmir/Codes/jesse/dev-jesse/bot/charts/monte_carlo_candles_chart_20250905_200323.png

🎯 Running Monte Carlo (trades)...
2025-09-05 20:03:24,433	INFO worker.py:1841 -- Started a local Ray instance.
Successfully started Monte Carlo simulation with 12 CPU cores
Monte Carlo Scenarios: 100%|█████████████████████████████████████████████████████████████| 40/40 [00:01<00:00, 24.13it/s]
Completed 40 Monte Carlo scenarios out of 40 requested

🔀 MONTE CARLO TRADES (trade-order shuffle test)
   Simulations: 40
   Metric           | Original | Worst 5% | Median | Best 5%
   -----------------+----------+----------+--------+--------
   Max Drawdown (%) | 10.35%   | 28.3%    | 16.0%  | 10.5%  
   Sharpe Ratio     | 3.28     | 2.74     | 3.08   | 3.44   
   Calmar Ratio     | 21.95    | 2.89     | 5.11   | 7.76
```

--------------------------------

### __init__()

Source: https://docs.jesse.trade/docs/strategies/entering-and-exiting

The constructor for the strategy class, executed once at the start of the strategy.

```APIDOC
## __init__()

### Description
Standard Python constructor for strategy initialization. Must call `super().__init__()` to function correctly.

### Example
```python
def __init__(self):
    super().__init__()
    print('initiated the strategy class')
```
```

--------------------------------

### Add custom project notes

Source: https://docs.jesse.trade/docs/mcp/mcp-rules

Example of how to include custom project-specific notes outside of the Jesse-managed markers.

```markdown
# My project notes
Always use BTC-USDT on Binance Spot for the first iteration.

<!-- JESSE-RULES-START v1.13.8 -->
...Jesse-managed rules go here, refreshed automatically...
<!-- JESSE-RULES-END -->

# Other agent reminders
Keep weekly reports under `notes/reviews/`.
```

--------------------------------

### Implementing Stop Loss and Take Profit

Source: https://docs.jesse.trade/docs/strategies/example-strategies

Examples for setting static ATR-based stops, trailing stops, and EMA-based exits.

```python
def go_long(self):  
    take_profit = self.price + self.atr * 3  
    stop = self.price - self.atr * 2  
    qty = 10
    self.buy = qty, self.price  
    self.stop_loss = qty, stop  
    self.take_profit = qty, take_profit  
  
  
@property  
def atr(self):  
    return ta.atr(self.candles, period=22)
```

```python
def update_position(self):  
    # update trailing_stop_loss only if in profit  
    if self.position.pnl > 0:  
        if self.is_long:  
            self.stop_loss = self.position.qty, self.price - self.atr * 2  
        else:  
            self.stop_loss = self.position.qty, self.price + self.atr * 2
```

```python
def update_position(self):  
    if self.is_long and self.price <= self.exit_ema:  
       self.liquidate()  
       
@property  
def exit_ema(self):  
    return ta.ema(self.candles)
```

--------------------------------

### Example output (default — DNA column)

Source: https://docs.jesse.trade/docs/research/optimize

Sample output showing the default table format with DNA strings.

```text
Completed 30 / 30 trials  |  Objective: sharpe

Rank  Trial     Fitness  Train Sharpe Ratio  Test Sharpe Ratio  DNA
----  --------  -------  ------------------  -----------------  ---
#1    Trial 17  0.1966   0.7962              0.8909             eyJlbnRyeV9hdHJfbXVsdGlwbGllciI6IDAuOTJ9
#2    Trial 6   0.1765   0.8148              1.5286             eyJlbnRyeV9hdHJfbXVsdGlwbGllciI6IDAuNTl9
...
```

--------------------------------

### Test Output Example

Source: https://docs.jesse.trade/docs/research/rule-significance-testing/usage

Example output showing the statistical significance results of the bootstrap test.

```text
============================================================
  Rule Significance Test — Bootstrap
============================================================
  Observations      : 3095 bars
  Simulations       : 1000
  Observed mean     : 0.00014333
  Annualised return : 3.6120 %
  p-value           : 0.0470   →  STATISTICALLY SIGNIFICANT (p ≤ 0.05) ★
============================================================
```

--------------------------------

### Telegram Bot Token Example

Source: https://docs.jesse.trade/docs/notifications

Example format of the access token generated by BotFather for the Telegram HTTP API.

```text
234325981:BBF5-H-FIdlfGVwXaSDfsAdy5A9_4uVsnH
```

--------------------------------

### Accessing Candle Data

Source: https://docs.jesse.trade/docs/research/candles

Example of printing a candle array and structuring candle data for backtesting.

```python
print(trading_candles[0])
# array([
#     1.56427200e+12, # timestamp
#     2.07300000e+02, # open
#     2.07750000e+02, # close
#     2.08230000e+02, # high
#     2.06170000e+02, # low
#     2.15143531e+04 # volume
# ])
```

```python
import jesse.helpers as jh

warmup_candles, trading_candles = get_candles(
    'Binance Spot', 'BTC-USDT', '4h', jh.date_to_timestamp('2020-01-25'), jh.date_to_timestamp('2020-03-25'),
    warmup_candles_num=210, caching=True, is_for_jesse=True
)

trading_candles = {
    jh.key('Binance Spot', 'BTC-USDT'): {
        'exchange': 'Binance Spot',
        'symbol': 'BTC-USDT',
        'candles': trading_candles,
    },
}
warmup_candles = {
    jh.key('Binance Spot', 'BTC-USDT'): {
        'exchange': 'Binance Spot',
        'symbol': 'BTC-USDT',
        'candles': warmup_candles,
    },
}

# Now we are ready to run backtests with these candles.
```

--------------------------------

### Implement a working long position strategy

Source: https://docs.jesse.trade/docs/strategies/entering-and-exiting

Example of a functional go_long implementation using current price, high, and low values.

```python
def go_long(self):
    qty = 1

    self.buy = qty, self.price
    self.stop_loss = qty, self.low - 10
    self.take_profit = qty, self.high + 10
```

--------------------------------

### Start Jupyter with Remote Access

Source: https://docs.jesse.trade/docs/research/jupyter

Command to launch Jupyter for remote or Docker-based access.

```bash
jupyter notebook --ip 0.0.0.0 --no-browser --allow-root
```

--------------------------------

### Install Matplotlib for Monte Carlo Plotting

Source: https://docs.jesse.trade/docs/research/monte_carlo

Required dependency for visualizing Monte Carlo scenario distributions or equity curves.

```bash
pip install matplotlib
```

--------------------------------

### Update Jesse via PIP

Source: https://docs.jesse.trade/docs/getting-started/update

Use this command for native installations. Verify the version after running to ensure the update was successful.

```bash
pip install -U jesse
```

--------------------------------

### Define entry logic for a long position

Source: https://docs.jesse.trade/docs/strategies/entering-and-exiting

Example of setting a stop order for entering a trade when the price continues an uptrend.

```python
def should_long(self):
    return True

def go_long(self):
    qty = 1
    entry = self.high + 2

    self.buy = qty, entry
```

--------------------------------

### Example terminal output for significance tests

Source: https://docs.jesse.trade/docs/rule-significance-testing/interpreting-results

Sample console output demonstrating the structure of significant and non-significant test results.

```text
============================================================
  Rule Significance Test — Bootstrap
============================================================
  Observations      : 2190 bars
  Simulations       : 1000
  Observed mean     : 0.00024041
  Annualised return : 6.0584 %
  p-value           : 0.0180   →  STATISTICALLY SIGNIFICANT (p ≤ 0.05)
============================================================
```

```text
============================================================
  Rule Significance Test — Bootstrap
============================================================
  Observations      : 2190 bars
  Simulations       : 1000
  Observed mean     : -0.00019395
  Annualised return : -4.8875 %
  p-value           : 0.7990   →  not significant (p > 0.10)
============================================================
```

--------------------------------

### Initialize a new Jesse project

Source: https://docs.jesse.trade/docs/getting-started

Clone the project template and prepare the environment configuration file.

```sh
# change the name "my-bot" to whatever you want
git clone https://github.com/jesse-ai/project-template my-bot
# enter the directory
cd my-bot
# create a .env file by copying it from the template
# edit this to match you enviroment
cp .env.example .env
```

--------------------------------

### Configure PostgreSQL database and user

Source: https://docs.jesse.trade/docs/getting-started/environment-setup

Creates the database, user, and grants necessary privileges for Jesse.

```sh
sudo -u postgres psql -c "CREATE DATABASE jesse_db;"
sudo -u postgres psql -c "CREATE USER jesse_user WITH PASSWORD 'password';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE jesse_db TO jesse_user;"
sudo -u postgres psql -c "ALTER DATABASE jesse_db OWNER TO jesse_user;"
```

--------------------------------

### Configure PostgreSQL

Source: https://docs.jesse.trade/docs/getting-started/environment-setup

Create the database, user, and set necessary privileges within the PostgreSQL CLI.

```sh
# open PostgreSQL CLI
psql postgres
# create database
CREATE DATABASE jesse_db;
# create new user
CREATE USER jesse_user WITH PASSWORD 'password';
# set privileges of the created user
GRANT ALL PRIVILEGES ON DATABASE jesse_db to jesse_user;
# set the owner of the database to the new user (required for PostgreSQL >= 15)
ALTER DATABASE jesse_db OWNER TO jesse_user;
# exit PostgreSQL CLI
\q
```

--------------------------------

### Initialize PostgreSQL Database

Source: https://docs.jesse.trade/docs/getting-started/environment-setup

Commands to create the database, user, and set appropriate permissions within the PostgreSQL CLI.

```bash
psql -U postgres
CREATE DATABASE jesse_db;
CREATE USER jesse_user WITH PASSWORD 'password';
GRANT ALL PRIVILEGES ON DATABASE jesse_db to jesse_user;
ALTER DATABASE jesse_db OWNER TO jesse_user;
\q
```

--------------------------------

### View project directory structure

Source: https://docs.jesse.trade/docs/getting-started

The standard file layout for a newly initialized Jesse project.

```sh
├── .env # file where you enter the dashboard password, database credentials, etc
├── docker # directory containing the required config files for docker
├── storage # directory containing logs, chart images, etc
└── strategies # directory containing your strategies
    ├── Strategy01
    │   └─ __init__.py
    └── Strategy02
        └─ __init__.py
```

--------------------------------

### Configure and Run Monte Carlo Simulations

Source: https://docs.jesse.trade/docs/research/monte_carlo

Sets up trading routes, data routes, and simulation parameters for Monte Carlo analysis. Requires importing specific pipeline classes and simulation functions from jesse.research.monte_carlo.

```python
from jesse.enums import exchanges
import os

import jesse.helpers as jh
from jesse.research import get_candles
from jesse.research.monte_carlo import (
    monte_carlo_candles, 
    monte_carlo_trades,
    print_monte_carlo_candles_summary, 
    plot_monte_carlo_candles_chart,
    print_monte_carlo_trades_summary, 
    plot_monte_carlo_trades_chart
)
from jesse.research.monte_carlo.candle_pipelines import GaussianNoiseCandlesPipeline, MovingBlockBootstrapCandlesPipeline

# =============================================================================
# CONFIGURATION - MODIFY ALL SETTINGS HERE
# =============================================================================

# Trading Routes Configuration
TRADING_ROUTES = [
    {"exchange": exchanges.BINANCE_PERPETUAL_FUTURES, "symbol": "BTC-USDT", "timeframe": "5m", "strategy": "MyAwesomeStrategy"},
]

# Data Routes Configuration 
DATA_ROUTES = [
    {"exchange": exchanges.BINANCE_PERPETUAL_FUTURES, "symbol": "BTC-USDT", "timeframe": "4h"},
]

# Simulation Configuration
SIMULATION_CONFIG = {
    "num_scenarios": 40,  # Back to normal
    "start_date": "2025-03-01", 
    "end_date": "2025-09-01",
    "progress_bar": True,
    "benchmark": True,
    "fast_mode": True,
}

# Strategy Configuration
STRATEGY_CONFIG = {
    "starting_balance": 10_000,
    "fee": 0.05 / 100,
    "type": "futures",
    "futures_leverage": 10,
    "futures_leverage_mode": "cross",
    "warm_up_candles": 210,
}
```

--------------------------------

### Stop Jesse Containers

Source: https://docs.jesse.trade/docs/getting-started/docker

Stop running containers that were started in detached mode.

```sh
docker compose stop
```

--------------------------------

### Prepare Candles for Simulations

Source: https://docs.jesse.trade/docs/research/monte_carlo

Fetches and organizes trading and warmup candles based on provided routes and configuration.

```python
def prepare_candles_for_simulations(routes: list, data_routes: list, start_date_str: str, finish_date_str: str, config: dict):
    all_routes = routes + data_routes
    trading_candles = {}
    warmup_candles = {}
    unique_symbol_exchanges = set()
    for route in all_routes:
        unique_symbol_exchanges.add((route["exchange"], route["symbol"], route["timeframe"]))
    for route_exchange, route_symbol, route_timeframe in unique_symbol_exchanges:
        _warmup_candles, _trading_candles = get_candles(
            route_exchange,
            route_symbol,
            route_timeframe,
            jh.date_to_timestamp(start_date_str),
            jh.date_to_timestamp(finish_date_str),
            config["warm_up_candles"],
            caching=True,
            is_for_jesse=True,
        )
        key = jh.key(route_exchange, route_symbol)
        if key not in trading_candles:
            trading_candles[key] = {
                "exchange": route_exchange,
                "symbol": route_symbol,
                "candles": _trading_candles,
                "timeframe": route_timeframe,
            }
            warmup_candles[key] = {
                "exchange": route_exchange,
                "symbol": route_symbol,
                "candles": _warmup_candles,
                "timeframe": route_timeframe,
            }
        else:
            if jh.timeframe_to_one_minutes(route_timeframe) > jh.timeframe_to_one_minutes(trading_candles[key]["timeframe"]):
                trading_candles[key] = {
                    "exchange": route_exchange,
                    "symbol": route_symbol,
                    "candles": _trading_candles,
                    "timeframe": route_timeframe,
                }
                warmup_candles[key] = {
                    "exchange": route_exchange,
                    "symbol": route_symbol,
                    "candles": _warmup_candles,
                    "timeframe": route_timeframe,
                }
    return trading_candles, warmup_candles
```

--------------------------------

### Initialize Conda

Source: https://docs.jesse.trade/docs/getting-started/environment-setup

Activate the conda environment and initialize it for your shell.

```sh
source ~/miniconda3/bin/activate
conda init --all
```

--------------------------------

### Running a complete optimization workflow

Source: https://docs.jesse.trade/docs/research/optimize

A full script to load training and testing data, execute the optimization process, and output performance summaries.

```python
import logging
import os

# suppress Ray startup noise
os.environ['RAY_DISABLE_IMPORT_WARNING'] = '1'
logging.getLogger('ray').setLevel(logging.ERROR)

from jesse.enums import exchanges
import jesse.helpers as jh
from jesse.research import get_candles, optimize, print_optimize_summary

# =============================================================================
# CONFIGURATION
# =============================================================================

EXCHANGE = exchanges.BINANCE_PERPETUAL_FUTURES
SYMBOL   = 'BTC-USDT'
TIMEFRAME = '4h'

TRAINING_START  = '2021-01-01'
TRAINING_FINISH = '2023-12-31'
TESTING_START   = '2024-01-01'
TESTING_FINISH  = '2024-12-31'

WARM_UP_CANDLES = 210

CONFIG = {
    'exchange': {
        'name': EXCHANGE,
        'balance': 10_000,
        'fee': 0.0007,
        'type': 'futures',
        'futures_leverage': 2,
        'futures_leverage_mode': 'cross',
    },
    'warm_up_candles': WARM_UP_CANDLES,
}

ROUTES = [
    # Replace 'MyStrategy' with your actual strategy class or string name
    {'symbol': SYMBOL, 'timeframe': TIMEFRAME, 'strategy': 'MyStrategy'},
]

DATA_ROUTES = []


# =============================================================================
# HELPER — load and wrap candles for one date range
# =============================================================================

def load_candles_for_period(start: str, finish: str) -> tuple:
    """Return (trading_candles_dict, warmup_candles_dict) for the given period."""
    warmup_arr, trading_arr = get_candles(
        EXCHANGE,
        SYMBOL,
        TIMEFRAME,
        jh.date_to_timestamp(start),
        jh.date_to_timestamp(finish),
        WARM_UP_CANDLES,
        caching=True,       # cache to disk — repeated runs skip the DB query
        is_for_jesse=True,  # required when passing arrays to optimize()
    )

    key = jh.key(EXCHANGE, SYMBOL)

    trading_candles = {
        key: {'exchange': EXCHANGE, 'symbol': SYMBOL, 'candles': trading_arr}
    }
    warmup_candles = {
        key: {'exchange': EXCHANGE, 'symbol': SYMBOL, 'candles': warmup_arr}
    }

    return trading_candles, warmup_candles


# =============================================================================
# MAIN
# =============================================================================

if __name__ == '__main__':
    print('📦 Loading candles...')
    training_candles, training_warmup = load_candles_for_period(TRAINING_START, TRAINING_FINISH)
    testing_candles,  testing_warmup  = load_candles_for_period(TESTING_START,  TESTING_FINISH)

    print(f'   Training : {TRAINING_START} → {TRAINING_FINISH}')
    print(f'   Testing  : {TESTING_START}  → {TESTING_FINISH}')
    print()

    print('🚀 Starting optimization...')
    result = optimize(
        config=CONFIG,
        routes=ROUTES,
        data_routes=DATA_ROUTES,
        training_candles=training_candles,
        training_warmup_candles=training_warmup,
        testing_candles=testing_candles,
        testing_warmup_candles=testing_warmup,
        optimal_total=200,
        fast_mode=True,
        objective_function='sharpe',   # 'sharpe' | 'calmar' | 'sortino' | 'omega'
        best_candidates_count=20,
        progress_bar=True,
    )

    # Pretty-print the ranked table
    print_optimize_summary(result)

    # Access the top result directly
    best = result['best_trials'][0]
    print('Best params:', best['params'])
    print('Training Sharpe:', best['training_metrics'].get('sharpe_ratio'))
    print('Testing  Sharpe:', best['testing_metrics'].get('sharpe_ratio'))
    print('DNA:', best['dna'])
```

--------------------------------

### Get anchor timeframe

Source: https://docs.jesse.trade/docs/utils

Retrieves the anchor timeframe for a given input, useful for multi-timeframe strategy development.

```python
anchor_timeframe(timeframe)
```

```python
bigger_timeframe = anchor_timeframe('1h') # prints '4h'
```

--------------------------------

### Configure Cursor project rules

Source: https://docs.jesse.trade/docs/mcp/mcp-rules

YAML front matter for a Cursor .mdc rule file to ensure Jesse MCP tools are applied automatically.

```mdc
---
description: Jesse MCP — use only MCP tools for Jesse strategy, backtests, candles, and config
alwaysApply: true
---
```

--------------------------------

### Using Built-in Indicators

Source: https://docs.jesse.trade/docs/indicators/custom-indicators

Import and utilize optimized technical indicators provided by the jesse.indicators module.

```python
from jesse.indicators import ema, sma, rsi

ema_value = ema(candles, period=14, sequential=True)
sma_value = sma(candles, period=20, sequential=True)
rsi_value = rsi(candles, period=14, sequential=True)
```

--------------------------------

### Execute Monte Carlo Simulation

Source: https://docs.jesse.trade/docs/research/monte_carlo

Initializes the environment, prepares candle data, and executes both candle and trade-based Monte Carlo simulations with summary and plotting functions.

```python
if __name__ == "__main__":
    import logging, os
    os.environ['RAY_DISABLE_IMPORT_WARNING'] = '1'
    logging.getLogger('ray').setLevel(logging.ERROR)
    print("🚀 Starting Jesse Monte Carlo (candles + trades) Analysis")
    print("=" * 50)
    routes, data_routes = get_configured_routes()
    config = STRATEGY_CONFIG.copy(); config["exchange"] = TRADING_ROUTES[0]["exchange"]
    start_date = SIMULATION_CONFIG["start_date"]; end_date = SIMULATION_CONFIG["end_date"]; num_scenarios = SIMULATION_CONFIG["num_scenarios"]
    print(f"📋 Configuration:")
    print(f"   Trading Routes:")
    for route in TRADING_ROUTES:
        print(f"     {route['symbol']}@{route['timeframe']} ({route['strategy']})")
    print(f"   Data Routes:")
    if DATA_ROUTES:
        for route in DATA_ROUTES:
            print(f"     {route['symbol']}@{route['timeframe']}")
    else:
        print(f"     None (modify DATA_ROUTES at top of file to add)")
    print(f"   Period: {start_date} to {end_date}")
    print(f"   Scenarios: {num_scenarios}")
    trading_candles, warmup_candles = prepare_candles_for_simulations(routes, data_routes, start_date, end_date, config)

    print(f"\n🎯 Running Monte Carlo (candles)...")
    mc_candles_results = monte_carlo_candles(
        config,
        routes,
        data_routes,
        progress_bar=SIMULATION_CONFIG["progress_bar"],
        candles=trading_candles,
        warmup_candles=warmup_candles,
        num_scenarios=num_scenarios,
        fast_mode=SIMULATION_CONFIG["fast_mode"],
        candles_pipeline_class=MONTE_CARLO_CANDLES_CONFIG["pipeline_class"],
        candles_pipeline_kwargs=MONTE_CARLO_CANDLES_CONFIG["pipeline_kwargs"],
    )
    print_monte_carlo_candles_summary(mc_candles_results)
    plot_monte_carlo_candles_chart(mc_candles_results)

    print(f"\n🎯 Running Monte Carlo (trades)...")
    monte_carlo_results = monte_carlo_trades(
        config,
        routes,
        data_routes,
        progress_bar=SIMULATION_CONFIG["progress_bar"],
        candles=trading_candles,
        warmup_candles=warmup_candles,
        num_scenarios=num_scenarios,
        benchmark=SIMULATION_CONFIG["benchmark"],
        fast_mode=SIMULATION_CONFIG["fast_mode"],
    )
    print_monte_carlo_trades_summary(monte_carlo_results)
    plot_monte_carlo_trades_chart(monte_carlo_results)
```

--------------------------------

### Get candles

Source: https://docs.jesse.trade/docs/research/candles

Retrieves candles from the database as a NumPy array. The is_for_jesse flag should be set to True when preparing data for backtesting.

```python
get_candles(exchange, symbol, timeframe, start_date_timestamp, finish_date_timestamp, warmup_candles_num=0, caching=False, is_for_jesse=False)
```

```python
warmup_candles, trading_candles = research.get_candles('Binance Spot', 'ETH-USDT', '4h', 1564272000000, 1569628800000)

print(warmup_candles)
```

--------------------------------

### @cached

Source: https://docs.jesse.trade/docs/strategies/api

A decorator used to cache the results of functions or properties to avoid redundant intensive calculations. The cache is automatically cleared at the start of each new candle.

```APIDOC
## @cached

### Description
Decorator to cache function or property results. Useful for indicator calculations to improve performance.

### Usage
Apply to properties or methods. When used with `@property`, it must be placed after the `@property` decorator.

### Example
```python
from jesse.strategies import Strategy, cached

@property
@cached
def donchian(self):
    return ta.donchian(self.candles)
```
```

--------------------------------

### Calculate Support and Resistance with breaks

Source: https://docs.jesse.trade/docs/indicators/reference

Calculates support and resistance levels and detects price breaks using candle data.

```python
support_resistance_with_breaks(candles: np.ndarray, left_bars: int = 15, right_bars: int = 15, vol_threshold: int = 20) -> SupportResistanceWithBreaks
```

--------------------------------

### Configure GaussianNoiseCandlesPipeline

Source: https://docs.jesse.trade/docs/research/monte_carlo

Initializes the pipeline with specific sigma values for OHLC price noise and a batch size for processing.

```python
from jesse.research.monte_carlo.candle_pipelines import GaussianNoiseCandlesPipeline

pipeline_kwargs = {
    "batch_size": 7 * 24 * 60,  # 1 week in minutes
    "close_mu": 0.0,           # Average for close price noise
    "close_sigma": 10.0,       # How much noise for close price (required)
    "high_mu": 0.0,            # Average for high price noise  
    "high_sigma": 5.0,         # How much noise for high price (required)
    "low_mu": 0.0,             # Average for low price noise
    "low_sigma": 5.0           # How much noise for low price (required)
}
```

--------------------------------

### Configure MovingBlockBootstrapCandlesPipeline

Source: https://docs.jesse.trade/docs/research/monte_carlo

Initializes the bootstrap pipeline using a specified batch size to control the resampling block length.

```python
from jesse.research.monte_carlo.candle_pipelines import MovingBlockBootstrapCandlesPipeline

pipeline_kwargs = {
    "batch_size": 7 * 24 * 60  # 1 week in minutes
}
```

--------------------------------

### Define short position entry syntax

Source: https://docs.jesse.trade/docs/strategies/entering-and-exiting

Basic structure for setting sell, stop-loss, and take-profit parameters within the go_short method.

```python
def go_short(self):
    self.sell = qty, entry_price
    self.stop_loss = qty, stop_loss_price
    self.take_profit = qty, take_profit_price
```

--------------------------------

### Create and activate Conda environment

Source: https://docs.jesse.trade/docs/getting-started/environment-setup

Creates a new Python 3.12 environment named jesse and activates it.

```sh
conda create --name jesse python=3.12
conda activate jesse
```

--------------------------------

### Test the connection in Codex

Source: https://docs.jesse.trade/docs/mcp/connect-codex

Use this prompt in Codex to verify that the Jesse MCP server is correctly registered and accessible.

```text
Use the Jesse MCP server and list the available tools.
```

--------------------------------

### Liquidate method usage

Source: https://docs.jesse.trade/docs/strategies/api

Demonstrates using the liquidate method within the update_position strategy hook.

```python
def update_position(self):
    if self.index == 10:
        self.liquidate()

def should_long(self):
    return self.index == 0

def go_long(self):
    self.buy = 1, self.price
```

--------------------------------

### Initialize strategy class

Source: https://docs.jesse.trade/docs/strategies/entering-and-exiting

Constructor for the strategy class; requires a super().__init__() call to function correctly.

```python
def __init__(self):
    super().__init__()

    print('initiated the strategy class')
```

--------------------------------

### Define multi-point entry positions

Source: https://docs.jesse.trade/docs/strategies/events

Configure multiple entry points for a single position using a list of tuples.

```python
def go_long(self):
    self.buy = [
        (1, 100), 
        (1, 90), 
    ]
```

--------------------------------

### Monitor other strategies for position opening

Source: https://docs.jesse.trade/docs/strategies/events

React to position opening events in a different strategy to trigger logic like liquidation.

```python
def on_route_open_position(self, strategy):
    # example usage: trading BTC-USDT in the current route 
    # strategy and wanting to close it as soon as a position 
    # is opened in the ETH-USDT route:
    if self.is_open and strategy.symbol == 'ETH-USDT':
        self.liquidate()
```

--------------------------------

### Configure Jesse MCP with local fallback

Source: https://docs.jesse.trade/docs/mcp/connect-zed

Use this configuration if the direct HTTP connection fails, requiring Node.js and npx to bridge the connection.

```json
{
  "context_servers": {
    "jesse": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:9002/mcp"],
      "env": {}
    }
  }
}
```

--------------------------------

### optimize(config, routes, data_routes, training_candles, training_warmup_candles, testing_candles, testing_warmup_candles, ...)

Source: https://docs.jesse.trade/docs/research/optimize

Runs a hyperparameter optimization process for a given strategy configuration and dataset.

```APIDOC
## optimize(config, routes, data_routes, training_candles, training_warmup_candles, testing_candles, testing_warmup_candles, ...)

### Description
Performs hyperparameter optimization on a trading strategy. It evaluates strategy performance across training and testing periods to find optimal parameters.

### Parameters
- **config** (dict) - Required - Strategy and exchange configuration.
- **routes** (list) - Required - Trading routes containing symbol, timeframe, and strategy.
- **data_routes** (list) - Required - Additional data routes for strategy reading.
- **training_candles** (dict) - Required - Candle data for the training period.
- **training_warmup_candles** (dict) - Required - Warmup candle data for the training period.
- **testing_candles** (dict) - Required - Candle data for the testing/validation period.
- **testing_warmup_candles** (dict) - Required - Warmup candle data for the testing period.
- **optimal_total** (int) - Optional - Target number of trades for fitness normalization (default: 200).
- **fast_mode** (bool) - Optional - Enables the fast backtest engine (default: True).
- **cpu_cores** (int) - Optional - Number of parallel Ray workers.
- **trials** (int) - Optional - Number of trials per hyperparameter (default: 200).
- **objective_function** (str) - Optional - Metric to maximize: 'sharpe', 'calmar', 'sortino', 'omega' (default: 'sharpe').
- **best_candidates_count** (int) - Optional - Number of top-scoring trials to return (default: 20).
- **progress_bar** (bool) - Optional - Show a progress bar in the terminal (default: True).

### Response
- **result** (dict) - A dictionary containing the optimization results, including the best trials.
```

--------------------------------

### Configure environment variables in .env

Source: https://docs.jesse.trade/docs/configuration

Define sensitive credentials and service connection details in the .env file. Restart the application after modifying these values.

```sh
PASSWORD=test
APP_PORT=9000
LSP_PORT=9001
MCP_PORT=9002
MCP_LOG_IN_TERMINAL=true

# If not using docker, you probably want to set this to "localhost"
POSTGRES_HOST=postgres
# POSTGRES_HOST=localhost
POSTGRES_NAME=jesse_db
POSTGRES_PORT=5432
POSTGRES_USERNAME=jesse_user
POSTGRES_PASSWORD=password

# If not using docker, you probably want to set this to "localhost"
# REDIS_HOST=localhost
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=

# Enter the API token which you created at https://jesse.trade/user/api-tokens:
LICENSE_API_TOKEN=
```

--------------------------------

### Importing Custom Indicators

Source: https://docs.jesse.trade/docs/indicators/custom-indicators

Registering the custom indicator in the __init__.py file of the custom_indicators directory.

```python
from .ewo import ewo
```

--------------------------------

### Enter a trade at multiple price points

Source: https://docs.jesse.trade/docs/strategies/entering-and-exiting

Use a list of tuples to scale into a position at different price levels.

```python
def go_long():
    qty = 1

    # open position at $120 and increase it at $140
    self.buy = [
        (qty/2, 120),
        (qty/2, 140)
    ]
    self.stop_loss = qty, 100
    self.take_profit = qty, 160
```
Tokens:
Raw