Scope Bot V4 Docs

Warning

This project can run in live trading mode.

Use testnet first.
Start with small size.
Validate your .env before starting.
Monitor the bot while it is running.

Project Layout

Main Bot

price-action.js now acts as the bootstrap and wiring layer for the strategy, broker adapter, state, risk controls, and notifications.

Persistence

mongodb-integration.js handles trades, positions, signals, snapshots, performance stats, and bot state.

Dashboard

Dashboard-server.js, dashboard.html, and dashboard.css provide the monitoring UI.

Validation

Validate-config.js checks credentials, MongoDB, Telegram, and core risk settings before launch.

Requirements

Node.js >=16
npm
MongoDB connection string
Broker API credentials
Optional: Telegram bot token and chat ID

Environment Setup

Create a .env file in the project root.

Minimum Required

BROKER=capitalcom
USE_TESTNET=true

CAPITAL_COM_API_KEY=your_api_key
CAPITAL_COM_IDENTIFIER=your_identifier
CAPITAL_COM_API_PASSWORD=your_api_password
CAPITAL_COM_EPIC=GOLD

MONGODB_URI=your_mongodb_uri
DB_NAME=price_action_bot

Optional But Recommended

SYMBOL=XAUUSDT
TIMEFRAME=15m
LEVERAGE=10
RISK_PCT=1.5
MIN_RR_RATIO=2.5
MAX_DAILY_TRADES=4
ALLOW_SHORTS=true
HTF_BIAS_ENABLED=true

TELEGRAM_TOKEN=your_bot_token
TELEGRAM_CHAT_ID=your_chat_id

DASHBOARD_PORT=3001
WATCH_PAIRS=GOLD,SILVER,US100
LOG_LEVEL=info
TRAILING_STATE_SAVE_DEBOUNCE_MS=15000

Notes

USE_TESTNET=true maps to Capital.com demo mode. Telegram is optional, but strongly recommended for trade alerts and safety notifications.

Quick Start

Create your .env file.
Install dependencies.
Validate config.
Run on testnet first.

npm install
npm run validate
npm run dev

Run Modes

Command	Purpose
`npm start`	Start the trading bot
`npm run dashboard`	Start the dashboard server
`npm run dev`	Run bot and dashboard together
`npm run manage`	Start the management UI
`npm run test-live`	Run the small-size live test harness
`npm run test-live-demo`	Run the demo-mode test harness

Strategy Summary

Candle-close confirmation before entry
Higher-timeframe bias filtering
Weighted confluence scoring
Support and resistance analysis
Volume confirmation
Structure-based stop placement
Partial closes at configurable R multiples
Breakeven stop movement
Trailing stop management
Momentum-based early exit checks

Persistence Model

MongoDB stores the bot's runtime and historical data in dedicated collections:

trades
positions
signals
snapshots
bot_state

Position-changing events are persisted immediately. Background heartbeat and snapshot saves still run on interval. Trailing stop ratchet saves are debounced to reduce MongoDB write load during fast moves.

Safety Controls

Max daily trade limit
Max daily loss percentage
Max drawdown percentage
Emergency per-trade stop logic
Kill switch file support via ./KILL_SWITCH
Exchange position reconciliation on startup and during runtime
Telegram safety alerts

Dashboard

By default the dashboard server runs on:

http://localhost:3001

The dashboard API provides health, current price, watch pairs, account balance, performance metrics, and bot state endpoints.

Deploying To Cloudflare Pages

This documentation is already prepared as a static site in the docs/ folder.

Recommended Cloudflare Pages Settings

Framework preset: None
Build command: leave blank
Build output directory: docs

Deploy Steps

Push this repository to GitHub.
In Cloudflare, create a new Pages project.
Connect the repository.
Set the output directory to docs.
Deploy and share the generated *.pages.dev URL.

Tip

If you later want multi-page docs, search, or versioned documentation, this static page can be replaced with a docs generator without changing the public Cloudflare Pages URL.