Lighter DEX Market Maker

This project is a complete market making solution for the Lighter DEX, built in Python. It consists of four main components that work together to collect data, calculate optimal trading parameters, determine the market trend, and execute a market making strategy.

Works on PAXG now by default. Check CRYPTO_CONFIGURATION.md to see what parts to change to switch to another market. By default, it tries to use all the funds available in the account. It can use leverage (2 by default; for example, if your account has 100$, it will try to put leverage at 2 and open position of size 200$).

The four core components are:

1. Data Collector (gather_lighter_data.py): Connects to the Lighter DEX websocket to stream real-time order book and trade data, saving it to CSV files.
2. Parameter Calculator (calculate_avellaneda_parameters.py): Implements the Avellaneda-Stoikov model to calculate optimal bid/ask spreads and reservation prices based on the collected data.
3. Trend Finder (find_trend_lighter.py): Uses a Supertrend indicator to determine the current market trend (uptrend or downtrend).
4. Market Maker (market_maker.py): Executes the market making strategy by placing and managing orders on the Lighter exchange, using the parameters generated by the calculator and the trend determined by the trend finder.

The entire system is orchestrated using Docker Compose, making it easy to run and manage.

Important Tips:

• Use on a dedicated account or sub-account. The bot will try to use all the funds available, and do compound interests.
• You don't need to have the .env file to run the data collector service
• Run first the data collector service only for some time, by edtiting the docker-compose.yml (comment out the market maker service)
• To get your ACCOUNT_INDEX, you can go to
  https://mainnet.zklighter.elliot.ai/api/v1/accountsByL1Address?l1_address=0xcEd... where 0xcEd... is your L1 (EVM) wallet address (Metamask, Rabby, Ledger, ...)
• Freshly coded, probably some bugs, only run with small amount of funds

Quick Start

Prerequisites

• Python 3.10+
• Docker
• Docker Compose

Installation

Before running the bot, you need to install the required Python packages:

pip install -r requirements.txt

Configuration

1. Create .env file: Create a .env file in the root of the project. See .env.example for a template.

   # Lighter Exchange Credentials
   API_KEY_PRIVATE_KEY=<your_api_key_private_key>
   ACCOUNT_INDEX=<your_account_index>
   API_KEY_INDEX=<your_api_key_index>
   
   # Market Maker Behavior
   MARKET_SYMBOL=PAXG

2. Environment Variables:

   • API_KEY_PRIVATE_KEY, ACCOUNT_INDEX, API_KEY_INDEX: Your Lighter exchange credentials.
   • MARKET_SYMBOL: The market to trade on (e.g., PAXG, BTC, ETH). Defaults to PAXG.
   • CLOSE_LONG_ON_STARTUP: (true/false) If true, the bot will attempt to close any existing long position in the specified market on startup. Defaults to false.
   • REQUIRE_PARAMS: (true/false) If true, the market maker will not place any orders until valid Avellaneda parameters are calculated. If false, it will use a static fallback spread. Defaults to false.
   • RESTART_INTERVAL_MINUTES: The market maker service will automatically restart after this many minutes. This helps in reloading parameters and preventing potential memory leaks. Defaults to 5.
   • LEVERAGE: The amount of leverage to use (e.g., 1, 2, 5, 8). This value multiplies your available capital, allowing for larger position sizes. It can be configured in the docker-compose.yml file. Defaults to 2 (1 means no leverage).
   • MARGIN_MODE: The margin mode to use, either cross or isolated. This is also configured in docker-compose.yml. Defaults to cross.
   • FLIP: (true/false) If true, the bot will adopt a short-biased strategy, selling first and then buying back. If false, it will follow a long-biased strategy, buying first and then selling. Defaults to false.

You can obtain the API credentials from the Lighter exchange.

Running the Bot

Start all services using Docker Compose:

docker-compose build
docker-compose up -d

This will start the following services in the background:

• data-collector: Gathers real-time market data.
• avellaneda-calculator: Calculates optimal spreads and reservation prices.
• find-trend: Determines the market trend using the Supertrend indicator.
• market-maker: Executes the trading strategy.

Stopping the Bot

To stop all services, run:

docker-compose down

Example Output

Here is an example of the market maker logs in action:

Project Structure

.
├── docker-compose.yml
├── Dockerfile
├── gather_lighter_data.py
├── calculate_avellaneda_parameters.py
├── find_trend_lighter.py
├── market_maker.py
├── requirements.txt
├── .env.example
├── lighter_data/       # CSV output data from the collector
├── params/             # JSON output from the parameter calculator
└── logs/               # Log files for all services

How it Works

1. Data Collection

The gather_lighter_data.py script connects to the Lighter DEX websocket and subscribes to the order book and trade channels for the configured markets (e.g., 'ETH', 'BTC', 'PAXG', 'ASTER'). It saves this data to CSV files in the lighter_data directory.

2. Parameter Calculation

The calculate_avellaneda_parameters.py script is set to run every 2 hours by default (defined in docker-compose.yml). Each time it runs, it analyzes the last 4 hours of trade and order book data to calculate the parameters for the Avellaneda-Stoikov market making model.

A key input to this model is market volatility (sigma). The script now calculates this using the GARCH(1,1) model, which provides a more sophisticated and responsive measure of volatility. If the GARCH model fails to produce a value, or if there are fewer than 10 historical data periods available, the script automatically falls back to a rolling standard deviation of log returns to ensure robustness.

The calculated parameters, including the volatility and optimal spreads, are saved to a nicely formatted JSON file (e.g., avellaneda_parameters_PAXG.json) in the params directory. It needs at least 1-2 days of gathered data to work properly.

3. Trend Finding

The find_trend_lighter.py script runs periodically to determine the market trend. It uses a Supertrend indicator, a popular technical analysis tool that uses price volatility to determine the trend. The script calculates the Supertrend value based on historical price data and determines if the market is in an uptrend or a downtrend. The result is saved to a JSON file (e.g., supertrend_params_PAXG.json) in the params directory.

4. Market Making

The market_maker.py script is the core of the bot. It reads the parameters from the JSON files generated by the calculator and the trend finder. It then connects to the Lighter exchange and places buy and sell orders based on the calculated optimal spreads, reservation prices, and the current market trend. The bot will adjust its strategy based on the FLIP environment variable, allowing it to switch between long-biased and short-biased strategies. It continuously monitors the market and its own orders, adjusting them as needed to maximize profitability.