Add core infrastructure: config, Binance adapter, docs, and auto-setup

- Add Pydantic settings with trading mode validation (paper/testnet/live) - Implement Binance USDⓈ-M Futures adapter with hedge mode, isolated margin - Add type definitions for orders, positions, and market data - Create documentation (PLAN.md, ARCHITECTURE.md, SECURITY.md) - Add setup.sh with uv/pip auto-detection for consistent dev environments - Configure Docker multi-stage build and docker-compose services - Add pyproject.toml with all dependencies and tool configs
2025-12-27 13:28:08 +04:00
parent f1f9888f6b
commit 6f602c0d19
22 changed files with 3396 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,131 @@
+# 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