Skip to content

README.md

Latest commit

 

History

History
136 lines (94 loc) · 4.83 KB

README.md

File metadata and controls

136 lines (94 loc) · 4.83 KB

BTC/USDT Direction Prediction with TTM-Inspired Modeling

This repository documents an experimental machine learning pipeline for predicting the direction of the next 5-minute BTC/USDT candle. The work was inspired by IBM Granite TinyTimeMixer (TTM) research and adapted into a custom binary-classification workflow for crypto intraday data.

The current codebase is best understood as a research and engineering portfolio project:

  • It is inspired by IBM Granite Time Series TTM, not a direct reproduction of the upstream Hugging Face checkpoint workflow.
  • It focuses on next-candle up/down classification rather than pure multi-step forecasting.
  • Included metrics and checkpoints are experiment snapshots, not production trading guarantees.

Portfolio note: a short project narrative is available in docs/portfolio-summary.md.

What This Project Includes

  • Bybit OHLCV data collection into SQLite
  • Feature engineering for 50+ technical indicators
  • A custom TTM-inspired PyTorch model for binary direction prediction
  • Training, evaluation, and hyperparameter search utilities
  • Saved experiment checkpoints for walkthroughs and demos
  • A downstream trading monitor / analysis workflow

Research Framing

The project direction started from the IBM Granite Time Series TTM line of work:

In this repository, that inspiration is translated into a crypto-specific classification pipeline with handcrafted market features, local training utilities, and experimentation around short-horizon BTC/USDT behavior.

Repository Layout

.
├── saved_models/              # Curated experiment checkpoints and notes
├── src/
│   ├── config.json            # Default local project configuration
│   ├── data/                  # Data collection, processing, and feature utilities
│   ├── models/                # Training, evaluation, optimization, model internals
│   └── utils/                 # Config, DB, and logging helpers
├── trader/                    # Monitoring, trading, and trade analysis scripts
├── requirements.txt
└── README.md

Quick Start

1. Install dependencies

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. Add environment variables

Create a local .env file from .env.example and add your Bybit credentials if you plan to use data collection or trading utilities.

cp .env.example .env

3. Review local paths

Default paths are configured in src/config.json to keep all runtime artifacts inside the repository:

  • data/ for SQLite databases
  • models/ for newly trained checkpoints
  • results/ for evaluation outputs
  • logs/ for application logs

4. Collect market data

python -m src.data.data_collector --symbol BTC/USDT --interval 5 --start-date 2024-01-01

5. Build processed features

python -m src.data.data_processor --symbol BTCUSDT --interval 5

6. Train a model

python -m src.models.train_model \
  --symbol BTCUSDT \
  --interval 5 \
  --mode test \
  --samples 5000 \
  --context_length 10 \
  --epochs 15

For a longer run:

python -m src.models.train_model --symbol BTCUSDT --interval 5 --mode full --epochs 150

7. Evaluate a checkpoint

python -m src.models.evaluate_model --symbol BTCUSDT --interval 5 --limit 1000

8. Run the monitoring / trading script

python trader/bt_trader.py --model saved_models/highest_accuracy/model.pth --duration 10

The trading script is best treated as an experimental downstream consumer of the model, not as a production-ready execution system.

Example Experiment Artifacts

Sample checkpoints are documented in saved_models/README.md. They are included to show the progression of experiments and make the repository easier to review, but they should not be interpreted as robust live-trading benchmarks.

Known Limitations

  • The repository is centered on BTC/USDT 5-minute data and is not a general market-agnostic framework.
  • Evaluation currently reflects internal experimental workflows more than strict production-grade validation.
  • Live trading paths require additional safeguards, slippage modeling, and failure handling before real-money use.
  • Some comments and auxiliary notes remain in Korean because the project was developed as a personal research build first.

License

MIT. See LICENSE.

Publish-Friendly Notes

  • Runtime artifacts such as local databases, logs, generated models, and virtual environments are git-ignored.
  • The committed checkpoints under saved_models/ are intentional reference artifacts.