btc-trading/README.md

BTC Trading Dashboard

A Bitcoin trading dashboard with FastAPI backend, PostgreSQL database, and technical analysis features.

Architecture

• Backend: FastAPI (Python)
• Frontend: HTML/JS dashboard with lightweight-charts
• Database: PostgreSQL (connects to NAS)
• Features:
  • Real-time candle data
  • Technical indicators (SMA, EMA, RSI, MACD, Bollinger Bands, etc.)
  • Trading strategy simulation
  • Backtesting

Prerequisites

• Python 3.9+
• PostgreSQL database (on NAS at 20.20.20.20:5433)

Setup

1. Virtual Environment

python -m venv venv

2. Install Dependencies

venv\Scripts\activate
pip install -r requirements.txt

3. Configure Database

Edit .env file:

DB_HOST=20.20.20.20
DB_PORT=5433
DB_NAME=btc_data
DB_USER=btc_bot
DB_PASSWORD=your_password

4. Test Database Connection

python test_db.py

Running the Server

Quick Start

Windows:

start_dev.cmd

Linux/Mac:

chmod +x start_dev.sh
./start_dev.sh

Manual Start

venv\Scripts\activate
uvicorn src.api.server:app --reload --host 0.0.0.0 --port 8000

Access the Application

Once the server is running:

• Dashboard: http://localhost:8000/dashboard
• API Docs: http://localhost:8000/docs
• Health Check: http://localhost:8000/api/v1/health

Project Structure

.
├── config/
│   └── data_config.yaml       # Data collection configuration
├── src/
│   ├── api/
│   │   ├── server.py          # FastAPI application
│   │   └── dashboard/         # Frontend static files
│   ├── data_collector/        # Data collection modules
│   │   ├── main.py            # Data collector service
│   │   ├── database.py        # Database manager
│   │   ├── websocket_client.py # WebSocket client
│   │   ├── indicator_engine.py # Technical indicators
│   │   ├── brain.py           # Trading logic
│   │   └── backtester.py      # Backtesting engine
│   └── strategies/            # Trading strategies
│       ├── base.py           # Base strategy class
│       └── ma_strategy.py    # Moving average strategy
├── .env                       # Environment variables
├── requirements.txt           # Python dependencies
└── test_db.py                # Database connection test

API Endpoints

Endpoint	Method	Description
/	GET	API info
/api/v1/health	GET	System health check
/api/v1/candles	GET	Get candle data
/api/v1/strategies	GET	List available strategies
/api/v1/ta	GET	Technical analysis
/api/v1/stats	GET	Trading statistics
/api/v1/backtests	POST	Trigger backtest

Development Tips

1. Auto-reload: The server reloads automatically when Python files change
2. Database changes: Restart server to pick up schema changes
3. Frontend: Edit HTML/JS in src/api/dashboard/static/
4. Indicators: Add new indicators in src/api/dashboard/static/js/indicators/
5. Strategies: Create strategies in src/strategies/

Troubleshooting

Port 8000 already in use

netstat -ano | findstr :8000
taskkill /PID <PID> /F

Database connection failed

1. Check NAS is reachable: ping 20.20.20.20
2. Verify PostgreSQL is running on NAS
3. Check .env credentials
4. Run python test_db.py for diagnosis

No data in dashboard

1. Verify data collector is running on NAS
2. Check database has candles table
3. Use API docs to query data manually