Automated trading bot for Polymarket BTC Up/Down binary markets (5- or 15-minute windows; set market.interval_minutes in config.json). It streams the CLOB via WebSocket, computes VWAP, deviation, momentum, and z-score on the favorite side, and fires Fill-And-Kill (FAK) entries when all conditions align. Optional Good-Till-Date (GTD) limits on the opposite token act as a partial hedge (advanced; off by default).

Suite: This bot is part of the PolyBullLabs Polymarket suite. Repository: github.com/PolyBullLabs/polymakret-5min-15min-1hour-arbitrage-bot · Telegram: @terauss

Why this strategy can work (and what breaks it)

Idea: Near the end of a short binary window, the market often prices one side as favorite (higher last price). The bot does not buy blindly: it waits for (a) favorite price in a tunable band, (b) a late entry slice, (c) price stretched above short-horizon VWAP (min_deviation_pct), and (d) positive momentum—roughly, crowd consensus plus recent upward flow on that token.

Profit source (when it exists): If the true chance of the favorite winning exceeds the entry price (e.g. pay $0.80 when win probability is sustainably >80%), expected value can be positive. The indicators are a filter to reduce entries where the book is choppy or mean-reverting against the favorite.

Risk: Binary markets can gap or flip into the close. Break-even win rate ≈ entry price before fees. Slippage, partial fills, and oracle resolution details can erode edge. Start small; use simulation in config when available.

Good fit: You want BTC only, transparent math (see PROJECT_LOGIC.md), and a Rich terminal dashboard. Poor fit: You need multi-asset from one process—use Meridian (up-down-spread-bot) in the same suite.

What This Bot Does

On each interval (e.g. every 5 or 15 minutes, depending on config), Polymarket opens a market asking whether BTC will finish up or down for that window. Two tokens are available:

UP token pays $1.00 if BTC rises, $0.00 if it falls
DOWN token pays $1.00 if BTC falls, $0.00 if it rises

The bot identifies the "favorite" (the token with higher probability), waits for specific technical conditions to align, then buys it. If the prediction is correct, the token resolves to $1.00 for a profit. If wrong, it resolves to $0.00 for a loss.

Key Features

Real-time terminal dashboard with Rich library (order book, indicators, signals, position, P&L)
VWAP-based signal generation with deviation and momentum filters
Historical win rate filtering by price range and time bin
FAK order execution with retry logic and WebSocket fill confirmation
Optional hedging via GTD orders on the opposite token at $0.02
Timeout recovery: detects fills via User WebSocket even after network timeouts
Chainlink BTC/USD oracle tracking: real-time BTC price and deviation from market start
Auto-redemption of winning positions on-chain
Telegram notifications with trade alerts and equity charts
Per-trade drawdown tracking with logging
Persistent trade history in JSON format (survives restarts)

Project Structure

btc-binary-VWAP-Momentum-bot/
|-- main.py                 # Main bot: dashboard, signals, execution, all core logic
|-- config.json             # Trading parameters (strategy, entry, hedge, etc.)
|-- .env.example            # Environment variables template (copy to .env)
|-- requirements.txt        # Python dependencies
|-- chart_pnl.py            # P&L chart generator (run separately)
|-- CONFIG.md               # Full config.json reference
|-- PROJECT_LOGIC.md        # Detailed technical documentation with formulas
|-- docs/
|   +-- README.md           # Step-by-step beginner guide (Windows + Linux)
|-- data/
|   +-- win_rate.csv        # Historical win rate matrix (price ranges x per-minute bins; 5m uses first 5 bins)
+-- src/
    |-- __init__.py
    |-- config_loader.py    # Loads config.json + .env, validates settings
    |-- order_executor.py   # FAK order placement with retry logic
    |-- hedge_manager.py    # GTD hedge order management
    |-- market_finder.py    # Discovers active markets via Gamma API
    |-- position_tracker.py # Position and P&L tracking
    |-- auto_redeemer.py    # On-chain redemption of resolved positions
    |-- telegram_notifier.py# Telegram alerts and chart sending
    |-- user_websocket.py   # User channel WebSocket (order/fill tracking)
    +-- websocket_client.py # Market data WebSocket (prices, trades, book)

Installation (From Scratch on a Clean Machine)

Prerequisites

Linux server (Ubuntu 22.04+ recommended) or macOS
Python 3.11+
Polymarket account with funded USDC balance (on Polygon), POL for gas fees, and API credentials
Private key of your trading wallet

Step 1: System Setup

sudo apt update && sudo apt upgrade -y
sudo apt install -y python3 python3-pip python3-venv git
python3 --version

Step 2: Clone the Repository

cd ~
git clone https://github.com/PolyBullLabs/polymakret-5min-15min-1hour-arbitrage-bot.git
cd polymakret-5min-15min-1hour-arbitrage-bot/btc-binary-VWAP-Momentum-bot

Step 3: Create Virtual Environment

python3 -m venv venv
source venv/bin/activate

Step 4: Install Dependencies

pip install --upgrade pip
pip install -r requirements.txt

Step 5: Configure Environment Variables

cp .env.example .env
nano .env

Fill in your credentials:

Variable	Required	Description
PRIVATE_KEY	Yes	Polygon wallet private key (0x...)
FUNDER_ADDRESS	If proxy	Gnosis Safe address (if using proxy wallet)
SIGNATURE_TYPE	If proxy	0=EOA, 1=Poly Proxy, 2=Gnosis Safe
POLY_API_KEY	Yes	Polymarket CLOB API key
POLY_API_SECRET	Yes	Polymarket CLOB API secret
POLY_API_PASSPHRASE	Yes	Polymarket CLOB API passphrase
RPC_URL	Recommended	Alchemy/Infura Polygon RPC (default: public RPC)
TELEGRAM_BOT_TOKEN	Optional	Telegram bot token from @BotFather
TELEGRAM_CHAT_ID	Optional	Your Telegram user/chat ID

How to get Polymarket API credentials:

Go to https://polymarket.com and connect your wallet
Navigate to your account settings
Generate API credentials (key, secret, passphrase)
These are used for L2 authentication on the CLOB

Step 6: Configure Trading Parameters

nano config.json

See the Configuration section below for parameter descriptions.

Step 7: Create Logs Directory

mkdir -p logs

Step 8: Run the Bot

source venv/bin/activate
python3 main.py

Step 9: Run in Background (Production)

sudo apt install -y tmux
tmux new -s bot

# Inside tmux:
source venv/bin/activate
python3 main.py

# Detach: Ctrl+B then D
# Reattach: tmux attach -t bot

Configuration

The bot is highly configurable -- every aspect of the strategy, risk management, execution, hedging, and notifications can be fine-tuned through config.json without touching any code. You can adjust the entry window, price filters, indicator sensitivity, bet sizing, and more to match your risk tolerance and trading style.

For a complete parameter-by-parameter guide with explanations, examples, and ready-made presets (Conservative / Moderate / Aggressive), see CONFIG.md.

Quick overview of the most important settings:

Parameter	Default	What it controls
`strategy.min_price`	0.75	Minimum token price to enter (lower = riskier, more profit)
`strategy.max_price`	0.88	Maximum token price to enter (higher = safer, less profit)
`strategy.min_elapsed_sec`	530	Wait this many seconds before entering
`strategy.min_deviation_pct`	3	Minimum VWAP deviation to trigger signal
`strategy.no_entry_before_end_sec`	335	Stop entering with this many seconds left
`entry.bet_amount_usd`	5	USD per trade (start small!)
`entry.max_entry_price`	0.88	Hard price ceiling for safety
`hedge.enabled`	false	Automatic hedging on opposite token
`telegram.enabled`	false	Trade notifications via Telegram
`web_dashboard.enabled`	false	Local web UI (same live data as the terminal; JSON at `/api/state`)

When web_dashboard.enabled is true, open http://127.0.0.1:8765/ (or your host/port) in a browser on the same machine. Defaults bind to localhost only; do not expose the port publicly without authentication.

How the Strategy Works

Signal Generation

The bot evaluates 5 conditions every 250ms. ALL must be true to trigger a BUY:

Price in range: min_price <= favorite_price <= max_price
Time elapsed: elapsed_seconds >= min_elapsed_sec
VWAP deviation: min_deviation_pct < deviation < max_deviation_pct
Positive momentum: momentum > 0%
Time remaining: seconds_left > no_entry_before_end_sec

Indicators

VWAP (Volume-Weighted Average Price): SUM(price * volume) / SUM(volume) over the last N seconds
Deviation: (last_price - VWAP) / VWAP * 100% -- how far price moved from its average
Momentum: (price_now - price_Ns_ago) / price_Ns_ago * 100% -- direction of price movement
Z-Score: (price - mean) / stdev over the last 5 seconds -- statistical outlier detection

Execution Flow

Signal detected
  -> FAK order placed
  -> Fill confirmed via WebSocket
  -> Position recorded
  -> Hedge placed (if enabled)
  -> Drawdown tracked every 250ms
  -> Market ends (10s before expiry)
  -> Position resolved, P&L recorded
  -> Winning positions auto-redeemed on-chain

Risk

Higher entry prices mean higher risk. The break-even win rate equals the entry price:

Entry at $0.75 needs 75% win rate to break even
Entry at $0.85 needs 85% win rate to break even
Entry at $0.88 needs 88% win rate to break even

Start with small bet_amount_usd ($1-5) until you understand the behavior.

Logs

The bot creates a logs/ directory with:

File	Description
bot.log	Main application log (connections, errors, BTC price ticks)
signals.log	Full indicator snapshot at each trade entry and market end
orders.log	Detailed order execution log (prices, retries, fills)
hedges.log	Hedge order placement and fill tracking
trading_log.json	Persistent trade history (survives restarts)

Generating Charts

After accumulating trades, generate a P&L chart:

source venv/bin/activate
python3 chart_pnl.py
# Output: logs/pnl_chart.png

Documentation

For a deep technical dive including all formulas, architecture diagrams, and the complete signal generation logic, see PROJECT_LOGIC.md.

Disclaimer

This software is provided for educational and research purposes only. Trading on prediction markets involves substantial risk; you may lose your entire stake. No performance is guaranteed. The authors and contributors are not responsible for financial losses, bugs, or exchange rule changes. Use simulation where offered, keep API keys and private keys secret, and never trade with capital you cannot afford to lose. For extended quant strategies (Kelly, Monte Carlo, advanced TA, sizing systems), see the repository README and contact @terauss.

License

MIT