Open-source infrastructure for researching, simulating, monitoring, and safely operating Polymarket strategies.
This repository is a full-stack prediction-market research lab: real-time market ingestion, strategy engines, risk controls, paper/live execution plumbing, settlement helpers, monitoring, and a Next.js trading terminal.
It is designed to be useful in three ways:
- Curious users can run a wallet-free local demo in a couple of minutes.
- Builders can fork the strategy template, add a signal, and see it in the dashboard.
- Operators can run the full Docker stack with fail-closed kill switches and paper mode before enabling live execution.
This project does not include accounts, wallets, API keys, or financial advice. Trading is disabled by default.
If you are not a developer or have never used Docker before, use the guided beginner flow:
git clone https://github.com/dantraynor/algorithmic-trading-polymarket.git
cd algorithmic-trading-polymarket
make startChoose option 1 for the safe demo. It uses fake data, needs no wallet, and cannot place trades.
Full walkthrough: docs/BEGINNER_GUIDE.md.
Run the dashboard with synthetic data. No wallet, no API keys, no live order flow.
git clone https://github.com/dantraynor/algorithmic-trading-polymarket.git
cd algorithmic-trading-polymarket
make doctor
make demoOpen http://127.0.0.1:3001 and sign in with:
demo_dashboard_secret
Stop it with:
make demo-downThe demo starts only Redis, the dashboard, and a synthetic data feeder. Execution services are not started.
- Real architecture - Rust ingestion, TypeScript strategy services, Redis streams, SQLite analytics, Docker Compose, and CI.
- Safe first-run experience - local demo, paper defaults, explicit live opt-in, global and per-strategy kill switches.
- Hackable strategy surface - strategies publish typed Redis signals and show up in the dashboard through a registry entry.
- Production-shaped operations - Docker images, GCP Terraform, GitHub Actions deployment, Grafana/Prometheus monitoring, runbooks.
- Readable codebase - services are split by responsibility instead of hiding everything in one bot process.
| Area | Services |
|---|---|
| Market data | ingestion, signal-core |
| Crypto strategies | btc-5m, btc-5m-latency, btc-5m-momentum, crypto-signals |
| Sports strategies | sports-signals |
| Execution and risk | execution, alpha-executor, settlement |
| UI and analytics | dashboard, shared |
| Operations | Docker Compose, Terraform, Prometheus, Grafana, GitHub Actions |
Polymarket WebSocket
|
v
ingestion (Rust) ------ Redis order books / market state
|
+--> signal-core (Rust arbitrage scanner)
+--> btc-5m / latency / momentum strategies
+--> crypto-signals
+--> sports-signals
|
v
Redis signal bus
|
+--------------+--------------+
v v
execution engine alpha-executor
| |
+--------------+--------------+
v
settlement
dashboard reads Redis, SQLite, and optional on-chain balances
Use this path when you want paper trading or live-ready infrastructure.
- Docker Desktop or Docker Engine with Compose v2
- Node.js 20+ for local TypeScript development
- Rust stable for local Rust development
- A Polygon RPC URL for live/paper strategy services that need chain reads
- Wallet, Safe, and Polymarket CLOB credentials only if you intend to execute orders
make setupThen edit .env. Keep all *_DRY_RUN=true values while testing.
To derive CLOB credentials from a funded/authorized key:
cd scripts
npm install
PRIVATE_KEY=0x... node derive-keys.jsAdd the printed CLOB_API_KEY, CLOB_API_SECRET, and CLOB_PASSPHRASE to .env.
make up
make ps
make logsDashboard:
http://127.0.0.1:3001
Trading is fail-closed. Missing switches mean no trading.
# Global enable
docker exec tradingbot-redis redis-cli -s /var/run/redis/redis.sock SET TRADING_ENABLED TRUE
# Emergency stop
docker exec tradingbot-redis redis-cli -s /var/run/redis/redis.sock DEL TRADING_ENABLEDEach strategy also has its own switch, for example BTC_5M_LATENCY_TRADING_ENABLED and ALPHA_TRADING_ENABLED. The global switch and the strategy switch must both be enabled.
| Layer | Behavior |
|---|---|
| Demo mode | No execution services, synthetic data only |
| Dry run | Strategy logic runs, orders are not sent |
| Kill switches | Global and per-strategy Redis flags must be explicitly enabled |
| Risk caps | Max size, slippage, drawdown, streak, and exposure controls |
| Freshness checks | Stale signals and corrupt order books are discarded |
| Deployment hygiene | Secrets live in .env or Secret Manager, never in the repo |
See docs/SAFETY.md for operator guidance.
make doctor # verify tools
make demo # dashboard-only demo
make up # full local stack
make test # run configured service tests
make down # stop full stackBuild individual services:
cd ingestion && cargo build --release
cd signal-core && cargo build --release
cd btc-5m-latency && npm ci && npm run build && npm test
cd dashboard && npm ci && npm run build && npm test- Create a service directory with
src/index.tsor Rust equivalent. - Read market data from Redis or an external feed.
- Publish a typed signal to a Redis channel such as
signals:alpha. - Add a risk gate or reuse
alpha-executor. - Add the service to Docker Compose.
- Register it in
dashboard/src/lib/strategy-registry.ts. - Add tests for signal generation and risk behavior.
More detail: CONTRIBUTING.md.
.
├── dashboard/ Next.js terminal UI
├── ingestion/ Rust WebSocket order book consumer
├── signal-core/ Rust arbitrage scanner
├── execution/ TypeScript CLOB order execution
├── settlement/ Position merge and settlement helper
├── alpha-executor/ Unified alpha execution and portfolio risk
├── btc-5m*/ BTC 5-minute strategy variants
├── crypto-signals/ Multi-asset crypto signal service
├── sports-signals/ NBA/NCAA signal service
├── shared/ Shared types, Redis keys, SQLite helpers
├── infrastructure/ Terraform, Redis, monitoring
├── scripts/ Setup, demo, and utility scripts
└── docs/ Operator and contributor documentation
Prediction markets and automated trading involve financial, legal, and operational risk. Use this software only where permitted, start with demo or paper mode, review every strategy before running it, and never commit secrets.