Skip to main content
Detailed installation instructions for the Polymarket Bot, including prerequisites, dependencies, and environment setup.

​
Prerequisites

1

Node.js 18+

The bot uses ES modules and requires Node.js 18 or higher.
brew install node
Verify installation:
node --version  # Should be v18.0.0 or higher
2

pnpm package manager

Install pnpm for efficient dependency management:
npm install -g pnpm
You can also use npm or yarn, but the project uses pnpm by default.
3

Git

Required to clone the repository:
git --version
If not installed, download from git-scm.com.

​
Installation

1

Clone repository

git clone <your-repo-url>
cd polymarket-bot
2

Install dependencies

pnpm install
This installs two production dependencies:
  • ws (v8.19.0+) - WebSocket client for Chainlink price feed
  • chalk (v5.6.2+) - Terminal UI with colors
And one dev dependency:
  • @types/ws (v8.18.1+) - TypeScript definitions for WebSocket types
3

Verify installation

Check that the bot can start:
node src/index.js
You should see the live interface with WebSocket connecting to Polymarket’s Chainlink oracle.
The bot will create data/ directory automatically on first run for storing history and logs.

​
Project structure

After installation, your project structure will look like: 
polymarket-bot/
├── src/
│   ├── index.js              # Main orchestrator and event loop
│   ├── config.js             # Configuration loader
│   ├── feeds/
│   │   ├── chainlink.js      # WebSocket feed for live BTC price
│   │   ├── vatic.js          # Strike price API client
│   │   └── polymarket.js     # Market discovery + EV calculator
│   ├── engine/
│   │   ├── probability.js    # Black-Scholes binary option model
│   │   ├── volatility.js     # EWMA volatility estimator
│   │   ├── momentum.js       # ROC and mean reversion
│   │   ├── predictor.js      # Combined prediction engine
│   │   ├── calibration.js    # Platt sigmoid recalibration
│   │   └── metrics.js        # Brier, Log Loss, Murphy, bands
│   ├── tracker/
│   │   ├── interval.js       # 5-minute interval lifecycle
│   │   └── history.js        # JSON persistence
│   ├── reporter/
│   │   └── daily.js          # Daily report generator
│   ├── risk/
│   │   ├── position-sizer.js # Fractional Kelly bet sizing
│   │   └── drawdown-tracker.js # 4-level risk management
│   ├── ui/
│   │   └── display.js        # Console UI renderer
│   └── logger/
│       ├── logger.js         # Structured JSON logger
│       └── tick-logger.js    # Raw tick JSONL writer
├── config/
│   └── default.json          # Default configuration
├── data/                     # Auto-created on first run
│   ├── history.json          # Persistent interval history
│   ├── logs/                 # Daily log files
│   └── ticks-*.jsonl         # Raw tick data
├── package.json
└── README.md

​
Configuration

The bot works out of the box with default settings in config/default.json. Key parameters: 
{
  "engine": {
    "ewma": {
      "lambda": 0.94
    },
    "abstention": {
      "minTicks": 50,
      "deadZone": 0.10,
      "minAccuracy": 0.40,
      "minEV": 0.05,
      "minMargin": 0.15
    }
  }
}
  • lambda - EWMA decay factor (0.94 = standard)
  • minTicks - Minimum data points before trading (50)
  • deadZone - Abstain if base prob within ±10% of 50%
  • minAccuracy - Suspend if rolling accuracy < 40%
  • minEV - Minimum Expected Value (5%)
  • minMargin - Minimum edge in pp (15pp)
You can modify config/default.json to customize behavior. The bot loads this file at startup via src/config.js.

​
Running the bot

pnpm start

​
Data sources

The bot connects to these external services:
SourcePurposeEndpoint
Polymarket ChainlinkLive BTC/USD pricewss://ws-live-data.polymarket.com
Vatic Trading APIStrike pricesapi.vatic.trading/api/v1/targets/timestamp
Polymarket Gamma APIMarket discoverygamma-api.polymarket.com/events
Polymarket CLOBMarket pricesclob.polymarket.com/price
All data sources are public APIs. No authentication required.

​
Troubleshooting

If you see connection errors:
  1. Check your internet connection
  2. Verify Polymarket’s WebSocket is available: wss://ws-live-data.polymarket.com
  3. Check for firewall blocking WebSocket connections
  4. The bot automatically reconnects on disconnect
If you see ESM import errors:
# Reinstall dependencies
rm -rf node_modules
pnpm install
Ensure package.json has "type": "module".
The data/ directory is created automatically on first run. If missing:
mkdir -p data/logs
The bot will create history.json and log files as needed.
If Vatic Trading API is unavailable:
  • The bot will retry automatically
  • Check API status at api.vatic.trading
  • Verify your system clock is synchronized (API uses timestamps)

​
Next steps

Quickstart

Get the bot running in 5 minutes

Configuration

Customize engine parameters and risk settings

How it works

Understanding Black-Scholes, EWMA, and momentum models

API reference

Data feeds, prediction engine, and risk management APIs

Build docs developers (and LLMs) love

Get started for freeTalk to us