prosperity4btx 3.0.0

Backtester for IMC Prosperity 4 algorithms (based on Jasper van Merle's Prosperity 3 Backtester)

IMC Prosperity 4 Backtester

This repository contains a backtester for IMC Prosperity 4 algorithms. The output it generates closely matches the format of the output generated by the official submission environment.

Tip: Want to visualize your backtest results? See the Visualizer section below!

Usage

Basic usage:

# Install the latest version of the backtester
$ pip install -U prosperity4btx

# Run the backtester on an algorithm using all data from round 0
$ prosperity4btx <path to algorithm file> 0

Run pip install -U prosperity4btx again when you want to update the backtester to the latest version. You must do this after every round's data becomes available for the backtester to work on new data.

Some more usage examples:

# Backtest on all days from round 1
$ prosperity4btx example/starter.py 1

# Backtest on round 1 day 0
$ prosperity4btx example/starter.py 1-0

# Backtest on round 1 day -1 and round 1 day 0
$ prosperity4btx example/starter.py 1--1 1-0

# Backtest on all days from rounds 1 and 2
$ prosperity4btx example/starter.py 1 2

# You get the idea

# Merge profit and loss across days
$ prosperity4btx example/starter.py 1 --merge-pnl

# Write algorithm output to custom file
$ prosperity4btx example/starter.py 1 --out example.log

# Skip saving the output log to a file
$ prosperity4btx example/starter.py 1 --no-out

# Backtest on custom data
# Requires the value passed to `--data` to be a path to a directory that is similar in structure to https://github.com/Xeeshan85/imc-prosperity-4-backtester/tree/main/prosperity4bt/resources
$ prosperity4btx example/starter.py 1 --data prosperity4bt/resources

# Print trader's output to stdout while running
# This may be helpful when debugging a broken trader
$ prosperity4btx example/starter.py 1 --print

# Automatically open results in the interactive visualizer when done
$ prosperity4btx example/starter.py 1 --vis

# Combine multiple options
$ prosperity4btx example/starter.py 1 2 --merge-pnl --vis --out results.log

Order Matching

Orders placed by Trader.run at a given timestamp are matched against the order depths and market trades of that timestamp's state. Order depths take priority, if an order can be filled completely using volume in the relevant order depth, market trades are not considered. If not, the backtester matches your order against the timestamp's market trades. In this case the backtester assumes that for each trade, the buyer and the seller of the trade are willing to trade with you instead at the trade's price and volume. Market trades are matched at the price of your orders, e.g. if you place a sell order for €9 and there is a market trade for €10, the sell order is matched at €9 (even though there is a buyer willing to pay €10, this appears to be consistent with what the official Prosperity environment does).

Matching orders against market trades can be configured through the --match-trades option:

• --match-trades all (default): match market trades with prices equal to or worse than your quotes.
• --match-trades worse: match market trades with prices worse than your quotes, inspired by team Linear Utility's Prosperity 2 write-up.
• --match-trades none: do not match market trades against orders.

Limits are enforced before orders are matched to order depths. If for a product your position would exceed the limit, assuming all your orders would get filled, all your orders for that product get canceled.

Visualizer

This repo ships an enhanced local visualizer in the visualizer/ directory — a React/TypeScript app built on top of Highcharts and Mantine.

What the local visualizer adds

Per product, three charts are shown:

1. Candlestick / Price / Volume (simple market data) — mid price, bid/ask levels, and volume from the activity log.
2. Order Book + Algo Trades (algo trade data) — filled and unfilled buy/sell orders overlaid on price; requires the Logger boilerplate below.
3. Indicators: SMA / EMA / Z-score (computed from simple mid-price data) — configurable window period and indicator mode switcher.

Global charts and cards:

• Performance Metrics — Sharpe ratio, Sortino ratio, max drawdown (absolute and %), win rate, profit factor, avg/std return per timestep, peak/min P&L — all computed from the backtester's activity log P&L series.
• P&L chart — running profit/loss per product and total.
• Positions chart — position as % of limit over time (requires Logger).

---

Option A — PyPI package (no repo clone needed)

# 1. Install the backtester
pip install -U prosperity4btx

# 2. Run your backtest — saves to backtests/<timestamp>.log
prosperity4btx your_algo.py 0

# 3. Start the visualizer (one-time setup)
cd path/to/imc-prosperity-4-backtester/visualizer
npm install
npm run dev          # → http://localhost:5173

# 4. Open http://localhost:5173 and drag-and-drop the .log file

Note: --vis with the PyPI package tries these options in order:

1. Pre-built visualizer dist (if included in package)
2. GitHub Pages hosted visualizer
3. jmerle's upstream visualizer as fallback

To use the local dev server automatically with --vis, use Option B instead.

---

Option B — Repo clone (full --vis support)

# 1. Install uv (https://docs.astral.sh/uv/) then sync
git clone https://github.com/Xeeshan85/imc-prosperity-4-backtester.git
cd imc-prosperity-4-backtester
uv venv && source .venv/bin/activate
uv sync

# 2. Install and start the visualizer (one-time setup)
cd visualizer
npm install
npm run dev          # → http://localhost:5173
cd ..

# 3. Run your backtest — --vis tries the local dev server first
prosperity4btx your_algo.py 0 --vis

When --vis is used from the repo clone, the priority order is:

1. Local dev server at http://localhost:5173 (if npm run dev is running)
2. Pre-built visualizer/dist/index.html (if you ran npm run build)
3. GitHub Pages hosted visualizer
4. jmerle's upstream visualizer as final fallback

---

Logger boilerplate (required for order/position charts)

For the order book overlay and position charts to work, your algorithm must use the Logger class and call logger.flush() at the end of Trader.run(). See the upstream visualizer README for the full boilerplate.

Price, indicator, P&L, and metrics charts work without the Logger.

Build (static) / GitHub Pages

# Local build
cd visualizer
npm run build

Data Files

Data for the following rounds is included:

• Round 0: Tutorial round with prices and anonymized trades data on EMERALDS and TOMATOES. This is the introductory round to learn the basics of the algorithm.
• Round 1: Prices and trades data on INTARIAN_PEPPER_ROOT and ASH_COATED_OSMIUM products.
• Round 2: Prices and trades data on INTARIAN_PEPPER_ROOT and ASH_COATED_OSMIUM products.

Product Limits for Prosperity 4:

• EMERALDS: 80
• TOMATOES: 80
• INTARIAN_PEPPER_ROOT: 80
• ASH_COATED_OSMIUM: 80
• HYDROGEL_PACK: 200
• VELVETFRUIT_EXTRACT: 200
• VELVETFRUIT_EXTRACT_VOUCHER: 300

Conversions are not supported in this version.

Environment Variables

During backtests two environment variables are set for the trader to know the round and day it's being backtested on. The environment variable named PROSPERITY4BT_ROUND contains the round number and PROSPERITY4BT_DAY contains the day number. Note that these environment variables do not exist in the official submission environment, so make sure the code you submit doesn't require them to be defined.

Development

Follow these steps if you want to make changes to the backtester:

1. Install uv.
2. Clone (or fork and clone) this repository.
3. Open a terminal in your clone of the repository.
4. Create a venv with uv venv and activate it.
5. Run uv sync.
6. Any changes you make are now automatically taken into account the next time you run prosperity4btx inside the venv.

Acknowledgments

This backtester & Visualizer is a port of jmerle's Prosperity 3 backtester & jmerle/imc-prosperity-3-visualizer adapted for Prosperity 4. Special thanks to Jesper Merle for the original implementation.