Skip to content

README.md

Latest commit

 

History

History
172 lines (139 loc) · 10.3 KB

README.md

File metadata and controls

172 lines (139 loc) · 10.3 KB
Raw

Polyterm — Polymarket Trading-Bot Platform

A multi-version trading-bot platform for Polymarket's crypto Up or Down markets (BTC / ETH / SOL / XRP / DOGE · 5m / 15m / 1h / 1d), with a Bloomberg-style live dashboard. You land on a Version Manager, pick a bot, and enter its own purpose-built UI. Every version is independent and live-switchable; they share only the common execution base (market discovery, detection, order placement, risk, accounting).

Runs in paper mode by default. Live trading is fully wired but gated behind two safety switches and a funding preflight.

┌─ Version Manager ─────────────────────────────┐
│  v1.5  Copy Bot          ● running   +$0.00   │   ← land here, pick a bot
│  v2.0  Strategy Bot                            │
│  v3.0  Market Maker                            │
│  v4.0  Cross-Platform Arb    soon              │
│  v5.0  AI / News                               │
│  v6.0  Weather                                 │
│  v7.0  Arbitrage                               │
│  v8.0  Sportsbook                              │
│  v9.0  Predictor                               │
└───────────────────────────────────────────────┘

Bots

Version Name What it does Status Docs
v1.x Copy Bot Mirror a target wallet's BUYs and SELLs in real time, across any markets you add. Includes a Target/Market Scout. ✅ implemented docs/v1-copy-bot.md
v2.x Strategy Bot Own-signal: last-second momentum + EV gate, multi-asset confirmation, volatility-regime & order-flow filters, signal-based stop-loss, optional Kelly sizing. No target. ✅ implemented docs/v2-strategy-bot.md
v3.x Market Maker Delta-neutral: quote two-sided passive bids and capture the spread via complete sets (Up+Down=$1). Inventory skew + caps, vol-widened spreads, tail flatten. Live wired (post-only resting orders) — beta/untested. ✅ implemented; live beta docs/v3-market-maker.md
v4.0 Cross-Platform Arb Arbitrage the same event across venues (e.g. Kalshi). 🚧 planned docs/v4-cross-platform-arb.md
v5.x AI / News Estimate an event's probability with an LLM + live web search, compare to the market price, and trade the gap on slow non-crypto markets (hold to resolution; tracks calibration). Needs ANTHROPIC_API_KEY. Paper-only for now. ✅ implemented (paper) docs/v5-ai-news.md
v6.x Weather Trade daily temperature-band markets with a calibrated numerical forecast (Open-Meteo ensemble — free, no API key). Normal-CDF band probabilities normalized per event, EV gate + Kelly, hold to resolution, Brier tracking. Paper-only for now. ✅ implemented (paper) docs/v6-weather.md
v7.x Arbitrage Lock risk-free profit from neg-risk underrounds: buy one YES on every outcome when a balanced set costs < $1. Depth-aware sizing, exact-balanced execution, hold to resolution. No forecasting, no API key. Live wired (marketable limit + unwind) — beta/untested. ✅ implemented; live beta docs/v7-arbitrage.md
v8.x Sportsbook Borrow the sharp sportsbook consensus: de-vig bookmaker odds into a true probability and trade Polymarket's deviation. Pre-game only, Kelly sizing, hold to resolution, Brier tracking. Needs ODDS_API_KEY. Paper-only for now. ✅ implemented (paper) docs/v8-sportsbook.md
v9.x Predictor Technical-analysis ensemble (EMA/RSI/MACD/Bollinger/Stochastic/ROC) off live candles + the move-vs-open Φ(z) model → P(Up), traded through an EV gate vs the order book. Live candlestick charts (TradingView Lightweight Charts) with the window-open "first point" line. BTC/ETH/SOL. No API key. Paper-first — TA can't predict short crypto; the EV gate is the edge. ✅ implemented (paper) docs/v9-predictor.md

Full documentation lives in docs/. Start with docs/README.md for the index, or docs/architecture.md for how the platform fits together.

Quick start

npm install               # backend deps
npm run ui:install        # one-time: dashboard deps
npm run generate-wallet   # one-time: writes .env with a fresh paper wallet (if missing)

Run the backend (bot + dashboard WebSocket server on :8787) and the dashboard:

# terminal 1 — backend
npm start
# terminal 2 — dashboard (Vite dev server on :5173)
npm run ui

Open http://localhost:5173. You'll land on the Version Manager — click Enter on a bot to run it and open its dashboard. (For a production-style single build, npm run ui:build outputs web/dist.)

Bounded paper session (e.g. one 15m window then exit):

RUN_SECONDS=900 npm start

At a glance

  • Version Manager — landing screen / control panel; shows every bot's separate P&L and lets you enter (and live-switch) any implemented bot.
  • Per-bot UI — Copy Bot is built around the target (markets, target feed, copy blotter); Strategy Bot is built around the signal (P, z, edge, σ).
  • Markets — add any ticker × duration (5m / 15m / 1h / 1d) from the dashboard; remove with the ✕ on each panel.
  • Scout — score wallets (who to copy) and markets (where to copy) for copy-fitness. See docs/v1-copy-bot.md.
  • Controls — ▶ START / ⏸ STOP (kill switch) · ⟲ RESET (fresh P&L) · 🔍 SCOUT.
  • Config — ⚙ CONFIG: mode, betting/exit modes, gates, risk, per-version params; saved to runtime-config.json and applied live (no restart).
  • Detection — on-chain WebSocket (~2–4 s) primary, /activity API fallback.

Configuration

  • .env — secrets and endpoints: PRIVATE_KEY, WALLET_ADDRESS, TARGET_WALLET, RPC URLs (Alchemy/Infura + public failover), CLOB/Gamma hosts, live switches. Never commit it (gitignored).
  • runtime-config.json — the dashboard's saved knobs (version, mode, betting/exit/gates/risk, market list, per-version params). Owned by the running bot — edit it through the ⚙ CONFIG panel, not by hand, or the running engine will overwrite your edits.

Full reference: docs/configuration.md.

Going live (real money)

Live is off by default. Summary (full steps in docs/configuration.md):

  1. Fund the wallet (pUSD/USDC on Polygon + a little POL for gas).
  2. npm run live:approve — one-time on-chain allowance.
  3. npm run live:check — read-only readiness check.
  4. Set PAPER_TRADING=false and LIVE_ARMED=true in .env.
  5. npm start — a funding preflight refuses to start if the wallet isn't ready.

Risk controls (live + paper parity): max $/clip, max open exposure, daily-loss stop, max entry price. A tripped limit shows a TRADING HALTED banner.

⚠️ These are thin-edge, latency-sensitive strategies. Start in paper, watch the copy fidelity and slippage metrics, and only scale once the edge is convincingly positive. Winning live positions are redeemed on-chain after resolution (the ledger shows expected P&L).

Project layout

src/
  index.js          entrypoint (engine + dashboard server)
  engine.js         the kernel — shared machinery; drives the active strategy
  strategies/       version plugins: base, copy (v1), momentum (v2), registry
  markets.js        active-market discovery (epoch 5m/15m + series 1h/1d), books
  spotFeed.js       Binance price feed + window-open price + momentum, per asset
  targetWatcher.js  target fills via the /activity API
  onchainWatcher.js on-chain CTF transfer detection (BUY in / SELL out)
  paperBroker.js    simulated fills vs the live book; settlement
  liveBroker.js     real CLOB FAK orders (same interface)
  clobClient.js     authenticated CLOB client + funding/allowance preflight
  scout.js          Target Scout + Market Scout (copyability scoring)
  settings.js       runtime settings store (runtime-config.json)
  server.js         WebSocket + HTTP dashboard server
web/                React/Vite dashboard (version manager + per-bot views)
docs/               full documentation (this is the source of truth)
scripts/            wallet generation, live check/approve

Documentation

Everything is documented in docs/ — you can get the full picture from the docs alone:

Disclaimer

For research and educational use. Trading prediction markets carries financial risk; nothing here is financial advice. You are responsible for compliance with Polymarket's terms and your local regulations. No warranty — see Copyright.

Copyright

© 2026 Victor Kutz. All rights reserved.

This is a private, proprietary project. Not licensed for redistribution, resale, or public use without the copyright holder's written permission. Provided “as is”, without warranty of any kind, express or implied, including merchantability and fitness for a particular purpose; the authors are not liable for any claim, damages, or trading losses arising from its use.