Automated crypto trading system for BTC/ETH perpetual futures with regime-adaptive strategy selection, risk management, and full transparency via web UI.

Quick Start

1. Clone and Setup

# Clone the repository
git clone <your-repo-url>
cd TradeFinder

# Run setup (auto-detects uv or uses pip)
chmod +x setup.sh
./setup.sh

# Activate virtual environment
source .venv/bin/activate

2. Configure API Keys

Get testnet API keys from: https://testnet.binancefuture.com

# Edit .env file
nano .env  # or your preferred editor

# Add your keys:
# BINANCE_TESTNET_API_KEY=your_key_here
# BINANCE_TESTNET_SECRET=your_secret_here

3. Run Tests

pytest

Manual Setup (Alternative)

If you prefer manual setup:

With uv (Recommended - 10-100x faster)

# Install uv if not present
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create venv and install
uv venv .venv --python 3.11
uv pip install -e ".[dev]" --python .venv/bin/python

source .venv/bin/activate

With pip

python3.11 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Project Structure

TradeFinder/
├── src/tradefinder/
│   ├── adapters/       # Exchange connectivity
│   │   ├── base.py     # Abstract interface
│   │   ├── binance_usdm.py  # Binance Futures
│   │   └── types.py    # Order, Position types
│   ├── core/           # Core engine
│   │   └── config.py   # Settings management
│   ├── data/           # Market data (TODO)
│   ├── strategies/     # Trading strategies (TODO)
│   └── ui/             # Streamlit dashboard (TODO)
├── tests/              # Test suite
├── docs/               # Documentation
│   ├── PLAN.md         # Project roadmap
│   ├── ARCHITECTURE.md # System design
│   └── SECURITY.md     # Security guidelines
├── setup.sh            # Auto-setup script
├── pyproject.toml      # Project config
├── docker-compose.yml  # Container setup
└── Dockerfile          # Docker build

Features

Implemented

✅ Configuration management (Pydantic settings)
✅ Binance USDⓈ-M Futures adapter
- Hedge mode support
- Isolated margin
- Leverage configuration
- Limit/stop-market orders
✅ Type definitions (Order, Position, etc.)
✅ Docker containerization

Planned

⏳ Data ingestion (OHLCV, funding rates)
⏳ Regime classifier (trend/range/volatility)
⏳ Strategy suite (supertrend, squeeze, mean-rev)
⏳ Risk engine & allocator
⏳ Streamlit UI
⏳ Walk-forward optimization

Trading Scope

Parameter	Value
Exchange	Binance USDⓈ-M Futures
Symbols	BTCUSDT, ETHUSDT
Mode	Hedge (long+short)
Margin	Isolated
Leverage	2x (configurable)
Signal TF	4h
Execution TF	1m

Documentation

Development Plan - Roadmap & milestones
Architecture - System design
Security - API key handling

License

MIT