# TradingBinance — Plataforma de Trading Algorítmico

> **Disclaimer legal:** Este sistema opera con probabilidades y gestión de riesgo estructurada. **NO garantiza ganancias** ni predice el mercado con certeza. El trading de criptomonedas conlleva riesgo significativo de pérdida de capital. Use bajo su propia responsabilidad.

Plataforma cloud para trading automático de criptomonedas con Binance, diseñada para iniciar en **TESTNET/PAPER TRADING** y solo activar producción tras pruebas estrictas.

## Características

- Conexión Binance Testnet con WebSocket + REST
- 13+ indicadores técnicos (SMA, EMA, RSI, MACD, Bollinger, ATR, VWAP, Stochastic, ADX, etc.)
- Fórmulas estadísticas (Sharpe, Sortino, Kelly, Z-score, drawdown, etc.)
- 5 estrategias configurables + ensemble con score 0-100
- Gestión de riesgo obligatoria (SL/TP, límites diarios, bloqueo automático)
- Backtesting con comisiones y slippage
- Paper trading interno
- Dashboard React con kill switch
- Workers Celery para mercado, estrategias y órdenes
- Notificaciones Email/Telegram
- JWT + roles (admin, analyst, viewer)
- CI/CD con GitHub Actions

## Arquitectura

Ver documentación completa en [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) y modelo DB en [`docs/DATABASE.md`](docs/DATABASE.md).

## Requisitos

- Docker & Docker Compose
- Python 3.11–3.12 (desarrollo local recomendado; usar Docker si tienes Python 3.14)
- Node.js 20+ (frontend local)
- Cuenta Binance Testnet: https://testnet.binance.vision/

## Inicio rápido (Docker)

### 1. Clonar y configurar

```bash
cd tradingbinance
cp .env.example .env
```

Editar `.env`:
- `SECRET_KEY`: cadena aleatoria de 32+ caracteres
- `BINANCE_API_KEY` y `BINANCE_API_SECRET`: keys de testnet
- Confirmar `TRADING_MODE=testnet`
- Mantener `ALLOW_PRODUCTION_TRADING=false` hasta completar Go/No-Go, canary, 2FA y aprobación manual

### 2. Levantar servicios

```bash
docker-compose up -d
```

Servicios:
| Servicio | Puerto | Descripción |
|----------|--------|-------------|
| API | 8000 | FastAPI backend |
| Frontend | 5173 | Dashboard React |
| PostgreSQL | 5432 | Base de datos |
| Redis | 6379 | Cache y colas |

### 3. Inicializar base de datos

```bash
docker-compose exec api python scripts/seed.py
```

Credenciales admin por defecto:
- Email: `admin@trading.local`
- Password: `Admin123!Change` (cambiar inmediatamente)

### 4. Acceder

- **Dashboard:** http://localhost:5173
- **API Docs:** http://localhost:8000/docs
- **Métricas Prometheus:** http://localhost:8000/metrics
- **Health:** http://localhost:8000/api/v1/health

## Desarrollo local (sin Docker)

### Backend

```bash
cd backend
python -m venv venv
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

pip install -r requirements.txt
cp ../.env.example ../.env
# Editar .env con DATABASE_URL apuntando a PostgreSQL local

python scripts/seed.py
uvicorn app.main:app --reload --port 8000
```

### Workers Celery

```bash
# Terminal 2
celery -A app.workers.celery_app.celery_app worker --loglevel=info

# Terminal 3
celery -A app.workers.celery_app.celery_app beat --loglevel=info
```

### Frontend

```bash
cd frontend
npm install
npm run dev
```

## Tests

```bash
cd backend
pytest tests/ -v --cov=app
```

## Postman

Importar colección: [`postman/TradingBinance.postman_collection.json`](postman/TradingBinance.postman_collection.json)

## Flujo de activación

```
TESTNET (default) → PAPER TRADING (30+ días) → PRODUCCIÓN (manual)
```

| Fase | Descripción |
|------|-------------|
| Testnet | Órdenes en Binance Testnet, capital ficticio del exchange |
| Paper | Simulación interna, compara precio esperado vs real |
| Producción | Solo tras backtest positivo + 30 días paper + aprobación admin |

## Configuración de riesgo

| Parámetro | Default | Variable env |
|-----------|---------|--------------|
| Riesgo por operación | 0.75% | `MAX_RISK_PER_TRADE_PCT` |
| Pérdida máxima diaria | 2.5% | `MAX_DAILY_LOSS_PCT` |
| Max trades/día | 10 | `MAX_TRADES_PER_DAY` |
| Confianza mínima BUY | 75 | `MIN_CONFIDENCE_BUY` |
| Kelly cap | 0.25 | `KELLY_CAP` |

## Estrategias

1. **Trend Following** — EMA crossover + RSI + ADX + volumen
2. **Mean Reversion** — Bollinger + RSI oversold
3. **Breakout** — Resistencia + volumen + ATR stop
4. **Conservative Scalping** — Spread bajo, volatilidad controlada
5. **Ensemble** — Score ponderado de estrategias 1-4

## Seguridad

- API keys nunca en código — usar `.env` o AWS Secrets Manager
- Permisos Binance: lectura + trading; **retiros desactivados**
- Órdenes reales de producción bloqueadas por defecto con `ALLOW_PRODUCTION_TRADING=false`
- Kill switch via dashboard o API
- 2FA TOTP para acciones críticas: rearmar circuit breaker, reconciliar, cambiar riesgo y emergency stop
- Cada decisión queda registrada en `decision_logs`
- Rate limiting en API y respeto a límites Binance

## Despliegue cloud

Ver [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) para instrucciones AWS/Azure/GCP.

## Estructura del proyecto

```
tradingbinance/
├── backend/           # FastAPI + Celery + servicios
│   ├── app/
│   │   ├── api/       # Endpoints REST
│   │   ├── core/      # Config, security, DB
│   │   ├── models/    # SQLAlchemy models
│   │   ├── schemas/   # Pydantic validation
│   │   ├── services/  # Binance, indicadores, estrategias, riesgo
│   │   └── workers/   # Celery tasks
│   ├── tests/
│   └── scripts/
├── frontend/          # Dashboard React
├── docs/              # Arquitectura, DB, deploy
├── postman/           # Colección API
└── docker-compose.yml
```

## Extensiones 16–30

Documentación detallada en [`docs/EXTENSIONS.md`](docs/EXTENSIONS.md):

| Sección | Módulo | Estado |
|---------|--------|--------|
| 16 Datos históricos | `market_data_service` | ✅ |
| 17 Filtros Binance | `exchange_filters_service` | ✅ |
| 18 FSM órdenes | `order_state_machine` + `order_events` | ✅ |
| 19 Régimen mercado | `regime_classifier` | ✅ |
| 20 Backtest avanzado | `advanced_backtesting` | ✅ |
| 21 Go/No-Go | `go_no_go` + `/operations/go-no-go` | ✅ |
| 22 Transición prod | `docs/TRANSITION_PLAN.md` | ✅ |
| 23 Exposición/correlación | `exposure_service` | ✅ |
| 24 Idempotencia | `core/idempotency` | ✅ |
| 25 Circuit breakers | `circuit_breaker` + `scripts/watchdog.py` | ✅ |
| 26 Observabilidad | `core/metrics.py` | ✅ Parcial |
| 27 Versionado | `strategy_versions` + `config_history` | ✅ |
| 28 Seguridad ampliada | 2FA TOTP + documentación | ✅ Parcial |
| 29 Operación | `docs/RUNBOOK.md` | ✅ |
| 30 Legal/fiscal | Export CSV `/operations/reports/tax-export` | ✅ |

### Nuevos endpoints

- `GET /api/v1/operations/circuit-breaker`
- `POST /api/v1/operations/circuit-breaker/reset`
- `POST /api/v1/operations/reconcile`
- `GET /api/v1/operations/go-no-go`
- `GET /api/v1/operations/audit`
- `GET /api/v1/operations/reports/tax-export`

### Watchdog

```bash
docker-compose exec api python scripts/watchdog.py
```

### 2FA para acciones críticas

Después de iniciar sesión, configura un autenticador compatible con TOTP:

```bash
POST /api/v1/auth/2fa/setup
POST /api/v1/auth/2fa/enable?code=123456
```

Las operaciones críticas deben enviar:

```text
X-TOTP-Code: 123456
```

Aplica a rearmar circuit breaker, reconciliación manual, Go/No-Go, export fiscal, emergency stop y cambios de riesgo.
Cada acción crítica queda registrada en `audit_logs` con actor, IP, user-agent y valores anteriores/nuevos cuando aplica.

## Roadmap por fases

| Fase | Semanas | Estado |
|------|---------|--------|
| 1 Fundación | 1–2 | ✅ |
| 2 Motor y riesgo | 3–4 | ✅ |
| 3 Backtesting | 5–6 | ✅ |
| 4 Operación | 7–8 | ✅ Parcial |
| 5 Endurecimiento | 9–10 | 🔄 Pendiente |

## Licencia

Uso privado. No redistribuir sin autorización.

**Aviso legal:** Las ganancias en criptomonedas pueden ser gravables ante la DIAN (Colombia). Este software no constituye asesoramiento financiero ni fiscal.