Installation — PolySpread Bot

Prerequisites

Python 3.10+ installed locally
A Polymarket account with API access
A Polygon wallet with pUSD (see funding guide below)
MATIC/POL for gas (a few cents worth)

Need pUSD?

If you don't have pUSD in your wallet yet: buy USDC on an exchange, withdraw to Polygon network, then wrap to pUSD via Polymarket's CollateralOnramp. Full guide in Step 2 of this tutorial.

Step 1: Download the Bot

After purchasing, you'll receive the source code as a ZIP file or GitHub repository link. Extract it to a folder:

# Example folder structure after extraction
polymarket-spread-bot/
  bot/
  main.py
  requirements.txt
  .env.example
  README.md

Step 2: Configure Environment

Copy .env.example to .env and fill in your credentials:

# Polymarket CLOB API credentials (from polymarket.com Settings → API)
POLY_API_KEY=your_api_key_here
POLY_API_SECRET=your_api_secret_here
POLY_API_PASSPHRASE=your_passphrase_here

# Wallet addresses
POLYMARKET_FUNDER=0xyour_funder_wallet_address
POLYMARKET_PRIVATE_KEY=0xyour_private_key_here

# Trading parameters
MAX_BUDGET_USD=50
MAX_PER_WINDOW_USD=5

Never commit .env to git!

Your private key gives full wallet access. Add .env to .gitignore before your first commit.

Step 3: Install Dependencies

# Create and activate virtual environment (recommended)
python -m venv venv
# Windows: venv\Scripts\activate
# macOS/Linux: source venv/bin/activate

# Install requirements
pip install -r requirements.txt

Step 4: Run Simulation Test

Before trading real money, run a simulation to verify everything works:

python main.py --mode sim --budget 10 --cycles 1

This runs one 5-minute window in simulation mode with a $10 budget. No real orders are placed. You should see debug output showing price checks, spread calculations, and hypothetical trades.

Step 5: Go Live

When you're satisfied with the simulation, run live mode:

python main.py --mode live --budget 10 --cycles 1 --yes

Start small!

First live run with $10 budget. Verify orders fill correctly and you understand the flow before scaling up.

Troubleshooting

Problem	Solution
`balance: 0` error on order	Deposit pUSD to your Polymarket wallet. Check `check_balance.py` in scripts/ folder.
FAK orders not filling	CLOB has limited liquidity at certain prices. The bot logs "no seller at X price". This is normal — wait for better prices.
API key error (400)	Regenerate API key on polymarket.com Settings page. Update .env with new credentials.
WebSocket connection errors	The bot auto-reconnects. Check your internet connection. No action needed.
Combined price always near $1.00	Binary tokens naturally sum to ~1.0. The bot waits for mid-range prices (both sides 40-60¢) that rarely occur. Run multiple windows.

Quick Test Script

A standalone test script is included to verify your FAK limit order flow works:

python test_buy.py

This prompts you for a side (Up/Down) and price, then attempts a single $1 FAK limit buy. Use it to confirm your API credentials and balance are correct before running the full bot.

Installation & Setup Guide