# TradeFinder

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

```bash
# 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

```bash
# 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

```bash
pytest
```

## Manual Setup (Alternative)

If you prefer manual setup:

### With uv (Recommended - 10-100x faster)

```bash
# 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

```bash
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](docs/PLAN.md) - Roadmap & milestones
- [Architecture](docs/ARCHITECTURE.md) - System design
- [Security](docs/SECURITY.md) - API key handling

## License

MIT