LockForge — Polymarket BTC Dump-and-Hedge / Lock-Profit Trading Bot (5m · 15m · 1h)

LockForge is a production-minded, open-source Polymarket trading bot for BTC Up/Down markets on 5-minute, 15-minute, and 1-hour windows. It implements a dump-and-hedge / lock-profit strategy: detect sharp BTC moves against the market's price-to-beat (PTB), enter the winning side, hedge the opposite leg when pair cost is cheap enough, merge matched shares into USDC, and hard-stop all new buys before resolution.

Built in TypeScript on Node 20+ with modular architecture, typed config, paper/live modes, SQLite trade journal, and structured [DUMP] / [LOCK] / [SKIP] logging.

From the Developer

I've been running LockForge on Polymarket BTC 5m / 15m / 1h Up/Down windows and have achieved decent, repeatable results — positive lock edges, sensible skip rates in chop, and a workflow I trust enough to keep sizing up. That said, I'm not satisfied yet: better lock timing, cleaner hedge fills on thin books, and smarter chop filtering would push profitability meaningfully higher.

I want to discuss this project with you.

Whether you're tuning dump thresholds, wiring live CLOB execution, improving Chainlink divergence guards, comparing hedge-ladder vs lock-profit approaches, or sharing what you've seen running real size — open an issue, start a Discussion, or reach out directly. The best improvements come from people actually running the bot and comparing session logs.

If you've built Polymarket bots before, if you're researching BTC Up/Down microstructure, or if you're exploring automated prediction-market strategies — let's compare notes and push this further together.

Performance Dashboard

Session analytics from paper and live runs. Every dump, lock, skip reason, and merge is logged for full explainability — download the repo, run paper mode, and reproduce the same decision trail.

Equity & Live PnL

Live equity curve, win rate, session PnL, and BTC price-to-beat tracking across 5m windows.

Dump Detection & Hedge Events

Velocity vs PTB, dump signal markers, Up/Down CLOB odds, and hedge lock triggers in real time.

Lock-Profit Analysis

Pair cost distribution, lock success rate, Sharpe/drawdown, merge economics, and timeframe heatmap.

Signal Quality & Session Stats

Regime indicator, Chainlink vs Binance divergence gauge, structured event feed, and session counters.

Strategy — Dump-and-Hedge / Lock-Profit

| Step | Action | |------|--------| | 1. Detect dump | Watch Binance BTCUSDT + Chainlink Data Streams. When BTC moves sharply vs PTB inside the open window, enter the winning side (Up or Down) with a sized taker/maker buy. | | 2. Hedge / lock | Track avg entry on the filled side. When avgentry + oppositeask ≤ LOCKCOSTMAX (default 0.985–0.99), buy the opposite side and merge matched pairs into USDC. | | 3. Can't lock? | Optional expand/rebalance under strict caps — never chase near resolution. | | 4. Ride-the-winner | Optional late-window hold when hedge unavailable (max exposure rules only). | | 5. Hard cutoff | Stop all new buys at T-90s (5m), T-180s (15m), T-600s (1h). Cancel resting orders. Wait for resolution and auto-redeem winners. |

Example structured logs:

[DUMP] btc-5m Δ=-18bps side=Down fill=$40 avg=0.61
[LOCK] opposite ask=0.37 pair=0.98 hedged=$40 merged=yes edge=$0.80
[SKIP] chop regime / stale chainlink / inside cutoff

Why LockForge?

| Feature | LockForge | |---------|-----------| | Strategy | Dump-and-hedge / lock-profit — not blind directional betting | | Markets | BTC Up/Down 5m · 15m · 1h via Gamma slug discovery | | Feeds | Binance trades + Chainlink oracle guard (don't trust CEX alone) | | Execution | Polymarket CLOB WebSocket + REST fallback, FOK/FAK/GTC | | Risk | Spend caps, imbalance limits, hourly loss circuit breakers, kill switch | | Modes | Paper (full simulation) · Monitor · Live | | Journal | SQLite fills, merges, events — exportable for analysis | | CLI | doctor · run · paper · live · status · redeem |

Quick Start

Prerequisites

• Node.js 20+
• Network access to Binance WebSocket, Polymarket Gamma/CLOB APIs

Install

git clone https://github.com/YOUR_USERNAME/LockForge-Polymarket-BTC-Dump-and-Hedge-Lock-Profit-Trading-Bot-5m-15m-1h.git
cd LockForge-Polymarket-BTC-Dump-and-Hedge-Lock-Profit-Trading-Bot-5m-15m-1h
npm install
cp .env.example .env

Health Check

npm run doctor

Paper Mode (recommended first)

npm run paper:5m    # BTC 5m — no wallet required
npm run paper:15m   # BTC 15m shadow
npm run paper:1h    # BTC 1h shadow

Paper mode uses the exact same decision path as live — fills are simulated against the real order book.

Run & Status

npm run run -- --profile BTC_5M
npm run status
npm test
npm run typecheck
npm run build

Architecture

lockforge/
├── config/
│   └── profiles.yaml              # Per-timeframe thresholds, sizing, status
├── docs/
│   ├── assets/                    # Dashboard screenshots
│   └── RUNBOOK.md                 # Shadow → live rollout guide
├── src/
│   ├── app/
│   │   ├── bot.ts                 # Main orchestrator (WATCH → DUMP → HEDGE → LOCKED → CLOSE)
│   │   ├── dashboard.ts           # CLI live dashboard
│   │   └── cli/
│   │       ├── doctor.ts          # Connectivity + config healthcheck
│   │       ├── run.ts             # Run with profile from .env
│   │       ├── paper.ts           # Paper trading
│   │       ├── live.ts            # Live trading (gated)
│   │       ├── status.ts          # Session status + SQLite stats
│   │       └── redeem.ts          # Post-resolution redeem
│   ├── config/                    # Zod-validated ENV + YAML loader
│   ├── marketDiscovery/           # Gamma slug discovery (btc-updown-*)
│   ├── feeds/
│   │   ├── binance.ts             # BTCUSDT trades + velocity ring buffer
│   │   └── chainlink.ts           # Settlement oracle (divergence guard)
│   ├── strategy/
│   │   ├── dump_detector.ts       # Velocity, PTB delta, chop/ATR filter
│   │   └── lock_engine.ts         # Pair cost, hedge triggers, merge math
│   ├── inventory/                 # Position tracking, imbalance, locked profit
│   ├── risk/                      # Spend caps, circuit breakers, cutoff gates
│   ├── execution/                 # FOK/FAK paper + live adapter
│   ├── mergeRedeem/               # Merge pairs + redeem winners
│   ├── storage/                   # SQLite trade journal
│   ├── alerts/                    # Telegram notifications
│   └── utils/                     # Logger, math, graceful shutdown
└── tests/                         # Lock math + dump detector unit tests

Signal Pipeline

flowchart TB
    subgraph Feeds
        A[Binance BTCUSDT WS]
        B[Chainlink Data Streams]
        C[Polymarket CLOB WS]
    end
subgraph Strategy         D[Dump Detector]         E[Lock Engine]         F[Risk Gates]     end
subgraph Execution         G[Executor FOK/FAK/GTC]         H[Inventory Manager]         I[Merge + Redeem]     end
A --> D     B --> D     B --> F     C --> E     D -->|dump signal| F     F -->|pass| G     G --> H     H --> E     E -->|pair cost OK| G     G --> I     D -->|chop / stale| J[Skip Log]     F -->|cutoff / cap| J

Core Modules

| Module | Responsibility | |--------|----------------| | market_discovery | Discover recurring markets via Gamma API — slugs btc-updown-5m-, btc-updown-15m-, btc-updown-1h-* | | price_feeds | Binance trade/bookTicker WebSocket + Chainlink settlement truth | | dump_detector | Velocity, % move from PTB, chop/ATR filter, regime gate | | lock_engine | Pair cost math, hedge triggers, merge eligibility, expand/rebalance | | inventory_risk | Imbalance, spend caps, circuit breakers, exposure limits | | executor | FOK/FAK/GTC ladder, cancel/replace, idempotent order keys | | settlement | Resolve + redeem winning positions on Polygon | | telemetry | Structured Pino logs, Telegram alerts, SQLite/CSV journal | | paper_mode | Full simulation before live — identical decision logic |

Configuration

Copy .env.example → .env. Every risk and strategy knob is documented and tunable without code changes.

| Variable | Default (5m) | Description | |----------|--------------|-------------| | BTC5MSTATUS | paper | live · paper · monitor · disabled | | LOCKCOSTMAX | 0.985 | Max pair cost to trigger hedge | | DUMPTHRESHOLDBPS | 12 | Min velocity vs PTB to enter | | MAXSPENDPERMARKETUSDC | 120 | Hard cap per window | | MAXTAKERFILL_USDC | 40 | Fixed USD size per action (no martingale) | | STOPBUYINGBEFORECLOSEMS | 90000 | T-90s cutoff for 5m | | MINSIDEPRICE / MAXSIDEPRICE | 0.08 / 0.92 | Avoid toxic tail prices | | COOLDOWNAFTERSINGLEFILLMS | 3000 | Cooldown between fills | | MAXINVENTORYIMBALANCE_USDC | 35 | Max one-sided exposure | | MAXLOSSPERHOURUSDC | 60 | Hourly loss circuit breaker | | KILLSWITCHFILE | .killswitch | File-based kill switch |

Per-profile overrides in config/profiles.yaml. See docs/RUNBOOK.md for the recommended rollout: shadow 5m → live tiny size → enable 15m/1h.

Live Trading Setup

This project is powerful for real trading — not just academic backtests. Paper mode validates the full decision loop; live mode uses the same code path with real CLOB orders.

• Set BTC5MSTATUS=live, MODE=live, CONFIRM_LIVE=true
• Add POLYMARKETPRIVATEKEY and POLYMARKETFUNDERADDRESS
• Fund Polygon wallet with USDC; use a private RPC (POLYGONRPCURL)
• Run npm run doctor — confirm live keys and market discovery pass
• Start with minimum ORDERSIZEUSDC and scale after reviewing session logs

Kill Switch

touch .killswitch   # halt all new entries immediately
rm .killswitch      # resume

Engineering Highlights

Built for production from day one:

• Typed modular architecture — each concern in its own module, Zod-validated config
• Reconnect with exponential backoff on all WebSocket feeds (Binance, CLOB, Chainlink)
• Heartbeat logging with BTC price, PTB delta, phase, PnL every 15s
• Idempotent order handling — deterministic keys per window/direction
• Graceful shutdown — SIGINT/SIGTERM cancels open orders, drains feeds, closes DB
• Structured Pino logs — JSON or pretty mode with [DUMP] / [LOCK] / [SKIP] tags
• SQLite trade journal — fills, merges, events, hourly PnL for post-session analysis
• Risk circuit breakers — hourly/daily loss caps, imbalance limits, stale feed guards
• No martingale — fixed USD size per action, cooldown between fills
• Unit tests — lock math and dump detector covered with Vitest

Contributing — Especially Live Trading

The highest-value contributions come from people running real size on Polymarket BTC markets:

• Live execution hardening — fill rates, partial fills, cancel-on-close, slippage calibration
• Chainlink Data Streams — production oracle wiring vs CEX proxy in paper mode
• Lock timing optimization — when to hedge vs expand vs ride-the-winner
• Multi-TF promotion — 15m/1h enablement criteria from shadow stats
• Redemption automation — post-resolution USDC reclaim on Polygon
• Telegram/Discord alert wiring — session summaries on [DUMP] / [LOCK] events

npm install && npm test && npm run doctor && npm run paper:5m

See GITHUB_ABOUT.md for GitHub repo metadata (description, topics, social preview) when you publish.

SEO Keywords

polymarket trading bot · polymarket bot · polymarket ai trading bot · polymarket ai bot · polymarket trading bot github · polymarket bot github · polymarket copy trading bot · polymarket sniper bot · polymarket arbitrage bot · polymarket market making bot · polymarket llm trading bot · polymarket ai agent · polymarket agent trading · polymarket news trading bot · polymarket automated trading · polymarket algo trading · polymarket trading bot python · polymarket trading bot typescript · polymarket trading bot nodejs · polymarket clob bot · polymarket clob api trading bot · polymarket api trading bot · how to build a polymarket trading bot · best polymarket trading bot · polymarket bot 2026 · polymarket prediction market bot · prediction market trading bot · polymarket whale copy bot · polymarket telegram bot · polymarket autocopy bot · polymarket yes no arbitrage bot · polymarket btc 5 minute bot · polymarket up down bot · polymarket latency arb bot · polymarket fair odds bot · polymarket probability trading bot · polymarket open source trading bot · polymarket bot strategy · polymarket trading bot tutorial · polymarket bot dry run paper trading · polymarket ai news agent · polymarket multi agent trading bot · polymarket sentiment trading bot · build polymarket bot with ai · polymarket automated market maker bot · polymarket orderbook trading bot · polygon polymarket trading bot · LockForge · dump and hedge polymarket · lock profit trading bot · btc up down trading bot · polymarket btc bot

License

MIT — see LICENSE.

LockForge — Polymarket BTC Dump-and-Hedge / Lock-Profit Trading Bot (5m · 15m · 1h)
Built for traders who lock profit, not hope.

⭐ Star the repo · 💬 Open a Discussion · 🔧 Fork and improve · Let's make this more profitable together.