Bybit-Predict

Rule-based cryptocurrency market analysis, signal generation, and Discord integration powered by public Bybit V5 market data.

Current release: v4.1.6. This release corrects linear-contract short returns and initial-equity drawdown, and makes live CLI/Discord analysis use completed candles. It builds on the reliability improvements in v4.1.5, PyPI distribution introduced in v4.1.1, and reproducible historical backtesting introduced in v4.1.0; the latest legacy release was v3.1.

正體中文

For backtests created with older versions, rerun with the same preserved CSV/manifest, analysis window, fees, and slippage; keep the original reports for comparison. See the v4.1.6 upgrade notes in CHANGELOG.md.

What Bybit-Predict is — and is not

Bybit-Predict analyzes OHLCV candles from Bybit and produces informational market signals and reference levels. The current legacy-rule-based-v4 strategy uses candle shapes, volume power, percentiles, IQR, and Fibonacci-inspired levels.

It does not use a machine-learning model and it is not a trading bot. It never places orders, asks for Bybit API credentials, or promises a market outcome.

Risk notice: Cryptocurrency markets are volatile. Results are informational only, are not financial advice, and must not be treated as a recommendation or guarantee to trade.

Highlights

• Live analysis uses completed candles: the default 180-candle window normally needs one K-line page, while 1,000 completed candles may need one additional older page.
• Typed, UTC-normalized Candle and immutable PredictionResult models.
• Stateless legacy strategy: concurrent analyses cannot mix their data.
• CLI for local use and an optional non-blocking Discord slash command.
• Active symbols validated using Bybit instrument metadata, not a hard-coded coin list.
• Tests, Ruff, Pyright, GitHub Actions CI, and Dependabot.
• Deterministic historical backtesting with saved CSV inputs, validated dataset manifests, explicit assumptions, performance metrics, and two simple baselines.

Requirements

• Python 3.11 or later
• Internet access to Bybit public market endpoints

No Bybit account, API key, or API secret is needed for public market analysis. The optional Discord interface needs only a Discord bot token.

Install

From PyPI

Install the CLI and its standard Bybit V5 dependency with:

python -m pip install bybit-predict

Install the optional Discord interface when you need it:

python -m pip install "bybit-predict[discord]"

For an isolated command-line installation, use pipx:

pipx install bybit-predict

From source

git clone https://github.com/KageRyo/Bybit-Predict.git
cd Bybit-Predict
uv venv --python 3.11 .venv
source .venv/bin/activate  # Windows: .venv\\Scripts\\activate
uv pip install .

For contributors, install development and optional Discord dependencies:

uv pip install -e ".[dev]"

CLI

Analyze the default 180 four-hour candles:

bybit-predict analyze BTCUSDT

Choose another supported Bybit interval and candle count:

bybit-predict analyze ETHUSDT --interval 60 --limit 240

CLI --limit and Discord candles count completed candles, from 42 to 1,000 (default 180). The active candle is excluded; at its exact UTC interval end it becomes eligible. Minute, daily, and weekly intervals advance from the candle start; monthly candles close at the next UTC calendar month, rather than after a fixed 30 days. A single UTC snapshot is used across requests and retries. If two K-line pages cannot supply the requested window, analysis fails with the requested and available closed counts. There is no open-candle opt-in. The reported data period retains the start timestamps of the first and last analyzed candles.

Example output:

Symbol: BTCUSDT
Strategy: legacy-rule-based-v4 (rule-based, not ML)
Timeframe: 240
Candles: 180
Trend: Bullish
Signal strength: 68.00%

Reference levels:
     0%  ...
  23.6%  ...

The CLI returns a non-zero status for invalid symbols, invalid parameters, or market-data failures. You can also run python -m bybit_predict analyze BTCUSDT.

Backtest a historical range

Backtesting uses a linear-contract model: long gross return is exit / entry - 1, short gross return is 1 - exit / entry, and both use slippage-adjusted prices with the declared per-side fees. Inverse-contract PnL is not modeled. The same calculation applies to strategy trades and the SMA directional baseline.

Maximum drawdown includes starting normalized equity of 1.0 and is reported as a negative or zero return. A first loss to 0.8 followed by recovery to 0.9 therefore still reports −20% drawdown. Public equity-curve points remain post-execution observations.

v4.1.0 adds a reproducible backtest command. It signals from a trailing closed-candle window, executes non-neutral signals at the next candle open, and exits at that candle close. The command prints its assumptions with metrics and baselines; it does not make a trading claim.

bybit-predict backtest BTCUSDT \
  --interval 240 \
  --start 2024-01-01 \
  --end 2025-01-01 \
  --strategy legacy \
  --window 180 \
  --save-data data/btcusdt-2024-4h.csv

Re-run against the saved, normalized CSV without downloading data again:

bybit-predict backtest BTCUSDT \
  --interval 240 \
  --start 2024-01-01 \
  --end 2025-01-01 \
  --strategy legacy \
  --window 180 \
  --data data/btcusdt-2024-4h.csv

--start is inclusive, --end is exclusive, and date-only values mean midnight UTC. See backtesting and evaluation for metric definitions, baseline semantics, manifest validation, reproducibility requirements, and important limitations. Saving a CSV also creates the required <csv-name>.manifest.json sidecar; --data rejects missing, malformed, mismatched, or tampered CSV/manifest pairs before replay. The sidecar contains exactly schema_version, symbol, category, interval, source, requested_start, requested_end, generated_at, and content_sha256 (schema 1, source Bybit V5). The report labels the public directional_accuracy field as close-to-close directional accuracy: it compares the signal candle close with the next candle close, not the next candle's open-to-close return. An adverse gap can therefore make this metric correct while the simulated trade loses money; use win rate and return metrics for execution outcomes. CLI dataset paths must resolve under the current working directory: the documented data/<file> form works, while .. traversal, paths outside that root, and symlink components are rejected before a backtest runs. The CLI also requires regular CSV and manifest files: existing hard-linked outputs and special files such as FIFOs are rejected without blocking.

Discord slash commands

Install the Discord optional dependency, create a Discord application/bot, and invite it with the bot and applications.commands scopes.

python -m pip install ".[discord]"
cp .env.example .env

Set environment variables securely (for example by sourcing .env locally or using your deployment secret manager):

export DISCORD_BOT_TOKEN="your-token"
# Optional: immediately sync commands to one development guild.
export DISCORD_GUILD_ID="your-development-guild-id"

Then start the interface:

bybit-predict discord

Use the slash command in Discord:

/predict symbol:BTCUSDT interval:240 candles:180

The command defers external market work to a thread, so a slow Bybit request does not block Discord's event loop. Responses include the strategy, trend, signal strength, candle period, and neutral reference levels rather than trading instructions.

Never commit .env, bot tokens, API keys, or downloaded data. They are ignored by default.

Configuration

Variable	Required	Purpose
DISCORD_BOT_TOKEN	Discord only	Discord bot authentication token.
DISCORD_GUILD_ID	No	Development guild for immediate command syncing.
BYBIT_TESTNET	No	true opts into Bybit testnet public data; default is false.

The market-data client intentionally exposes no Bybit credential settings: public K-line and instrument endpoints do not require authentication.

Architecture

Bybit V5 public API
        │
BybitV5MarketClient ──→ normalized UTC Candles
        │
        ├── PredictionService ──→ LegacyRuleBasedStrategy ──→ PredictionResult
        │         │                         │
        │         ├──────── CLI             └── future strategies
        │         └──────── Discord slash command
        │
        └── BacktestEngine ─────→ LegacyRuleBasedStrategy ──→ BacktestResult
                  │
                  ├──────── historical CLI
                  └──────── saved CSV input/output

• market/ owns Bybit V5 requests, retry boundaries, pagination, and response normalization.
• strategies/ contains pure, deterministic signal calculations and has no dependency on Bybit or Discord.
• services/ composes market data with a strategy.
• interfaces/ converts user input/output only.

Strategy and evaluation

LegacyRuleBasedStrategy is deliberately retained as the project’s historical core. It classifies candle bodies and wicks, compares significant bullish and bearish volume, and derives optional reference prices from IQR and percentile calculations. It is explicitly named so later strategies can be compared fairly. v4 intentionally fixes v3's zero/six-candle volume window, timezone handling, and bearish Fibonacci label ordering; the exact compatibility baseline and retained semantics are documented in legacy strategy migration notes.

The v4.1.0 backtesting work (#25) defines a fixed trailing analysis window, next-open entry, same-candle-close exit, and neutral-as-cash behavior before calculating close-to-close directional accuracy, win rate, average return, maximum drawdown, and a zero-risk-rate Sharpe ratio. It compares the result with buy-and-hold and a 10/20 SMA directional baseline. See backtesting and evaluation for the exact rules and limitations. Until published results are independently interpreted in context, this project makes no claim that its signals predict future prices.

Development and quality checks

ruff check .
ruff format --check .
pyright
pytest

pytest fails when total coverage falls below the 80% floor (the current baseline is approximately 84%). Pyright remains in basic mode but now treats missing imports as errors; the development extra installs the dependencies needed by the checks.

Pull requests run these checks on Python 3.11, 3.12, and 3.13. See CONTRIBUTING.md for local setup and the required feature/<issue>-<description> branch convention.

Publishing

Pushing a final release tag builds an sdist and universal wheel, validates them, publishes through PyPI Trusted Publishing, then creates a GitHub Release with the same artifacts. See PyPI publishing for the maintainer-only setup and release procedure. No long-lived PyPI API token is stored in this repository or its GitHub Actions secrets.

Release history and roadmap

• v4.0.0: package architecture, public Bybit V5 client, stateless legacy strategy, CLI, Discord slash command, configuration, quality gates, and documentation.
• v4.1.0: reproducible backtesting and evaluation (#25).
• v4.1.1: PyPI distribution, Trusted Publishing, and package-release automation (#37).
• v4.1.2: documentation and PyPI metadata corrections (#40).
• v4.1.3: CI dependency maintenance and restoration of the complete GPL v2 license text.
• v4.1.4: standard GPL v2 distribution license, recognised by GitHub as GPL-2.0.
• v4.1.5: candle and API robustness, interval and dataset replay validation, linear SMA baseline computation, explicit metric semantics, enforced quality gates, and protected-main governance.
• v4.1.6: corrected linear short returns and initial-equity drawdown, plus completed-candle live analysis with bounded pagination (#64–#66).
• Later: additional strategies may implement the same strategy contract; ML is a future option, not an implied feature.

Contributing and history

The repository name, issues, forks, stars, merged pull requests, and Git history are intentionally preserved. Thanks to prior contributors, including RRAaru. New contributors are welcome—start with good first issues or read CONTRIBUTING.md.

License and copyright

Bybit-Predict is licensed under the GNU General Public License v2.0 or later.

Copyright © 2022–2026 CodeRyo Studio, Chien-Hsun Chang, and contributors. CodeRyo Studio is the project maintainer. See NOTICE for the complete attribution notice.