English | 简体中文

Poly-Maker: A Market Making Bot for Polymarket

Disclaimer: This is not financial advice. Trading cryptocurrencies and participating in prediction markets involves significant risk. This is high-risk software that trades real money. Market making can lead to losses due to sudden price movements, one-sided fills, market resolution, API/network failures, or changes in reward structures. Always start with DRY_RUN=true and use very small amounts of capital for live testing.

---

This repository contains a market-making bot for the Polymarket prediction market platform. It has evolved to include two primary architectures:

1. Lightweight Bot (Active): The primary, modern implementation. It's a standalone market-making bot configured via a simple .env file, designed for efficiency and ease of use. It uses the official py-clob-client-v2. This is the recommended version and the focus of this README.
2. Legacy System (Reference): The original implementation, which was a more complex system reliant on Google Sheets for configuration, WebSockets for data streams, and a Node.js script for position merging. This is preserved for reference but is not the main execution path.

Features (Lightweight Bot)

• .env Configuration: All parameters, from API keys to strategy variables, are managed in a single .env file.
• Rebate-Focused Strategy: Primarily uses GTC (Good-Til-Cancelled) + Post-Only orders to act as a maker and capture rebates.
• Short-Term Price Prediction: Employs a predictor based on micro-price and order book imbalance to forecast short-term fair value.
• Intelligent Order Reconciliation: Minimizes unnecessary order cancellations and placements, helping to preserve order queue priority.
• Integrated Risk Management:
  • Per-market and global exposure limits.
  • Inventory skew logic to adjust quotes based on current holdings.
  • Emergency exit mechanism to quickly unload positions in adverse market conditions.
• Data Recording: Logs market state, predictions, and positions to a CSV file for every tick, enabling offline analysis and strategy refinement.
• Helper Utilities: Includes scripts for market discovery, latency measurement, and authentication troubleshooting.
• Deployment Ready: Comes with a systemd service file for running as a background service on a VPS.

Architecture Overview

The lightweight bot's logic is modular, making it easy to understand and extend.

• main.py: The main entry point for the application.
• config.py: Loads and validates all configuration parameters from the .env file.
• polymarket_adapter.py: A wrapper around the Polymarket CLOB client, abstracting away API interactions.
• market_maker.py: The core strategy loop that orchestrates data fetching, prediction, risk management, and order execution.
• advanced_predictors.py: Implements the price prediction logic.
• quote_engine.py: Converts the predicted fair value into maker-safe bid/ask quotes.
• order_reconciler.py: Compares desired orders with existing live orders to decide what to cancel, place, or keep.
• emergency_exit.py: Contains the logic for the automated emergency exit strategy.
• data_recorder.py: Asynchronously writes tick-by-tick data to a log file.

Installation

1. Clone the repository:

   git clone https://github.com/your-username/poly-maker.git
   cd poly-maker

2. Install Python dependencies using uv:

   uv sync

3. (Optional) Install Node.js dependencies for the legacy position merger:

   cd poly_merger
   npm install
   cd ..

Configuration

1. Create your environment file:

   cp .env.example .env

2. Edit .env: Open the .env file and fill in your details. Refer to ENV_CONFIG_GUIDE.md for a detailed explanation of every variable.

   Minimal Required Configuration:

   # Your wallet private key (e.g., from MetaMask)
   PK=YOUR_PRIVATE_KEY
   # Your Polymarket funder/proxy wallet address
   FUNDER_ADDRESS=YOUR_FUNDER_ADDRESS
   # Signature type (3 is recommended for new users, see check_auth.py for details)
   SIGNATURE_TYPE=3
   
   # Market to trade (find using helper scripts)
   CONDITION_ID=0x...
   TOKEN_ID_YES=...
   TOKEN_ID_NO=...
   
   # --- Core Strategy ---
   # Set to false for live trading
   DRY_RUN=true
   # Size of each order in USDC
   ORDER_NOTIONAL_USDC=5
   # How often to refresh quotes (seconds)
   REFRESH_INTERVAL_SECONDS=8
   
   # --- Risk Management ---
   # Max exposure for this specific market (USDC)
   MAX_MARKET_EXPOSURE_USDC=25
   # Max total exposure across all markets managed by the bot
   MAX_GLOBAL_EXPOSURE_USDC=80
   
   # --- Prediction ---
   # Your estimated latency in milliseconds (use latency_probe.py)
   PREDICTION_LATENCY_MS=180

Usage

1. Find a Market

Before you can run the bot, you need to tell it which market to trade.

• Discover markets with liquidity rewards:

  uv run python discover_markets.py --limit 10

• Get IDs from a market URL: If you have the URL of a market from the Polymarket website, you can use resolve_market.py.

  uv run python resolve_market.py "https://polymarket.com/event/..."

  Copy the CONDITION_ID, TOKEN_ID_YES, and TOKEN_ID_NO from the script's output into your .env file.

2. Measure Latency

The prediction logic depends on an accurate estimate of your system's latency. Run the latency probe to find this value.

uv run python latency_probe.py --samples 20

Take the p95 value for safe_horizon_ms (or live_horizon_ms if you run a live probe) and set it as PREDICTION_LATENCY_MS in your .env file.

3. Check Authentication

If you encounter invalid signature errors, this script can help diagnose mismatches between your private key, funder address, and signature type.

uv run python check_auth.py

4. Run the Bot

ALWAYS start with a dry run to ensure your configuration is correct and the bot's proposed orders are reasonable.

• Dry Run (No real orders placed):

  uv run python main.py

  The bot will print the orders it would have placed.

• Live Trading: Once you are confident, set DRY_RUN=false in your .env file.

  DRY_RUN=false uv run python main.py

  Logs will be printed to the console and saved to logs/market_maker.log.

Deployment on a VPS

For continuous operation, it's recommended to run the bot on a server (e.g., a London-based VPS for lower latency to Polymarket servers). A systemd service file is provided in service/poly-maker.service.

1. Copy the service file to /etc/systemd/system/.
2. Set the WorkingDirectory and EnvironmentFile paths correctly.
3. Use systemctl to enable and start the service.

sudo cp service/poly-maker.service /etc/systemd/system/polymaker.service
sudo systemctl daemon-reload
sudo systemctl start polymaker.service
sudo systemctl enable polymaker.service # To start on boot

Legacy Components

The repository also contains the original, more complex implementation in directories like poly_data/, data_updater/, and files like trading.py. These components relied heavily on Google Sheets for configuration and state management. They are not used by the current main.py entry point but are kept for reference.

Contributing

Contributions are welcome! Please read the Contributing Guide for details on how to get started, report bugs, and submit pull requests.

License

This project is licensed under the terms of the LICENSE file.

---

Project Status