English

简体中文

Codebase and Architecture Guide

This document serves as a guide for anyone new to the repository. The goal is to explain the project’s structure, the role of each component, and where to look when you want to add new features.

1. High-Level Overview

This project is a market-making bot for Polymarket. It periodically reads the order book, positions, and recent trades for target markets (YES/NO tokens). It then uses a short-term predictor to estimate a fair price, generates GTC + Post-only orders, and submits them via the Polymarket CLOB API.

Core Execution Path

graph TD
    A[main.py] --> B[BotConfig reads .env]
    B --> C[PolymarketAdapter connects]
    C --> D[MarketMaker.bootstrap initializes]
    D --> E[MarketMaker.tick loop]
    E --> F(AdvancedPredictor predicts)
    E --> G(QuoteEngine quotes)
    E --> H(OrderReconciler reconciles)
    E --> I(PolymarketAdapter trades)
    E --> J(DataRecorder records)

Startup Phase

flowchart TD
    A["Run Bot"] --> B["BotConfig: Read .env"]
    B --> C["config.validate: Validate key parameters"]
    C --> D["setup_logging: Configure logs"]
    D --> E["PolymarketAdapter: Initialize CLOB client"]
    E --> F["MarketMaker.run()"]

Strategy Flow per Tick

flowchart TD
    A["MarketMaker.tick()"] --> B["Fetch YES/NO order book"]
    B --> C["Calculate bid/ask/mid & imbalance"]
    C --> D["Read positions & global exposure"]
    D --> E["Read recent trades &trade_flow"]
    E --> F["AdvancedPredictor generates predicted_mid"]
    F --> G["Risk Checks (exposure, stop-loss, etc.)"]
    G --> H["QuoteEngine generates BUY/SELL limit prices"]
    H --> I["Create list of Target Orders"]
    I --> J["OrderReconciler compares with live open orders"]
    J --> K["Cancel stale orders"]
    K --> L["Place missing orders"]
    F --> M["DataRecorder writes data to CSV"]

2. Directory Overview

.
├── main.py                         # Main entry point
├── config.py                       # .env configuration loading & validation
├── market_maker.py                 # Core market-making strategy loop
├── polymarket_adapter.py           # Polymarket API adapter layer
├── quote_engine.py                 # Quoting engine
├── emergency_exit.py               # Emergency maker exit logic
├── order_reconciler.py             # GTC order reconciliation
├── predictors.py                   # Base predictor interface
├── advanced_predictors.py          # The enhanced predictor currently in use
├── data_recorder.py                # Records tick-by-tick data
├── docs/                           # Documentation website files
├── tests/                          # Unit tests
├── poly_data/                      # Legacy/auxiliary data and trading tools
└── poly_merger/                    # Node.js position merging utility

3. Core File Breakdown

main.py

The main entry point. It initializes the configuration, logging, API adapter, and the MarketMaker instance.

config.py

Loads variables from the .env file into a structured BotConfig object and validates them before the bot runs.

polymarket_adapter.py

A wrapper around the Polymarket SDK/API. All interactions with the exchange (placing orders, fetching order books, checking positions) are handled here to decouple the strategy logic from the API specifics.

market_maker.py

The heart of the strategy. Its tick() method contains the main loop that:

1. Fetches market data.
2. Calculates features (like order book imbalance).
3. Calls the predictor.
4. Checks risk controls.
5. Builds target orders.
6. Reconciles and places orders.

advanced_predictors.py

The current default prediction module. It uses features like micro-price, order book imbalance, and trade flow to predict the short-term fair value of the market. This is where you would experiment with new prediction models.

quote_engine.py

Takes the predicted fair value from the predictor and converts it into the actual limit prices for BUY and SELL orders. It incorporates logic for inventory skew and ensures orders are placed safely as a maker.

order_reconciler.py

A crucial component for a GTC strategy. Instead of cancelling all orders every tick, it compares the new target orders with the live open orders and only places/cancels what is necessary, helping to maintain queue priority.

emergency_exit.py

A modular safety mechanism. If it detects that a position is moving sharply against the bot’s favor (based on P&L, price movement, and order book pressure), it signals to exit the position quickly using aggressive maker orders.

data_recorder.py

Asynchronously writes a CSV log file containing key data for every single tick (market prices, predictions, positions, etc.), which is invaluable for offline backtesting and research.