Polymarket Trader

A TypeScript Polymarket trading agent that defaults to paper trading, includes risk controls, and ships with a local dashboard for monitoring state, positions, fills, audit logs, and runtime status.

This project is not financial advice. Prediction markets and automated trading can involve financial, legal, tax, regulatory, platform, and operational risk. Confirm your jurisdiction, Polymarket eligibility, and Terms of Service obligations before using this code.

Current status

• Paper trading is the default and intended mode.
• Live execution is intentionally blocked in this milestone.
• The app reads public Polymarket market data and simulates fills locally.
• Runtime state and logs are written under data/ and are ignored by Git.

Requirements

• Node.js 18 or newer
• npm

Setup

npm install

Run tests

npm test

This builds the TypeScript project and runs the compiled Node test files in dist/test.

Run the paper trader

npm start

This is equivalent to:

npm run start:paper

The bot will:

1. Build the TypeScript source into dist/.
2. Load config/strategy.json.
3. Discover liquid active Polymarket markets when auto-discovery is enabled.
4. Poll order books.
5. Generate mean-reversion paper trade intents.
6. Apply risk checks before every simulated fill.
7. Save state to data/state.json and append audit events to data/audit.log.

Stop the bot with Ctrl+C.

Open the dashboard

Start the dashboard in a second terminal from the project root:

npm run dashboard

Then open:

http://127.0.0.1:4310

The dashboard exposes a local read-only monitoring UI and a JSON status endpoint at /api/status. It reads from data/state.json, data/audit.log, data/runtime.log, and config/strategy.json. It does not place trades.

To use a different host or port:

node dashboard.cjs --host 127.0.0.1 --port 4310

You can also set environment variables:

HOST=127.0.0.1 PORT=4310 npm run dashboard

Check status

After the project has been built at least once:

npm run status

This prints open positions, total exposure, realized P&L, fill count, and kill-switch state from data/state.json.

Kill switch

Block new orders:

npm run halt

Release the kill switch:

npm run halt:off

The kill switch is stored in data/state.json.

Configuration

Edit config/strategy.json.

Important fields:

• mode: keep this as paper.
• tickIntervalMs: delay between trading loop ticks.
• markets: reserved for configured markets.
• autoDiscover.enabled: automatically discover active markets when true.
• autoDiscover.limit: maximum number of markets to trade.
• autoDiscover.minLiquidity: minimum liquidity for discovered markets.
• strategy.lookbackTicks: rolling window for mid-price mean reversion.
• strategy.entryEdge: minimum deviation from rolling mean before a trade intent is generated.
• strategy.orderSizeUsd: requested order size before risk clamping.
• risk.maxPositionUsdPerMarket: maximum simulated exposure per market.
• risk.maxTotalExposureUsd: maximum total simulated exposure.
• risk.maxDailyLossUsd: daily realized loss limit.
• risk.maxOrderSizeUsd: maximum single-order size.
• risk.staleDataMs: stale data circuit breaker threshold.

Data files

Runtime files are created automatically and ignored by Git:

data/state.json
data/audit.log
data/runtime.log
data/*.tmp
data/*.corrupt.*

Use this command to clean generated files:

npm run clean

Live mode

Live trading is not wired in this milestone. The code has an explicit guard that rejects live mode unless both of these environment variables are set:

POLYMARKET_LIVE_CONFIRM=I_UNDERSTAND_THE_RISK
POLYMARKET_PRIVATE_KEY=...

Do not commit private keys, API keys, seed phrases, wallets, runtime logs, state files, or .env files.

Project layout

config/strategy.json   Strategy and risk configuration
dashboard.cjs          Local monitoring dashboard
src/                   TypeScript source
test/                  Node test suite
data/.gitkeep          Placeholder for runtime data directory

Open-source hygiene

This repository is prepared to avoid committing generated files, local machine metadata, runtime state, logs, dependencies, secrets, and BuilderStudio artifacts. Before publishing, run:

npm test
git status --short

Review the final diff and confirm that the MIT license is the license you want to use for the public repository.