From 9e0d9b88f9f6a3d3dadc96c4d2ca2b2d1126ffb9 Mon Sep 17 00:00:00 2001 From: mindesbunister Date: Fri, 24 Oct 2025 14:36:05 +0200 Subject: [PATCH] docs: Update README with Docker deployment and web interface details - Added Docker deployment section with architecture details - Documented web interface (/settings) features - Added API endpoint examples for all operations - Updated Phase 3 status to COMPLETE - Added settings management API documentation - Included Docker commands and container details - Updated file structure to reflect current layout --- README.md | 269 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 212 insertions(+), 57 deletions(-) diff --git a/README.md b/README.md index 74cb590..64aa0a4 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ |-------|--------|-------------| | Phase 1 | ✅ **COMPLETE** | Trade execution from TradingView signals | | Phase 2 | ✅ **COMPLETE** | Real-time monitoring & automatic exits | -| Phase 3 | 🚧 **PLANNED** | Database, risk manager, notifications | +| Phase 3 | ✅ **COMPLETE** | Web UI, settings management, Docker deployment | ## What It Does @@ -17,46 +17,66 @@ 3. **Monitors prices** in real-time via Pyth Network 4. **Closes positions** automatically at TP1/TP2/SL 5. **Adjusts stops** dynamically (breakeven, profit lock) +6. **Provides web UI** for configuration and monitoring **100% autonomous. No manual intervention required!** -## Quick Start +## Quick Start (Docker) -### 1. Install Phase 2 +### 1. Deploy with Docker Compose ```bash -# From project root -./install-phase2.sh +# Build and start +docker compose up -d + +# View logs +docker compose logs -f trading-bot + +# Stop +docker compose down ``` -### 2. Configure +### 2. Access Web Interface +- **Settings UI:** `http://YOUR_HOST:3001/settings` +- **API Endpoints:** `http://YOUR_HOST:3001/api/` + +### 3. Configure Settings +Open `http://YOUR_HOST:3001/settings` in your browser to: +- Adjust position size and leverage +- Set stop-loss and take-profit levels +- Configure dynamic stop-loss triggers +- Set daily loss limits +- Toggle DRY_RUN mode + +### 4. Setup n8n Workflow +Import `n8n-complete-workflow.json` into your n8n instance and configure TradingView alerts. + +## Alternative: Manual Setup + +### 1. Install Dependencies ```bash -# Edit .env.local -DRIFT_WALLET_PRIVATE_KEY=your_base58_key +npm install +``` + +### 2. Configure Environment +```bash +# Copy and edit .env +cp .env.example .env + +# Required variables: +DRIFT_WALLET_PRIVATE_KEY=[your_wallet_array] SOLANA_RPC_URL=https://mainnet.helius-rpc.com/?api-key=YOUR_KEY -API_KEY=your_random_secret_key +API_SECRET_KEY=your_random_secret_key +DRY_RUN=false ``` -### 3. Test +### 3. Run ```bash -cd v4 - -# Test price monitoring (safe) -npx tsx test-price-monitor.ts - -# Test position manager (safe) -npx tsx test-position-manager.ts - -# Test full flow (REAL TRADE - use small size!) -npx tsx test-full-flow.ts -``` - -### 4. Trade -```bash -# Start server +# Development npm run dev -# Configure TradingView alerts → n8n webhook -# Bot handles everything automatically! +# Production +npm run build +npm start ``` --- @@ -65,7 +85,7 @@ npm run dev ### Phase 1: Trade Execution ✅ - Drift Protocol integration -- Market order execution +- Market order execution - TradingView signal normalization - n8n webhook endpoint - Risk validation API @@ -78,49 +98,184 @@ npm run dev - **Multi-position** support - **Real-time P&L** tracking -### Phase 3: Coming Soon 🚧 -- Database persistence (PostgreSQL/Prisma) -- Advanced risk manager -- Trade history & analytics -- Enhanced notifications -- Web dashboard +### Phase 3: Production Ready ✅ +- **Web UI** for settings management +- **Docker deployment** with multi-stage builds +- **REST API** for all operations +- **Risk calculator** with live preview +- **Settings persistence** to .env file +- **PostgreSQL** integration ready + +--- + +## Web Interface + +### Settings Page (`/settings`) +Beautiful web interface for managing all trading parameters: + +**Position Sizing:** +- Adjust position size ($10-$10,000 USD) +- Set leverage (1x-20x) + +**Risk Management:** +- Stop-loss percentage +- Take-profit 1 & 2 levels +- Emergency stop level + +**Dynamic Stop-Loss:** +- Breakeven trigger +- Profit lock trigger and amount + +**Safety Limits:** +- Max daily loss +- Max trades per hour +- Cooldown between trades + +**Execution:** +- Slippage tolerance +- DRY_RUN toggle for testing + +**Live Risk Calculator:** +- Shows max loss in USD +- TP1 and TP2 gains +- Risk/Reward ratio + +### API Endpoints + +All endpoints require `Authorization: Bearer YOUR_API_SECRET_KEY` + +**Trade Execution:** +```bash +# Execute a trade +POST /api/trading/execute +{ + "symbol": "SOL-PERP", + "direction": "long", + "timeframe": "5", + "signalStrength": "strong" +} + +# Close a position +POST /api/trading/close +{ + "symbol": "SOL-PERP", + "percentToClose": 100 +} + +# Get active positions +GET /api/trading/positions + +# Validate trade (risk check) +POST /api/trading/check-risk +{ + "symbol": "SOL-PERP", + "direction": "long" +} +``` + +**Settings Management:** +```bash +# Get current settings +GET /api/settings + +# Update settings +POST /api/settings +{ + "MAX_POSITION_SIZE_USD": 100, + "LEVERAGE": 5, + "STOP_LOSS_PERCENT": -1.5, + ... +} +``` + +--- + +## Docker Deployment + +### Architecture +- **Multi-stage build** for optimized image size +- **Next.js standalone** output for production +- **PostgreSQL** for trade history +- **Isolated network** (172.28.0.0/16) +- **Health monitoring** and logging + +### Container Details +- **Port:** 3001 (external) → 3000 (internal) +- **Image:** Node 20 Alpine +- **Size:** ~400MB (optimized) +- **Restart:** unless-stopped + +### Commands +```bash +# Build image +docker compose build trading-bot + +# Start services +docker compose up -d + +# View logs +docker compose logs -f trading-bot + +# Restart after config changes +docker compose restart trading-bot + +# Stop everything +docker compose down +``` + +### Environment Variables +All settings are configured via `.env` file: +- Drift wallet credentials +- Solana RPC endpoint (Helius recommended) +- Trading parameters (size, leverage, SL, TP) +- Risk limits and safety controls +- API authentication key + +Changes to `.env` require container restart to take effect. --- ## File Structure ``` -v4/ -├── README.md ← You are here -├── QUICKREF_PHASE2.md ← Quick reference -├── PHASE_2_COMPLETE.md ← Phase 2 features -├── PHASE_2_SUMMARY.md ← Detailed summary -├── TESTING.md ← Testing guide -├── SETUP.md ← Setup instructions +traderv4/ +├── README.md ← You are here +├── DOCKER.md ← Docker deployment guide +├── SETUP.md ← Setup instructions +├── TESTING.md ← Testing guide +├── docker-compose.yml ← Docker orchestration +├── Dockerfile ← Multi-stage build +├── .env ← Configuration (template) +├── package.json ← Dependencies │ -├── config/ -│ └── trading.ts ← Trading configuration +├── app/ +│ ├── layout.tsx ← Root layout +│ ├── globals.css ← Tailwind styles +│ ├── settings/ +│ │ └── page.tsx ← Settings UI +│ └── api/ +│ ├── settings/ +│ │ └── route.ts ← Settings API +│ └── trading/ +│ ├── execute/route.ts ← Execute trades +│ ├── close/route.ts ← Close positions +│ ├── positions/route.ts ← Query positions +│ └── check-risk/route.ts ← Risk validation │ ├── lib/ │ ├── drift/ -│ │ ├── client.ts ← Drift SDK wrapper -│ │ └── orders.ts ← Order execution +│ │ ├── client.ts ← Drift SDK wrapper +│ │ └── orders.ts ← Order execution │ ├── pyth/ -│ │ └── price-monitor.ts ← Real-time prices +│ │ └── price-monitor.ts ← Real-time prices │ └── trading/ -│ └── position-manager.ts ← Auto-exit logic +│ └── position-manager.ts ← Auto-exit logic │ -├── app/ -│ └── api/ -│ └── trading/ -│ ├── execute/ -│ │ └── route.ts ← Execute trade -│ ├── check-risk/ -│ │ └── route.ts ← Risk validation -│ └── positions/ -│ └── route.ts ← Query positions +├── config/ +│ └── trading.ts ← Market configurations │ -└── test-*.ts ← Test scripts +├── n8n-complete-workflow.json ← Full n8n workflow +└── n8n-trader-workflow.json ← Alternative workflow ``` ---