BTC Sentinel

Multi-strategy Bitcoin trading system with institutional-style risk controls. Paper trade first, validate on testnet, then run live on Binance or Coinbase — with a real-time dashboard, Telegram/Discord alerts, and full auditability.

---

For Traders

• Paper by default — No real orders until you switch to testnet or live. Your keys never leave your machine.
• Binance & Coinbase — Connect via API key + secret. Optional Binance Testnet for risk-free rehearsal.
• Five strategies in one engine — Trend, Momentum, Mean Reversion, Grid/DCA, and experimental Market Maker. Combine them with configurable weights and regime awareness.
• Risk first — Per-strategy caps (size, concurrent trades, ATR), plus global circuit breaker (max daily loss, max drawdown, max exposure). Manual reset required after a breach.
• Entry/exit alerts — Telegram and Discord notifications for fills and exits by default; optional signal-level noise.
• Backtest before you risk capital — Run 6-month simulations from the dashboard; tune fees, slippage, and strategy mix.

---

Features

Area	What you get
Dashboard	Live price, 24h change, regime, signals, portfolio value, open positions, win rate, profit factor, drawdown
Strategies	Trend (MA + ATR), Momentum (RSI/breakout), Mean Reversion (Bollinger), Grid/DCA, Market Maker (experimental)
Risk	Max equity per trade, max concurrent trades, break-even and trailing stops, multi-target TPs
Execution	Paper (default), Binance Spot (mainnet/testnet), Coinbase Exchange; market orders with configurable fees/slippage in backtest
Alerts	Entry/exit messages (size, stop, targets); optional signal/regime spam; multi-channel Telegram/Discord
Data	SQLite by default; optional Postgres for multi-instance or scaling

---

Quick start

Prerequisites

• Python 3.11+
• Node.js 18+ (for the dashboard)

1. Backend

Create a .env in the project root (or export in shell):

Variable	Required	Description
API_KEY	Yes	Shared secret for API/dashboard access
CAPITAL_USD	No	Paper starting capital (default 10000)
LIVE	No	Set to true for live/testnet exchange
EXCHANGE	No	binance or coinbase when LIVE=true
EXCH_API_KEY	When live	Exchange API key
EXCH_API_SECRET	When live	Exchange API secret
EXCH_SANDBOX	No	true = Binance Testnet; false = mainnet
NOTIFY_MODE	No	entry_exit (default) or signals
POSTGRES_DSN	No	Postgres connection string if not using SQLite

Start the API:

uvicorn btc_sentinel.api.app:app --host 0.0.0.0 --port 8000

Health check: open http://localhost:8000/health — should return {"ok": true}.

2. Dashboard (frontend)

In frontend/:

# Copy env and set your API key and backend URL
cp .env.example .env
# Edit .env: VITE_API_URL=http://localhost:8000, VITE_API_KEY=your_api_key

npm install
npm run dev

Open http://localhost:5173 and log in with your API_KEY (or use the app’s auth flow).

3. Going live safely

1. Run in paper mode (default) — no LIVE or EXCHANGE needed.
2. Use Binance Testnet with EXCH_SANDBOX=true and testnet keys — see TESTNET_RUNBOOK.md.
3. When ready, set LIVE=true, EXCHANGE=binance (or coinbase), and mainnet API key/secret. Prefer API keys with trading only, no withdrawal rights.

---

Notifications

• Telegram: set TELEGRAM_BOT_TOKEN and optionally TELEGRAM_CHAT_ID; or register channels via Settings/API.
• Discord: set DISCORD_WEBHOOK_URL or add webhooks via Settings/API.
• Modes: NOTIFY_MODE=entry_exit (default) sends entry/exit alerts; signals adds signal/regime updates.

Endpoints (with X-API-Key if API_KEY is set):

• GET /channels, POST /channels/add — manage channels
• POST /notify/test, POST /notify/preview — test and preview messages

---

API overview

All protected routes require header X-API-Key: <API_KEY> (or valid session).

Use case	Endpoints
Status & market	GET /status, GET /regime, GET /history
Portfolio & account	GET /portfolio, GET /account/balance, GET /account/deposits
Trading & config	GET /strategies, POST /config/update, POST /config/reset, GET /exchange/status, POST /exchange/apply
Risk	GET /config, POST /risk/global/update, POST /emergency/close-all
Performance	GET /trades, GET /metrics, GET /metrics/detail, GET /trades/export
Backtest	GET /backtest/run, GET /backtest/full, GET /backtest/config, POST /backtest/config
Alerts	GET /channels, POST /channels/add, GET /alerts/prefs, POST /alerts/prefs

---

Security and safety

• Non-custodial — The bot submits orders via your exchange API; it does not hold funds.
• Secrets in env only — No API keys or secrets in config files or the repo.
• Audit — Order and API audit logs can be stored in your database.
• Your responsibility — Trading involves risk. Use paper and testnet first; restrict exchange API keys to trading and trusted IPs where possible.

---

License

Proprietary. Contact for commercial licensing or custom integrations.