Market Lab

Market Lab is an interactive Python application for exploring Binance spot-candle data. It stores downloaded OHLCV data in SQLite, calculates technical indicators, marks events, plots series, and produces simple quantile-based statistics. It is intended for research and experimentation; it does not place orders or provide trading advice.

What it does

• Creates a SQLite database for a Binance USDT market and timeframe.
• Downloads historical candles from Binance's public REST API and updates an existing database.
• Calculates built-in or user-defined indicators and stores them as columns in candles.
• Calculates events and stores their status values as columns in status.
• Plots one or more series, with positive and negative event markers when selected.
• Produces one- and two-variable quantile statistics.

The built-in indicator catalogue includes moving averages, VWEMA, correlation, ATR, relative changes, returns, RSI, Bollinger bands, Savitzky-Golay filtering, and other formulas. The event catalogue includes crossings, extrema, over/under comparisons, and peak detection.

Requirements

• Python 3.11 or newer
• Internet access to Binance for downloads and updates
• A desktop environment capable of displaying Matplotlib windows

Runtime dependencies are declared in pyproject.toml: matplotlib, numpy, questionary, requests, rich, scipy, and websocket-client.

Install

From the repository root, either use uv:

uv sync

or create a virtual environment and install the dependencies with pip:

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
python -m pip install matplotlib numpy questionary requests rich scipy websocket-client

Run Market Lab

Start the interactive application from the repository root:

python desktop.py

The console entry point in the current package configuration is only a placeholder, so use python desktop.py for the full application.

At launch, choose Create a database or Open a database. When creating one, enter a base symbol such as BTC (Market Lab appends USDT) and choose a supported Binance timeframe. Then use the main menu:

1. Download Data — retrieve all available history or a selected date range.
2. Calculate Indicators — choose a formula, its input columns, arguments, and window.
3. Calculate Events — choose a rule and the columns it should inspect.
4. Plot or Calculate Statistics — explore saved data.
5. Update Data — download newer candles and attempt to extend saved calculations.

Download data before calculating an indicator or event. A window must contain no more candles than are available.

Data model

Each database has these main tables:

The downloaded candle fields are open_time, open, high, low, close, volume, close_time, quote_asset_vol, number_of_trades, taker_buy_base_asset_volume, and taker_buy_quote_asset_volume.

Indicator output begins at the final candle of its first window; earlier rows are left empty. Calculating a column with the same name can replace the existing column, so use clear, unique names when preserving experiments matters.

Custom indicators and events

Market Lab can import Python modules that define indicator_dict and/or event_dict. Custom Python is executed during import, so only load code you have reviewed and trust.

Use Settings → Manage Custom Indicators and Events → Create custom_indicators.py to generate a starter module, edit it, then use Register custom module to validate, register, and load it. The complete, code-aligned extension contract and working examples are in How to create your own indicators and events.

Project layout

Notes and limitations

• Market data comes from Binance's public API. Availability, symbols, and historical coverage are controlled by Binance.
• The application is interactive rather than a stable programmatic API.
• SQLite files and generated custom modules are created next to the project files. Back up databases before replacing columns or registering untrusted changes.
• This project is for analysis, not a recommendation to buy or sell any asset.

Verification

The repository includes a lightweight custom-module smoke test:

python test_smoke.py