A bellwether is the lead animal whose movement signals where the flock heads next — the original leading indicator. Bellwether is a regime-adaptive, ensemble trading-signal engine for the terminal: it turns real market data (stocks and crypto) into actionable
BUY/SELL/HOLDcalls with a transparent, weighted vote behind every decision — rendered as a beautiful live dashboard.
🐏 BELLWETHER v0.2.0 ● ACTIVE SOURCE: coinex/15m EQUITY: $100,000.00 DAILY P&L: +0.00%
╭──────────┬─────────────┬──────────────────────┬──────────┬─────────────┬──────────────┬────────╮
│ Ticker │ Price │ Regime │ Signal │ Score │ Conv. │ Size │
├──────────┼─────────────┼──────────────────────┼──────────┼─────────────┼──────────────┼────────┤
│ BTCUSDT │ $65,910.00 │ Steady Down-Trend │ ▼ SELL │ ▱▱▱▰▰│▱▱▱▱▱ │ ██████░░ 62% │ 1.5172 │
│ ETHUSDT │ $1,828.83 │ Aggressive Down-Trend│ ■ HOLD │ ▱▱▱▱▰│▱▱▱▱▱ │ ███░░░░░ 33% │ 0 │
╰──────────┴─────────────┴──────────────────────┴──────────┴─────────────┴──────────────┴────────╯
BTCUSDT $65,910.00 score -0.37
Trend Ensemble (Supertrend×3 + MACD + EMA + Donchian)
Supertrend -1.00 3x Supertrend ALL down ORDER SELL
Donchian -0.34 Donchian mid-range (22%) ENTRY $65,910.00
RSI -0.34 RSI 40 (trend-confirm) STOP $66,574.83
... TARGET $64,912.76
git clone https://github.com/mightbeanshuu/bellwether && cd bellwether
./install.sh # creates a venv, installs everything, adds a `bellwether` launcher
bellwether # instant live crypto scan 🚀Then it's just:
bellwether # default: scan top crypto on CoinEx
bellwether live # LIVE dashboard: real-time WebSocket prices + ensemble signals
bellwether live --tick 0.01 # repaint every 10ms off the live WebSocket feed
bellwether scan --source coinex BTCUSDT ETHUSDT SOLUSDT
bellwether scan --source yahoo NVDA AAPL MSFT SPY # stocks
bellwether scan --apply BTCUSDT # apply signals to the paper portfolio
bellwether status # inspect the paper book
bellwether reset --capital 250000bellwether auth login # paste a READ-ONLY (VIEW) API key + secret
bellwether account # show real balances + open positions
bellwether scan --account # dashboard equity reflects your real futures balance
bellwether auth logoutCredentials live in env vars (COINEX_ACCESS_ID / COINEX_SECRET_KEY) or
~/.bellwether/credentials.json (chmod 600, gitignored). Requests are signed
with HMAC-SHA256 per CoinEx v2.
Safety boundary: Bellwether's account access is read-only — it can view balances/positions but cannot place, modify, or cancel orders. Live order execution is deliberately not wired in; it would be a separate, explicit opt-in. Use a key with VIEW permission only.
bellwether live opens a persistent CoinEx WebSocket and the exchange pushes
state.update ticks as the market moves — so prices are millisecond-fresh
without hammering REST. The dashboard reads the latest in-memory price each
frame, so --tick 0.01 repaints at ~10ms with no per-frame network cost. Stocks
(--source yahoo) fall back to REST polling.
| Source | What | Symbols |
|---|---|---|
coinex (default) |
CoinEx USDT-perpetual futures | BTCUSDT, ETHUSDT, … |
coinex-spot |
CoinEx spot | BTCUSDT, … |
yahoo |
Equities / ETFs (yfinance) | NVDA, SPY, … |
If a feed is empty, too short, stale, or has NaNs in the latest bar, Bellwether
raises a DataGap, marks the asset DATA_GAP, and skips it — it never
guesses a price. This is research/education tooling, not financial advice,
and it emits signals + a paper ledger only (no broker, no real orders).
Inspired by the patterns in the most-starred open-source bots — notably
freqtrade's multi-Supertrend
confluence and the voting/stacked-confirmation approach catalogued in
awesome-systematic-trading
and best-of-algorithmic-trading —
Bellwether doesn't trust a lone crossover. It runs a panel of voters, each
casting a signed vote in [-1, +1], then blends them with regime-aware
weights into one net score:
| Voter | Idea | Heaviest in |
|---|---|---|
| Supertrend ×3 | 3 ATR settings must agree (freqtrade-style confluence) | trends |
| MACD | histogram sign + momentum | trends |
| EMA-20/50 | convergence/spread | trends |
| Donchian | 20-bar breakout (Turtle) | breakouts |
| Bollinger %B | mean reversion at the bands | ranges |
| Stochastic | oversold/overbought reversion | ranges |
| RSI | trend-confirm in trends, fade extremes in ranges | both |
The regime (ADX → trend strength, ATR% → volatility, EMA → direction)
re-weights the panel, so the engine leans on Supertrend/MACD/EMA/Donchian when
trending and Bollinger/Stochastic/RSI when ranging. A trade only fires when the
net score clears a ±0.25 no-trade band; conviction scales with |score|.
Volatility-adjusted position sizing:
size = (capital × risk_ratio) / |entry − stop|
risk_ratio (base 1.5%) scales down as ATR% rises above a 2% reference
and is floored at 0.5% — smaller bets into violent tape. Sizing supports
fractional lots (e.g. BTC) and never exceeds account equity (no leverage).
Stops/targets are ATR multiples so they breathe with each asset.
Circuit breaker: if mark-to-market daily P&L breaches −2%, the engine
flags CIRCUIT BREAKER TRIGGERED, freezes all new BUYs for the session, and
allows only SELL/HOLD.
pip install pytest && pytest -q # 15 offline tests (indicators, risk, strategy)bellwether/
data.py # pluggable real OHLCV (yahoo / coinex) + DataGap gating
indicators.py # SMA/EMA, ATR, RSI, MACD, Bollinger, Stochastic, Donchian, Supertrend, ADX
regime.py # market-regime classification
strategy.py # regime-gated ensemble voting engine
risk.py # volatility-adjusted sizing + circuit breaker
portfolio.py # JSON-persisted paper ledger
dashboard.py # rich terminal UI
engine.py # scan orchestration -> structured ScanResult
cli.py # argparse CLI (scan / live / status / reset)
install.sh # one-command venv + launcher install
tests/ # offline unit tests
MIT