Build and Run a Polymarket Prediction Bot in Your Terminal

What Is the Polymarket Prediction Bot?

Polymarket Prediction Bot is an open-source, keyboard-driven terminal application for exploring prediction markets on Polymarket. It combines a markets browser, live central-limit order book view, strategy engine, position tracker, and fill log in a Textual and Rich terminal interface.

Polymarket markets typically contain YES and NO shares that resolve to $1 or $0 according to the outcome of a real-world event. Because the market price can be interpreted as an implied probability, the bot compares market prices with fair-probability estimates, examines order-book conditions, and surfaces potential edge or arbitrage signals.

Important: This is an unofficial educational project and is not affiliated with Polymarket. It is not financial advice, and no included strategy guarantees a profit. Begin with --demo, which uses a bundled dataset and simulated fills without touching a wallet.

Key Features

• Markets browser: Filter markets by volume, spread, category, and time remaining until resolution.
• CLOB order book: Inspect YES and NO bids and asks, spreads, midpoint prices, and book imbalance.
• Strategy engine: Run probability-edge, book-imbalance, and liquidity strategies individually or together.
• Signal tracking: Review suggested sides and confidence values from 0 to 1.
• Position monitoring: Follow open YES and NO sizes, average cost, unrealized PnL in USDC, and resolution countdowns.
• Fill log: Maintain a local record of signals, simulated or CLOB fills, and cancellations.
• Dashboard: View top movers, wide spreads, markets nearing resolution, and queued signals.
• Paper trading: Test workflows with a virtual USDC balance before configuring live access.
• Risk controls: Apply maximum USDC exposure, per-market caps, and a daily loss limit.
• Cross-platform interface: Run the application on Windows, macOS, or Linux.

Prerequisites

The standard installation requires Git, Python 3.11 or newer, and pip. The repository also provides one-click launchers that unpack a bundled standalone interpreter on first use, so a system Python installation is not required when using those launchers.

Install the Bot with Python

1. Clone the repository:

   git clone https://github.com/gulelmatthews/Polymarket-Perpetual-Bot.git

2. Enter the project directory:

   cd Polymarket-Perpetual-Bot

3. Install the required packages:

   pip install -r requirements.txt

4. Start with the bundled demo dataset:

   python main.py --demo

The project also exposes a package entry point through python -m polymarket_bot. Its command-line parsing and launch logic are implemented in the host package.

Use the One-Click Launchers

Windows

Run the included batch launcher:

run.bat

Linux and macOS

Make the shell launcher executable, then run it:

chmod +x run.sh
./run.sh

On first use, these launchers unpack the bundled standalone interpreter required by the application.

Navigate the Terminal Dashboard

The interface is organized into six primary views. Use the number keys to move directly between them:

• 1: Dashboard
• 2: Markets
• 3: Order Book
• 4: Strategy
• 5: Positions
• 6: Log

Additional keyboard controls support the main workflow:

• /: Filter the market list.
• Enter or b: Open the CLOB book for the selected market.
• s: Run the strategy engine across the watchlist.
• o: Compose a paper order.
• t: Cycle through the available themes.
• q: Quit the application.

Basic Demo Workflow

1. Launch the application with python main.py --demo.

2. Press 2 to open the markets browser.

3. Use / to narrow the visible markets based on the available filters.

4. Select a market and press Enter or b to inspect its YES and NO order book.

5. Review the best bids and asks, spread, midpoint, and relative size imbalance.

6. Press s to scan the watchlist with the enabled strategies.

7. Open the Strategy view with 4 and review each signal's confidence and suggested side.

8. Press o to compose a paper order when you want to test a signal.

9. Use 5 to inspect positions and unrealized PnL, then use 6 to review signals and simulated fills.

Understand the Built-In Strategies

Probability-Edge Strategy

This strategy compares the market price with a fair-probability model. It generates a signal when the difference exceeds the configured threshold. For example, if the model's fair probability is meaningfully above the current YES price, the resulting signal may suggest the YES side.

The quality of this signal depends on the fair-probability model supplied to the strategy. Treat confidence as an analytical output rather than a guarantee.

Book-Imbalance Strategy

The book-imbalance strategy examines the relative size available on the YES and NO sides. A large size skew can be treated as a directional cue. This is order-book information, not proof that a market will move or resolve in that direction.

Liquidity Strategy

The liquidity strategy looks for wide spreads and potential mean reversion toward the midpoint. Wide spreads can present opportunities, but they can also indicate weak liquidity or elevated execution risk.

Cross-Market Signals

The bot can surface YES-plus-NO spread and multi-outcome arbitrage signals. These should be evaluated alongside available liquidity, order-book depth, and risk limits rather than treated as automatic profits.

Configure Live Mode

Live mode requires your own Polymarket API credentials. Create the configuration file at ~/.polymarket-bot/config.toml with the following structure:

[auth]
private_key    = "0x…"
proxy_address  = "0x…"
api_key        = "…"
api_secret     = "…"
api_passphrase = "…"
endpoint       = "https://clob.polymarket.com"

The private key is the Polygon EOA private key, while proxy_address is the Polymarket proxy or signer address. The application reads credentials only from this local configuration file.

On systems that support Unix file permissions, restrict access to the file:

chmod 0600 ~/.polymarket-bot/config.toml

Security warning: Never commit the configuration file, private key, API secret, or passphrase to source control. The project states that keys remain local and are not logged.

After configuring credentials, live mode can be started with:

python main.py

Live order placement is gated behind explicit configuration. Validate the setup in demo mode first, confirm your exposure controls, and check whether Polymarket is available in your jurisdiction. The project does not bypass geofencing.

Advanced Usage Tips

Combine Strategy Context

The built-in strategies are selectable and composable. Instead of acting on one metric alone, compare probability edge, order-book imbalance, spread width, and signal confidence. Agreement between indicators can provide more context, although it still does not eliminate trading risk.

Inspect Liquidity Before Considering a Signal

A displayed market price does not show how much size can be executed at that price. Open the book and inspect bid and ask depth, spread, midpoint, and imbalance before evaluating an edge or arbitrage signal.

Use the Log as a Paper Trail

The bot logs signals, fills, and cancellations. Reviewing the log can help you compare strategy outputs with subsequent simulated outcomes and identify cases where a high-confidence signal did not behave as expected.

Monitor Resolution Time

Use the markets browser and dashboard to identify markets that resolve soon. Resolution timing affects how long capital may remain exposed, while the Positions view provides a countdown for open markets.

Apply Risk Controls Before Live Use

Configure and respect the available maximum USDC exposure, per-market cap, and daily loss limit. These controls are especially important when strategies are connected to live order templates.

Keep Demo and Live Workflows Separate

Use --demo while learning the keybindings, testing strategy combinations, and observing simulated fills. Move to credentialed live mode only after confirming that the interface, signal interpretation, and risk settings behave as expected.

Project Structure

The repository separates command-line startup, configuration, strategy logic, data models, and the terminal interface:

polymarket-prediction-bot/
├── main.py
├── polymarket_bot/
│   ├── __main__.py
│   ├── cli.py
│   ├── config.py
│   ├── core/
│   └── tui/
├── support/
├── requirements.txt
├── run.bat
├── run.sh
└── release/

main.py is the primary entry point, while polymarket_bot/core/ contains models, the strategy engine, and mock data. The polymarket_bot/tui/ directory contains the Textual screens, widgets, and styles. The release/ directory is reserved for planned precompiled binaries.

Conclusion

Polymarket Prediction Bot provides a unified terminal workflow for browsing prediction markets, inspecting CLOB liquidity, generating strategy signals, and tracking positions and fills. Start with python main.py --demo, learn the keyboard-driven interface, evaluate signals in context, and apply strict exposure controls before considering credentialed live mode.

The project is distributed under the MIT License and is intended as an independent educational toolkit rather than financial advice.