feat: Add database init on startup and documentation

- Add lifespan handler to main.py for automatic DB table creation - Expand .env.example with detailed variable documentation - Add AUDIT_REPORT.md with comprehensive product/technical review - Add STRATEGY_SCHEMA.md as single source of truth for strategy config - Remove redundant init_db.py script (DB init now handled by app startup)
feat: Add deployment documentation and templates (issue #12 ) (#23 )
2026-04-09 04:49:11 +00:00 · 2026-04-09 01:23:53 +02:00 · 2026-04-08 16:49:13 +02:00 · 2026-04-08 14:41:40 +00:00 · 2026-04-08 16:23:23 +02:00
13 changed files with 1782 additions and 2 deletions
--- a/deployment/DEPLOYMENT.md
+++ b/deployment/DEPLOYMENT.md
@@ -0,0 +1,223 @@
+# Deployment Guide
+
+This document describes how to deploy the Randebu Trading Bot application to a production server.
+
+## Prerequisites
+
+- Debian server with 8GB RAM, 4 cores
+- Python 3.10+
+- Node.js 18+
+- Nginx
+- SSL certificate (Let's Encrypt)
+- SSH access to server
+
+## Server Structure
+
+```
+/var/www/
+  └── bot/
+      ├── backend/          # Backend application (FastAPI)
+      ├── frontend/         # Frontend static files (SvelteKit build)
+      └── data/             # SQLite database and app data
+```
+
+## Step-by-Step Deployment
+
+### 1. Clone Repository
+
+```bash
+ssh user@your-server
+sudo mkdir -p /var/www/bot
+sudo chown -R $USER:$USER /var/www/bot
+cd /var/www/bot
+git clone https://git.example.com/shoko/randebu.git .
+```
+
+### 2. Setup Backend
+
+```bash
+cd /var/www/bot/src/backend
+
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+
+mkdir -p /var/www/bot/data
+```
+
+### 3. Configure Environment
+
+Copy and configure the environment file:
+
+```bash
+cp src/backend/.env.example /var/www/bot/data/.env
+nano /var/www/bot/data/.env
+```
+
+Update these values:
+- `SECRET_KEY` - Generate a secure key
+- `DATABASE_URL` - Update path to `/var/www/bot/data/app.db`
+- `MINIMAX_API_KEY` - Your API key
+- `AVE_API_KEY` - Your API key
+
+### 4. Build Frontend
+
+```bash
+cd /var/www/bot/src/frontend
+npm install
+npm run build
+
+# Move build to expected location
+mkdir -p /var/www/bot/frontend
+cp -r build/* /var/www/bot/frontend/
+```
+
+### 5. Configure Nginx
+
+Copy the nginx template and modify as needed:
+
+```bash
+sudo cp /var/www/bot/deployment/scripts/nginx-template.conf /etc/nginx/sites-available/bot.yourdomain.com
+sudo nano /etc/nginx/sites-available/bot.yourdomain.com
+```
+
+Update `bot.yourdomain.com` with your actual domain.
+
+Enable the site:
+
+```bash
+sudo ln -s /etc/nginx/sites-available/bot.yourdomain.com /etc/nginx/sites-enabled/
+sudo nginx -t
+sudo systemctl reload nginx
+```
+
+### 6. Setup SSL Certificate
+
+```bash
+sudo apt install certbot python3-certbot-nginx
+sudo certbot --nginx -d bot.yourdomain.com
+```
+
+### 7. Configure Systemd Service
+
+Copy and configure the systemd service:
+
+```bash
+sudo cp /var/www/bot/deployment/scripts/systemd-template.service /etc/systemd/system/ave-backend.service
+sudo nano /etc/systemd/system/ave-backend.service
+```
+
+Update `your-user` and `/var/www/bot` paths as needed.
+
+### 8. Start Backend Service
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable ave-backend
+sudo systemctl start ave-backend
+sudo systemctl status ave-backend
+```
+
+### 9. Configure Firewall
+
+```bash
+sudo ufw allow 22/tcp
+sudo ufw allow 80/tcp
+sudo ufw allow 443/tcp
+sudo ufw enable
+```
+
+### 10. Verify Deployment
+
+1. Visit `https://bot.yourdomain.com` - should show frontend
+2. Visit `https://bot.yourdomain.com/api/...` - should hit backend API
+3. Check backend logs: `sudo journalctl -u ave-backend -f`
+
+## Project Structure
+
+```
+/var/www/bot/
+├── deployment/              # Deployment scripts and templates
+│   ├── DEPLOYMENT.md       # This file
+│   └── scripts/
+│       ├── nginx-template.conf
+│       ├── systemd-template.service
+│       └── deploy.sh       # Automated deployment script
+├── src/
+│   ├── backend/            # FastAPI application
+│   │   ├── app/
+│   │   │   ├── api/       # API routes
+│   │   │   ├── core/      # Core functionality
+│   │   │   ├── db/        # Database models
+│   │   │   └── services/  # Business logic
+│   │   ├── run.py
+│   │   └── requirements.txt
+│   └── frontend/           # SvelteKit application
+│       ├── src/
+│       └── package.json
+├── data/                   # Runtime data (gitignored)
+│   ├── app.db             # SQLite database
+│   └── .env               # Environment variables
+└── frontend/              # Built frontend static files
+```
+
+## Troubleshooting
+
+### Backend won't start
+
+Check logs:
+```bash
+sudo journalctl -u ave-backend -n 100
+```
+
+Common issues:
+- Missing environment variables - check `.env` file
+- Port 8000 already in use - check configuration
+- Database path incorrect - verify paths
+
+### Nginx errors
+
+Test configuration:
+```bash
+sudo nginx -t
+```
+
+Check error logs:
+```bash
+sudo tail -f /var/log/nginx/error.log
+```
+
+### SSL certificate issues
+
+Renew certificate:
+```bash
+sudo certbot renew
+```
+
+Check certificate status:
+```bash
+sudo certbot certificates
+```
+
+## Useful Commands
+
+| Action | Command |
+|--------|---------|
+| Restart backend | `sudo systemctl restart ave-backend` |
+| View backend logs | `sudo journalctl -u ave-backend -f` |
+| Check nginx status | `sudo systemctl status nginx` |
+| Reload nginx | `sudo systemctl reload nginx` |
+| Check port 8000 | `curl http://localhost:8000/health` |
+
+## Rolling Updates
+
+To update the application:
+
+```bash
+cd /var/www/bot
+git pull
+cd src/backend && source venv/bin/activate && pip install -r requirements.txt
+sudo systemctl restart ave-backend
+```
+
+For frontend updates, rebuild and copy static files to `/var/www/bot/frontend`.
--- a/deployment/scripts/deploy.sh
+++ b/deployment/scripts/deploy.sh
@@ -0,0 +1,47 @@
+#!/bin/bash
+set -e
+
+DEPLOY_DIR="/var/www/bot"
+DOMAIN="bot.yourdomain.com"
+GIT_REPO="https://git.example.com/shoko/randebu.git"
+BRANCH="main"
+
+echo "=== Randebu Deployment Script ==="
+echo "Deploy directory: $DEPLOY_DIR"
+echo "Domain: $DOMAIN"
+echo ""
+
+cd "$DEPLOY_DIR"
+
+echo "[1/6] Pulling latest code..."
+git pull origin "$BRANCH"
+
+echo "[2/6] Updating backend dependencies..."
+cd "$DEPLOY_DIR/src/backend"
+source venv/bin/activate
+pip install -r requirements.txt
+
+echo "[3/6] Rebuilding frontend..."
+cd "$DEPLOY_DIR/src/frontend"
+npm install
+npm run build
+mkdir -p "$DEPLOY_DIR/frontend"
+cp -r build/* "$DEPLOY_DIR/frontend/"
+
+echo "[4/6] Restarting backend service..."
+sudo systemctl restart ave-backend
+sleep 2
+sudo systemctl status ave-backend --no-pager
+
+echo "[5/6] Testing endpoints..."
+curl -s "http://localhost:8000/health" && echo ""
+curl -s -o /dev/null -w "Frontend: %{http_code}\n" "https://$DOMAIN/" || true
+
+echo "[6/6] Verifying SSL..."
+sudo certbot certificates 2>/dev/null | grep -A2 "$DOMAIN" || echo "No certificate found for $DOMAIN"
+
+echo ""
+echo "=== Deployment Complete ==="
+echo "Backend: https://$DOMAIN/api/"
+echo "Frontend: https://$DOMAIN/"
+echo "Backend logs: sudo journalctl -u ave-backend -f"
--- a/deployment/scripts/nginx-template.conf
+++ b/deployment/scripts/nginx-template.conf
@@ -0,0 +1,59 @@
+server {
+    listen 80;
+    server_name bot.yourdomain.com;
+
+    return 301 https://$server_name$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name bot.yourdomain.com;
+
+    ssl_certificate /etc/letsencrypt/live/bot.yourdomain.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/bot.yourdomain.com/privkey.pem;
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
+    ssl_prefer_server_ciphers off;
+    ssl_session_cache shared:SSL:10m;
+    ssl_session_timeout 1d;
+
+    root /var/www/bot/frontend;
+    index index.html;
+
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    location /api/ {
+        proxy_pass http://127.0.0.1:8000/api/;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_cache_bypass $http_upgrade;
+    }
+
+    location /ws/ {
+        proxy_pass http://127.0.0.1:8000/ws/;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+    }
+
+    gzip on;
+    gzip_vary on;
+    gzip_min_length 1024;
+    gzip_types text/plain text/css text/xml text/javascript application/javascript application/xml+rss application/json;
+}
--- a/deployment/scripts/systemd-template.service
+++ b/deployment/scripts/systemd-template.service
@@ -0,0 +1,21 @@
+[Unit]
+Description=Randebu Trading Bot Backend
+After=network.target
+
+[Service]
+Type=simple
+User=your-user
+WorkingDirectory=/var/www/bot/src/backend
+Environment="PATH=/var/www/bot/src/backend/venv/bin"
+ExecStart=/var/www/bot/src/backend/venv/bin/python /var/www/bot/src/backend/run.py
+Restart=always
+RestartSec=10
+
+EnvironmentFile=/var/www/bot/data/.env
+
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=ave-backend
+
+[Install]
+WantedBy=multi-user.target
--- a/docs/AUDIT_REPORT.md
+++ b/docs/AUDIT_REPORT.md
@@ -0,0 +1,521 @@
+# Randebu Trading Bot - Product & Technical Audit Report
+
+> **Date:** 2026-04-09  
+> **Phase:** Phase 1 Implementation Complete - Pre-Testing Review  
+> **Purpose:** Document current state, issues found, and recommendations for next steps
+
+---
+
+## 1. Product Overview
+
+### 1.1 What is Randebu?
+
+Randebu is an AI-powered trading bot platform where users create and manage automated trading strategies through natural language chat—similar to ChatGPT, but specialized for creating trading bots.
+
+### 1.2 Core User Flow
+
+```
+User Registration → Create Bot → Chat with AI to Define Strategy 
+    → Backtest Strategy → Simulate Trading → (Future) Live Trading
+```
+
+### 1.3 Phase 1 Scope
+
+| Feature | Status |
+|---------|--------|
+| BNB Chain only | ✅ Intended (not yet enforced) |
+| Backtest engine | ✅ Implemented |
+| Simulation engine | ✅ Implemented |
+| Natural language strategy parsing | ✅ Implemented |
+| User authentication | ✅ Implemented |
+| Multi-bot support (max 3) | ✅ Implemented |
+| Dummy wallet (database record) | ✅ Implemented |
+
+### 1.4 Tech Stack
+
+| Layer | Technology |
+|-------|------------|
+| Frontend | Svelte 5 + TypeScript |
+| Backend | Python FastAPI |
+| AI Agent | CrewAI + MiniMax LLM |
+| Database | SQLite |
+| Trading Data | AVE Cloud API |
+
+---
+
+## 2. Critical Issues (Must Fix Before Testing)
+
+These issues will cause complete pipeline failure if not addressed.
+
+### 2.1 Database Tables Never Created
+
+**Location:** `src/backend/app/main.py`, `src/backend/run.py`
+
+**Problem:** The application starts but never creates the database tables. There is no:
+- Alembic migration setup
+- `Base.metadata.create_all()` call on startup
+- Database initialization script
+
+**Impact:** First database operation will fail with "table not found" error.
+
+**Current State:**
+```python
+# core/database.py defines Base, but nothing calls:
+# Base.metadata.create_all(engine)
+```
+
+**Fix Required:** Add database initialization on application startup.
+
+---
+
+### 2.2 Strategy Config Schema Mismatch
+
+**Location:** Multiple files - see mapping below
+
+**Problem:** The LLM outputs one schema format, but the backtest and simulation engines expect a completely different format. This is a **complete pipeline break** - strategies parsed by AI will never trigger any trades in backtesting.
+
+#### Schema Flow Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│ LLM OUTPUT (llm_connector.py) - What AI actually produces             │
+├─────────────────────────────────────────────────────────────────────────┤
+│ {                                                                       │
+│   "type": "price_drop",                                                │
+│   "params": {                                                          │
+│     "token": "PEPE",                                                   │
+│     "threshold_percent": 5                                             │
+│   }                                                                    │
+│ }                                                                       │
+└─────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│ BACKEND VALIDATOR (crew.py - StrategyValidator.validate())             │
+├─────────────────────────────────────────────────────────────────────────┤
+│ # Validator expects params.threshold_percent - THIS WORKS              │
+│ if "threshold_percent" not in params:                                  │
+│     errors.append(f"Condition {i}: missing 'threshold_percent'")       │
+└─────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼ (But engines look for flat fields)
+┌─────────────────────────────────────────────────────────────────────────┐
+│ BACKTEST ENGINE (services/backtest/engine.py - _check_condition())     │
+├─────────────────────────────────────────────────────────────────────────┤
+│ # What engine actually looks for:                                      │
+│ threshold = condition.get("threshold", 0)    # ❌ Returns 0!          │
+│ token = condition.get("token")                # ❌ Wrong path!         │
+│ timeframe = condition.get("timeframe")        # ❌ Not in params!     │
+│                                                                          │
+│ # Result: Conditions NEVER trigger because field names don't match     │
+└─────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│ SIMULATE ENGINE (services/simulate/engine.py - _check_condition())    │
+├─────────────────────────────────────────────────────────────────────────┤
+│ # Same issue as backtest engine                                        │
+│ threshold = condition.get("threshold", 0)    # ❌ Returns 0            │
+└─────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│ FRONTEND TYPES (src/frontend/src/lib/api/types.ts)                    │
+├─────────────────────────────────────────────────────────────────────────┤
+│ interface Condition {                                                  │
+│   type: 'price_drop' | 'price_rise' | 'volume_spike' | 'price_level';│
+│   token: string;                    # Flat - no params wrapper        │
+│   threshold?: number;               # Not threshold_percent!          │
+│   timeframe?: string;               # Exists here                    │
+│ }                                                                       │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+#### Field Mapping Table
+
+| Component | Token Field | Threshold Field | Timeframe Field |
+|-----------|-----------|-----------------|-----------------|
+| LLM Output | `params.token` | `params.threshold_percent` | N/A |
+| Validator | `params.token` | `params.threshold_percent` | N/A |
+| Backtest Engine | `token` | `threshold` | `timeframe` |
+| Simulate Engine | `token` | `threshold` | `timeframe` |
+| Frontend Types | `token` | `threshold` | `timeframe` |
+
+**Fix Required:** Normalize to ONE consistent schema across the entire pipeline. Recommended: Use the flat structure (token, threshold, timeframe) as it's simpler and already used by engines and frontend.
+
+---
+
+### 2.3 Bot Creation Will Fail
+
+**Location:** 
+- `src/backend/app/db/schemas.py` (BotCreate)
+- `src/frontend/src/lib/api/client.ts` (bots.create)
+
+**Problem:**
+
+| Issue | Details |
+|-------|---------|
+| Backend requires | `strategy_config: dict` (REQUIRED) |
+| Backend requires | `llm_config: dict` (REQUIRED) |
+| Frontend sends | Only `name` and optional `description` |
+
+**Impact:** Users cannot create bots through the frontend - API will return validation error.
+
+**Fix Required:** Either:
+1. Make `strategy_config` and `llm_config` optional in backend with default values
+2. OR update frontend to send default config values
+
+---
+
+### 2.4 Config Endpoints Return Empty Data
+
+**Location:** `src/backend/app/api/config.py`
+
+```python
+@router.get("/chains")
+def get_chains():
+    return {"chains": []}  # ❌ Always empty
+
+@router.get("/tokens")
+def get_tokens():
+    return {"tokens": []}  # ❌ Always empty
+```
+
+**Impact:** Frontend cannot populate dropdowns for chain/token selection.
+
+**Fix Required:** Return BSC (BNB Chain) as the only supported chain in Phase 1, and query AVE API for available tokens.
+
+---
+
+## 3. Major Issues
+
+### 3.1 Risk Management Not Implemented
+
+**Location:** 
+- `src/backend/app/db/models.py` (schema supports it)
+- `src/backend/app/services/backtest/engine.py`
+- `src/backend/app/services/simulate/engine.py`
+
+**Problem:** The database schema and frontend UI support `risk_management` configuration:
+```typescript
+interface RiskManagement {
+    stop_loss_percent?: number;
+    take_profit_percent?: number;
+}
+```
+
+However, neither the backtest nor simulation engines actually check or use stop-loss/take-profit logic during trade execution. The config is saved but ignored.
+
+**Fix Required:** Implement actual stop-loss and take-profit checks in both engines.
+
+---
+
+### 3.2 Duplicate AveCloudClient Implementations
+
+**Location:**
+- `src/backend/app/services/ave/client.py`
+- `src/backend/app/services/backtest/ave_client.py`
+
+**Problem:** Two different AveCloudClient classes with different methods:
+
+| `services/ave/client.py` | `services/backtest/ave_client.py` |
+|--------------------------|-----------------------------------|
+| `get_tokens()` | ❌ Missing |
+| `get_batch_prices()` | ✅ `get_batch_prices()` |
+| `get_token_details()` | ❌ Missing |
+| `get_klines()` | ✅ `get_klines()` |
+| `get_trending_tokens()` | ❌ Missing |
+| `get_token_risk()` | ❌ Missing |
+| `get_chain_quote()` | ❌ Missing |
+| `get_chain_swap()` | ❌ Missing |
+| ❌ Missing | `get_token_price()` |
+
+Additionally, the simulate engine imports from the wrong location:
+```python
+# services/simulate/engine.py
+from ..backtest.ave_client import AveCloudClient  # ❌ Wrong import
+```
+
+**Fix Required:** Consolidate into ONE AveCloudClient class.
+
+---
+
+### 3.3 Silent Error Handling in Simulation
+
+**Location:** `src/backend/app/services/simulate/engine.py`
+
+```python
+try:
+    # ... API calls ...
+except Exception as e:
+    pass  # ❌ Silently swallows ALL errors!
+```
+
+**Impact:** If AVE API fails or returns bad data, the simulation continues silently with no logging or user feedback.
+
+**Fix Required:** Add proper error logging and user-facing error messages.
+
+---
+
+### 3.4 No Chain Validation for Phase 1
+
+**Problem:** You mentioned limiting to BNB Chain only for Phase 1, but:
+- No backend validation enforces this
+- Users can specify any chain in backtest/simulate config
+- The config endpoints return empty arrays
+
+**Fix Required:** Add chain validation that only allows "bsc" for Phase 1.
+
+---
+
+### 3.5 In-Memory Token Blacklist
+
+**Location:** `src/backend/app/api/auth.py`
+
+```python
+TOKEN_BLACKLIST = set()  # ❌ In-memory only
+```
+
+**Problems:**
+- Resets when server restarts
+- Doesn't work with multiple workers/processes
+- Logout doesn't truly invalidate tokens in production
+
+**Fix Required:** Use Redis or database-backed token blacklist for production.
+
+---
+
+### 3.6 Conversation History Not Passed to Crew
+
+**Location:** `src/backend/app/api/bots.py`
+
+```python
+history_for_crew = conversation_history[-10:]  # Gets history
+crew = get_trading_crew()                      # ❌ Doesn't pass history!
+result = crew.chat(user_message, history_for_crew)
+```
+
+The history is fetched but not actually used by the agent - each chat starts fresh.
+
+**Fix Required:** Pass conversation history to the crew agent.
+
+---
+
+### 3.7 No Rate Limiting Applied
+
+**Location:** `src/backend/app/main.py`
+
+```python
+app.state.limiter = limiter  # Set up but not used on most endpoints
+```
+
+The rate limiter is initialized but only applied to the login endpoint. Other endpoints have no protection.
+
+**Fix Required:** Apply rate limiting to sensitive endpoints.
+
+---
+
+### 3.8 CORS Wide Open
+
+**Location:** `src/backend/app/main.py`
+
+```python
+allow_origins=["*"]  # ❌ Should be restricted to frontend domain
+```
+
+**Fix Required:** Limit CORS to the frontend domain in production.
+
+---
+
+### 3.9 No WebSocket for Real-Time Updates
+
+**Problem:** Users must poll the API to see:
+- Backtest progress
+- Simulation signals (new signals only appear on refresh)
+
+**Impact:** Poor UX during long-running operations.
+
+**Fix Required:** Add WebSocket support for real-time updates (Phase 2 or later).
+
+---
+
+## 4. Minor Issues
+
+### 4.1 Unused Dependencies
+
+**Location:** `src/backend/requirements.txt`
+
+```python
+anthropic>=0.18.0  # Included but project uses MiniMax
+```
+
+**Fix Required:** Remove unused dependency.
+
+---
+
+### 4.2 Missing .env Example
+
+**Problem:** No `.env.example` file to guide deployment.
+
+**Fix Required:** Create `.env.example` with all required variables documented.
+
+---
+
+### 4.3 No Input Sanitization
+
+User-provided data (bot names, chat messages) isn't sanitized before storage or display.
+
+**Fix Required:** Add input validation and sanitization.
+
+---
+
+### 4.4 Inconsistent Error Responses
+
+Some endpoints return `{"detail": "..."}` (FastAPI default), others return custom error shapes.
+
+**Fix Required:** Standardize error response format.
+
+---
+
+### 4.5 No Integration Tests
+
+No tests that verify the full pipeline (chat → config → backtest).
+
+**Fix Required:** Add integration tests.
+
+---
+
+## 5. Missing Documentation Files
+
+The following should be created:
+
+1. **`.env.example`** - All environment variables with descriptions
+2. **`docs/STRATEGY_SCHEMA.md`** - Single source of truth for strategy config schema
+3. **`docs/API_SCHEMA.md`** - API contract documentation
+4. **`init_db.py`** - Database initialization script
+
+---
+
+## 6. Recommendations Summary
+
+### Priority Matrix
+
+| Priority | Issue | Effort | Impact |
+|----------|-------|--------|--------|
+| **P0** | Database tables not created | Small | App crashes on startup |
+| **P0** | Bot creation fails | Small | Users can't create bots |
+| **P0** | Strategy schema mismatch | Medium | Backtesting completely broken |
+| **P0** | Config endpoints empty | Small | No chain/token selection |
+| **P1** | Risk management not implemented | Medium | No stop-loss/take-profit |
+| **P1** | Chain validation missing | Small | Can use non-BSC chains |
+| **P1** | Silent error handling | Small | Hard to debug issues |
+| **P2** | Duplicate AveCloudClient | Medium | Maintenance burden |
+| **P2** | CORS restricted | Small | Security hardening |
+| **P2** | Token blacklist (production) | Medium | Security |
+| **P2** | Rate limiting | Medium | DoS protection |
+| **P3** | WebSocket support | Large | UX improvement |
+| **P3** | Integration tests | Medium | Code quality |
+
+---
+
+## 7. AVE Cloud Integration Notes
+
+### Rate Limit Strategy
+
+| Tier | TPS | Recommended Approach |
+|------|-----|---------------------|
+| Free | 1 | Aggressive caching, batch requests |
+| Normal | 5 | Moderate caching |
+| Pro | 20 | Minimal caching |
+
+### Caching Recommendations
+
+1. **Token prices:** Cache for 30-60 seconds
+2. **Trending tokens:** Cache for 5-10 minutes
+3. **Token details:** Cache for 5-10 minutes
+4. **Risk assessments:** Cache for 15-30 minutes
+
+### No Testnet Warning
+
+AVE Cloud has **no testnet**. All API calls use real money:
+- Use quote/dry-run mode for testing
+- Start with minimal amounts ($1-10)
+- Contact AVE support about sandbox options
+
+---
+
+## 8. Next Steps
+
+### Immediate (Before Testing)
+
+1. Add database initialization to startup
+2. Fix bot creation (frontend or backend)
+3. **Normalize strategy schema** - Choose flat structure, update all components
+4. Populate config endpoints with BSC + default tokens
+5. Add BSC-only chain validation
+
+### Short Term
+
+6. Implement risk management (stop-loss/take-profit)
+7. Consolidate AveCloudClient
+8. Add proper error handling
+9. Create .env.example
+10. Add input sanitization
+
+### Medium Term
+
+11. Add WebSocket for real-time updates
+12. Implement production token blacklist (Redis)
+13. Apply rate limiting
+14. Restrict CORS
+15. Add integration tests
+
+---
+
+## 9. Files Reference
+
+### Key Backend Files
+
+| File | Purpose |
+|------|---------|
+| `src/backend/app/main.py` | FastAPI app initialization |
+| `src/backend/app/api/bots.py` | Bot CRUD + chat endpoint |
+| `src/backend/app/api/backtest.py` | Backtest API |
+| `src/backend/app/api/simulate.py` | Simulation API |
+| `src/backend/app/api/ave.py` | AVE Cloud proxy endpoints |
+| `src/backend/app/api/config.py` | Config endpoints |
+| `src/backend/app/db/schemas.py` | Pydantic schemas |
+| `src/backend/app/db/models.py` | SQLAlchemy models |
+| `src/backend/app/services/ai_agent/crew.py` | CrewAI agents |
+| `src/backend/app/services/ai_agent/llm_connector.py` | MiniMax LLM |
+| `src/backend/app/services/backtest/engine.py` | Backtest logic |
+| `src/backend/app/services/simulate/engine.py` | Simulation logic |
+| `src/backend/app/services/ave/client.py` | AVE Cloud client |
+
+### Key Frontend Files
+
+| File | Purpose |
+|------|---------|
+| `src/frontend/src/lib/api/client.ts` | API client |
+| `src/frontend/src/lib/api/types.ts` | TypeScript types |
+| `src/frontend/src/routes/bot/[id]/+page.svelte` | Bot chat page |
+| `src/frontend/src/routes/bot/[id]/backtest/+page.svelte` | Backtest page |
+| `src/frontend/src/routes/bot/[id]/simulate/+page.svelte` | Simulation page |
+| `src/frontend/src/lib/components/ChatInterface.svelte` | Chat UI |
+| `src/frontend/src/lib/components/StrategyPreview.svelte` | Strategy display |
+
+---
+
+## 10. Audit Complete
+
+This audit was conducted by reviewing:
+- All source code in `src/backend/` and `src/frontend/`
+- Documentation in `docs/`
+- Database models and schemas
+- API endpoints and their implementations
+
+The product has a **solid architectural foundation** and addresses a real market need. The core issues are manageable - primarily schema standardization and missing initialization code.
+
+---
+
+*End of Audit Report*
--- a/docs/STRATEGY_SCHEMA.md
+++ b/docs/STRATEGY_SCHEMA.md
@@ -0,0 +1,279 @@
+# Strategy Config Schema
+
+> **Status:** DRAFT - Needs to be normalized with implementation  
+> **Purpose:** Single source of truth for strategy configuration format
+
+---
+
+## 1. Overview
+
+This document defines the structure of the `strategy_config` JSON object that represents a trading bot's strategy. This config is:
+- Generated by the AI from natural language input
+- Validated by the backend
+- Used by backtest and simulation engines
+- Displayed in the frontend
+
+---
+
+## 2. Schema Version
+
+**Current Version:** 1.0  
+**Status:** Flat structure (NOT nested in `params`)
+
+> **IMPORTANT:** The current implementation has a mismatch where the LLM outputs a nested `params` structure but the engines expect flat fields. This document defines the **TARGET** schema to normalize all components.
+
+---
+
+## 3. Full Schema
+
+```json
+{
+  "version": "1.0",
+  "conditions": [
+    {
+      "type": "price_drop",
+      "token": "PEPE",
+      "chain": "bsc",
+      "threshold": 5,
+      "timeframe": "1h"
+    }
+  ],
+  "actions": [
+    {
+      "type": "buy",
+      "amount_percent": 10,
+      "token": "PEPE"
+    }
+  ],
+  "risk_management": {
+    "stop_loss_percent": 3,
+    "take_profit_percent": 10
+  }
+}
+```
+
+---
+
+## 4. Field Definitions
+
+### 4.1 Root Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `version` | string | No | Schema version (for future compatibility) |
+| `conditions` | array | Yes | List of trigger conditions |
+| `actions` | array | Yes | List of actions to execute when conditions are met |
+| `risk_management` | object | No | Risk management settings |
+
+### 4.2 Condition Object
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `type` | string | Yes | Condition type (see supported types below) |
+| `token` | string | Yes | Token symbol or address (e.g., "PEPE" or "0x123...-bsc") |
+| `chain` | string | No | Blockchain chain (default: "bsc") |
+| `threshold` | number | For price_drop/rise/volume_spike | Percentage threshold (e.g., 5 = 5%) |
+| `price` | number | For price_level | Price level to trigger on |
+| `direction` | string | For price_level | "above" or "below" |
+| `timeframe` | string | No | Time window for calculation (e.g., "1h", "15m") |
+
+#### Supported Condition Types
+
+| Type | Description | Required Fields |
+|------|-------------|-----------------|
+| `price_drop` | Triggers when token price drops by threshold % | token, threshold |
+| `price_rise` | Triggers when token price rises by threshold % | token, threshold |
+| `volume_spike` | Triggers when trading volume increases by threshold % | token, threshold |
+| `price_level` | Triggers when price crosses a specific level | token, price, direction |
+
+### 4.3 Action Object
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `type` | string | Yes | Action type (buy, sell, hold, notify) |
+| `amount_percent` | number | For buy/sell | Percentage of portfolio to trade |
+| `token` | string | No | Token to trade (defaults to condition token) |
+
+#### Supported Action Types
+
+| Type | Description | Required Fields |
+|------|-------------|-----------------|
+| `buy` | Purchase tokens | amount_percent |
+| `sell` | Sell tokens | amount_percent |
+| `hold` | Do nothing (log only) | - |
+| `notify` | Send notification to user | - |
+
+### 4.4 Risk Management Object
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `stop_loss_percent` | number | No | Exit trade if loss exceeds this % |
+| `take_profit_percent` | number | No | Exit trade if profit reaches this % |
+
+---
+
+## 5. Examples
+
+### 5.1 Simple Buy on Price Drop
+
+> "Buy PEPE when it drops 5% in 1 hour"
+
+```json
+{
+  "conditions": [
+    {
+      "type": "price_drop",
+      "token": "PEPE",
+      "chain": "bsc",
+      "threshold": 5,
+      "timeframe": "1h"
+    }
+  ],
+  "actions": [
+    {
+      "type": "buy",
+      "amount_percent": 10
+    }
+  ]
+}
+```
+
+### 5.2 Buy on Price Rise with Stop Loss
+
+> "Buy when PEPE rises 10%, but stop loss at 3%"
+
+```json
+{
+  "conditions": [
+    {
+      "type": "price_rise",
+      "token": "PEPE",
+      "threshold": 10,
+      "timeframe": "4h"
+    }
+  ],
+  "actions": [
+    {
+      "type": "buy",
+      "amount_percent": 20
+    }
+  ],
+  "risk_management": {
+    "stop_loss_percent": 3
+  }
+}
+```
+
+### 5.3 Sell on Price Level
+
+> "Sell when PEPE reaches $0.0001"
+
+```json
+{
+  "conditions": [
+    {
+      "type": "price_level",
+      "token": "PEPE",
+      "price": 0.0001,
+      "direction": "above"
+    }
+  ],
+  "actions": [
+    {
+      "type": "sell",
+      "amount_percent": 100
+    }
+  ]
+}
+```
+
+### 5.4 Volume Spike Alert
+
+> "Notify me when PEPE volume spikes 50%"
+
+```json
+{
+  "conditions": [
+    {
+      "type": "volume_spike",
+      "token": "PEPE",
+      "threshold": 50,
+      "timeframe": "1h"
+    }
+  ],
+  "actions": [
+    {
+      "type": "notify"
+    }
+  ]
+}
+```
+
+---
+
+## 6. Validation Rules
+
+### 6.1 Conditions
+
+- At least one condition is required
+- Each condition must have a valid `type`
+- Token must be specified
+- Threshold must be positive number (for applicable types)
+- Price level must be specified for `price_level` type
+- Direction must be "above" or "below" for `price_level` type
+
+### 6.2 Actions
+
+- At least one action is required
+- Each action must have a valid `type`
+- `amount_percent` must be between 0 and 100
+
+### 6.3 Risk Management
+
+- `stop_loss_percent` must be positive
+- `take_profit_percent` must be positive
+
+---
+
+## 7. Implementation Status
+
+### Components Using This Schema
+
+| Component | Status | Notes |
+|-----------|--------|-------|
+| Backend Validator (crew.py) | ❌ Mismatch | Uses nested `params` structure |
+| Backtest Engine | ❌ Mismatch | Uses flat structure (correct) |
+| Simulate Engine | ❌ Mismatch | Uses flat structure (correct) |
+| Frontend Types | ✅ Match | Uses flat structure |
+| Frontend StrategyPreview | ✅ Match | Uses flat structure |
+
+### Normalization Required
+
+The LLM output parser should be updated to output flat structure (not nested in `params`) to match what the engines and frontend expect.
+
+---
+
+## 8. Future Extensions
+
+### Potential Condition Types (Phase 2+)
+
+| Type | Description |
+|------|-------------|
+| `rsi_oversold` | RSI indicator below threshold |
+| `rsi_overbought` | RSI indicator above threshold |
+| `ma_crossover` | Moving average crossover |
+| `bollinger_breakout` | Bollinger Band breakout |
+| `news_sentiment` | Based on news sentiment analysis |
+
+### Potential Action Types (Phase 2+)
+
+| Type | Description |
+|------|-------------|
+| `dca_buy` | Dollar cost averaging buy |
+| `trailing_stop` | Trailing stop loss |
+| `smart_rebalance` | Portfolio rebalancing |
+
+---
+
+*Document Version: 1.0*  
+*Last Updated: 2026-04-09*
--- a/src/backend/.env.example
+++ b/src/backend/.env.example
@@ -1,11 +1,68 @@
+# Randebu Trading Bot - Environment Variables Template
+# Copy this file to .env and fill in your values
+
+# =============================================================================
+# DATABASE
+# =============================================================================
+
+# SQLite database path (relative or absolute)
+# Example: sqlite:///./data/app.db
 DATABASE_URL=sqlite:///./data/app.db
+
+# =============================================================================
+# AUTHENTICATION
+# =============================================================================
+
+# Secret key for JWT token signing
+# Generate with: python -c "import secrets; print(secrets.token_hex(32))"
 SECRET_KEY=your-super-secret-key-change-in-production
+
+# JWT algorithm (HS256 is recommended)
 JWT_ALGORITHM=HS256
+
+# Token expiration time in minutes (1440 = 24 hours)
 ACCESS_TOKEN_EXPIRE_MINUTES=1440
+
+# =============================================================================
+# MINIMAX LLM
+# =============================================================================
+
+# MiniMax API key (get from https://platform.minimax.chat/)
 MINIMAX_API_KEY=your-minimax-api-key
+
+# MiniMax model to use
+# Common options: MiniMax-Text-01, MiniMax-M2.1
 MINIMAX_MODEL=MiniMax-Text-01
-AVE_API_KEY=your-ave-cloud-api-key
+
+# =============================================================================
+# AVE CLOUD API
+# =============================================================================
+
+# AVE Cloud API key (get from https://cloud.ave.ai/)
+AVE_API_KEY=your-ave-api-key
+
+# AVE Cloud plan tier
+# Options: free, normal, pro
+# Note: Free tier has 1 TPS limit, Pro required for WebSocket
 AVE_API_PLAN=free
+
+# =============================================================================
+# SERVER CONFIGURATION
+# =============================================================================
+
+# Server host (0.0.0.0 for all interfaces)
 HOST=0.0.0.0
+
+# Server port
 PORT=8000
+
+# Debug mode (set to false in production)
 DEBUG=false
+
+# =============================================================================
+# FRONTEND CONFIGURATION (for reference)
+# =============================================================================
+
+# Frontend environment variables (set in frontend .env file):
+# VITE_API_URL=https://bot.yourdomain.com/api
+# VITE_WS_URL=wss://bot.yourdomain.com/ws
--- a/src/backend/app/api/ave.py
+++ b/src/backend/app/api/ave.py
@@ -0,0 +1,265 @@
+from fastapi import APIRouter, Depends, HTTPException, status, Request
+from sqlalchemy.orm import Session
+from typing import Annotated, Optional
+import httpx
+
+from .auth import get_current_user
+from ..core.database import get_db
+from ..core.config import get_settings
+from ..db.models import User
+from ..services.ave import AveCloudClient, check_tier_access
+from ..db.schemas import (
+    AveBatchPricesRequest,
+    AveKlinesRequest,
+    AveChainQuoteRequest,
+    AveChainSwapRequest,
+)
+
+router = APIRouter()
+
+
+def get_ave_client() -> AveCloudClient:
+    settings = get_settings()
+    return AveCloudClient(api_key=settings.AVE_API_KEY, plan=settings.AVE_API_PLAN)
+
+
+@router.get("/tokens")
+async def search_tokens(
+    query: Optional[str] = None,
+    chain: Optional[str] = None,
+    limit: int = 20,
+    current_user: User = Depends(get_current_user),
+):
+    client = get_ave_client()
+    try:
+        tokens = await client.get_tokens(query=query, chain=chain, limit=limit)
+        return {"tokens": tokens}
+    except httpx.HTTPStatusError as e:
+        if e.response.status_code == 429:
+            raise HTTPException(
+                status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+                detail="Rate limit exceeded. Please try again later.",
+            )
+        raise HTTPException(
+            status_code=e.response.status_code,
+            detail=f"AVE API error: {e.response.text}",
+        )
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to fetch tokens: {str(e)}",
+        )
+
+
+@router.post("/tokens/price")
+async def get_batch_prices(
+    request: AveBatchPricesRequest,
+    current_user: User = Depends(get_current_user),
+):
+    client = get_ave_client()
+    try:
+        prices = await client.get_batch_prices(request.token_ids)
+        return {"prices": prices}
+    except httpx.HTTPStatusError as e:
+        if e.response.status_code == 429:
+            raise HTTPException(
+                status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+                detail="Rate limit exceeded. Please try again later.",
+            )
+        raise HTTPException(
+            status_code=e.response.status_code,
+            detail=f"AVE API error: {e.response.text}",
+        )
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to fetch batch prices: {str(e)}",
+        )
+
+
+@router.get("/tokens/{token_id}")
+async def get_token_details(
+    token_id: str,
+    current_user: User = Depends(get_current_user),
+):
+    client = get_ave_client()
+    try:
+        token = await client.get_token_details(token_id)
+        if token is None:
+            return {"token": None, "upsell_message": None}
+        return {"token": token}
+    except httpx.HTTPStatusError as e:
+        if e.response.status_code == 429:
+            raise HTTPException(
+                status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+                detail="Rate limit exceeded. Please try again later.",
+            )
+        raise HTTPException(
+            status_code=e.response.status_code,
+            detail=f"AVE API error: {e.response.text}",
+        )
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to fetch token details: {str(e)}",
+        )
+
+
+@router.get("/klines/{token_id}")
+async def get_klines(
+    token_id: str,
+    interval: str = "1h",
+    limit: int = 100,
+    start_time: Optional[int] = None,
+    end_time: Optional[int] = None,
+    current_user: User = Depends(get_current_user),
+):
+    client = get_ave_client()
+    try:
+        klines = await client.get_klines(
+            token_id=token_id,
+            interval=interval,
+            limit=limit,
+            start_time=start_time,
+            end_time=end_time,
+        )
+        return {"klines": klines}
+    except httpx.HTTPStatusError as e:
+        if e.response.status_code == 429:
+            raise HTTPException(
+                status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+                detail="Rate limit exceeded. Please try again later.",
+            )
+        raise HTTPException(
+            status_code=e.response.status_code,
+            detail=f"AVE API error: {e.response.text}",
+        )
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to fetch klines: {str(e)}",
+        )
+
+
+@router.get("/tokens/trending")
+async def get_trending_tokens(
+    chain: Optional[str] = None,
+    limit: int = 20,
+    current_user: User = Depends(get_current_user),
+):
+    client = get_ave_client()
+    try:
+        tokens = await client.get_trending_tokens(chain=chain, limit=limit)
+        return {"tokens": tokens}
+    except httpx.HTTPStatusError as e:
+        if e.response.status_code == 429:
+            raise HTTPException(
+                status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+                detail="Rate limit exceeded. Please try again later.",
+            )
+        raise HTTPException(
+            status_code=e.response.status_code,
+            detail=f"AVE API error: {e.response.text}",
+        )
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to fetch trending tokens: {str(e)}",
+        )
+
+
+@router.get("/contracts/{contract_id}")
+async def get_token_risk(
+    contract_id: str,
+    current_user: User = Depends(get_current_user),
+):
+    client = get_ave_client()
+    try:
+        risk = await client.get_token_risk(contract_id)
+        if risk is None:
+            return {"risk": None, "upsell_message": None}
+        return {"risk": risk}
+    except httpx.HTTPStatusError as e:
+        if e.response.status_code == 429:
+            raise HTTPException(
+                status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+                detail="Rate limit exceeded. Please try again later.",
+            )
+        raise HTTPException(
+            status_code=e.response.status_code,
+            detail=f"AVE API error: {e.response.text}",
+        )
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to fetch token risk: {str(e)}",
+        )
+
+
+@router.post("/chain/quote")
+async def get_chain_quote(
+    request: AveChainQuoteRequest,
+    current_user: User = Depends(get_current_user),
+):
+    client = get_ave_client()
+    try:
+        quote = await client.get_chain_quote(
+            chain=request.chain,
+            from_token=request.from_token,
+            to_token=request.to_token,
+            amount=request.amount,
+            slippage=request.slippage,
+        )
+        if quote is None:
+            return {"quote": None, "upsell_message": None}
+        return {"quote": quote}
+    except httpx.HTTPStatusError as e:
+        if e.response.status_code == 429:
+            raise HTTPException(
+                status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+                detail="Rate limit exceeded. Please try again later.",
+            )
+        raise HTTPException(
+            status_code=e.response.status_code,
+            detail=f"AVE API error: {e.response.text}",
+        )
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to fetch chain quote: {str(e)}",
+        )
+
+
+@router.post("/chain/swap")
+async def get_chain_swap(
+    request: AveChainSwapRequest,
+    current_user: User = Depends(get_current_user),
+):
+    client = get_ave_client()
+    try:
+        swap = await client.get_chain_swap(
+            chain=request.chain,
+            from_token=request.from_token,
+            to_token=request.to_token,
+            amount=request.amount,
+            slippage=request.slippage,
+            wallet_address=request.wallet_address,
+        )
+        if swap is None:
+            return {"swap": None, "upsell_message": None}
+        return {"swap": swap}
+    except httpx.HTTPStatusError as e:
+        if e.response.status_code == 429:
+            raise HTTPException(
+                status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+                detail="Rate limit exceeded. Please try again later.",
+            )
+        raise HTTPException(
+            status_code=e.response.status_code,
+            detail=f"AVE API error: {e.response.text}",
+        )
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to fetch chain swap: {str(e)}",
+        )
--- a/src/backend/app/db/models.py
+++ b/src/backend/app/db/models.py
@@ -25,6 +25,7 @@ class User(Base):
    id = Column(String, primary_key=True, default=generate_uuid)
    email = Column(String, unique=True, nullable=False)
    password_hash = Column(String, nullable=False)
+    tier = Column(String, default="free")
    created_at = Column(DateTime, default=datetime.utcnow)
    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)

--- a/src/backend/app/db/schemas.py
+++ b/src/backend/app/db/schemas.py
@@ -144,3 +144,72 @@ class SignalResponse(BaseModel):

    class Config:
        from_attributes = True
+
+
+class AveTokenSearchResponse(BaseModel):
+    tokens: List[dict]
+    upsell_message: Optional[str] = None
+
+
+class AveBatchPricesRequest(BaseModel):
+    token_ids: List[str]
+
+
+class AveBatchPricesResponse(BaseModel):
+    prices: Dict[str, dict]
+    upsell_message: Optional[str] = None
+
+
+class AveTokenDetailsResponse(BaseModel):
+    token: Optional[dict] = None
+    upsell_message: Optional[str] = None
+
+
+class AveKlinesRequest(BaseModel):
+    token_id: str
+    interval: str = "1h"
+    limit: int = 100
+    start_time: Optional[int] = None
+    end_time: Optional[int] = None
+
+
+class AveKlinesResponse(BaseModel):
+    klines: List[dict]
+    upsell_message: Optional[str] = None
+
+
+class AveTrendingTokensResponse(BaseModel):
+    tokens: List[dict]
+    upsell_message: Optional[str] = None
+
+
+class AveTokenRiskResponse(BaseModel):
+    risk: Optional[dict] = None
+    upsell_message: Optional[str] = None
+
+
+class AveChainQuoteRequest(BaseModel):
+    chain: str
+    from_token: str
+    to_token: str
+    amount: str
+    slippage: float = 0.5
+
+
+class AveChainQuoteResponse(BaseModel):
+    quote: Optional[dict] = None
+    upsell_message: Optional[str] = None
+
+
+class AveChainSwapRequest(BaseModel):
+    chain: str
+    from_token: str
+    to_token: str
+    amount: str
+    slippage: float = 0.5
+    wallet_address: Optional[str] = None
+
+
+class AveChainSwapResponse(BaseModel):
+    swap: Optional[dict] = None
+    upsell_message: Optional[str] = None
--- a/src/backend/app/main.py
+++ b/src/backend/app/main.py
@@ -1,14 +1,35 @@
+import logging
+from contextlib import asynccontextmanager
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 from slowapi import Limiter
 from slowapi.util import get_remote_address
-from .api import auth, bots, backtest, simulate, config
+from .api import auth, bots, backtest, simulate, config, ave
 from .core.limiter import limiter
+from .core.database import engine, Base
+
+logger = logging.getLogger(__name__)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Initialize database on startup."""
+    # Import all models to ensure they're registered
+    from .db.models import User, Bot, BotConversation, Backtest, Simulation, Signal
+    
+    # Create tables if they don't exist
+    Base.metadata.create_all(bind=engine)
+    logger.info("Database initialized successfully")
+    
+    yield
+    # Cleanup on shutdown if needed
+

 app = FastAPI(
    title="Randebu Trading Bot API",
    description="AI-powered trading bot platform API",
    version="0.1.0",
+    lifespan=lifespan,
 )

 app.state.limiter = limiter
@@ -26,6 +47,7 @@ app.include_router(bots.router, prefix="/api/bots", tags=["bots"])
 app.include_router(backtest.router, prefix="/api", tags=["backtest"])
 app.include_router(simulate.router, prefix="/api", tags=["simulate"])
 app.include_router(config.router, prefix="/api/config", tags=["config"])
+app.include_router(ave.router, prefix="/api/ave", tags=["ave"])


@app.get("/")
--- a/src/backend/app/services/ave/init.py
+++ b/src/backend/app/services/ave/init.py
@@ -0,0 +1,3 @@
+from .client import AveCloudClient, check_tier_access
+
+__all__ = ["AveCloudClient", "check_tier_access"]
--- a/src/backend/app/services/ave/client.py
+++ b/src/backend/app/services/ave/client.py
@@ -0,0 +1,213 @@
+import httpx
+from typing import List, Dict, Any, Optional
+from datetime import datetime
+
+
+class AveCloudClient:
+    DATA_API_URL = "https://prod.ave-api.com"
+    TRADING_API_URL = "https://bot-api.ave.ai"
+
+    def __init__(self, api_key: str, plan: str = "free"):
+        self.api_key = api_key
+        self.plan = plan
+
+    def _data_headers(self) -> Dict[str, str]:
+        return {"X-API-KEY": self.api_key}
+
+    def _trading_headers(self) -> Dict[str, str]:
+        return {"X-API-KEY": self.api_key, "Content-Type": "application/json"}
+
+    async def get_tokens(
+        self,
+        query: Optional[str] = None,
+        chain: Optional[str] = None,
+        limit: int = 20,
+    ) -> List[Dict[str, Any]]:
+        url = f"{self.DATA_API_URL}/v2/tokens"
+        params = {"limit": limit}
+        if query:
+            params["query"] = query
+        if chain:
+            params["chain"] = chain
+
+        async with httpx.AsyncClient() as client:
+            response = await client.get(
+                url, headers=self._data_headers(), params=params, timeout=30.0
+            )
+            response.raise_for_status()
+            data = response.json()
+            if data.get("status") == 200:
+                return data.get("data", [])
+            raise Exception(f"Failed to fetch tokens: {data}")
+
+    async def get_batch_prices(self, token_ids: List[str]) -> Dict[str, Dict[str, Any]]:
+        url = f"{self.DATA_API_URL}/v2/tokens/price"
+        async with httpx.AsyncClient() as client:
+            response = await client.post(
+                url,
+                headers=self._data_headers(),
+                json={"token_ids": token_ids},
+                timeout=30.0,
+            )
+            response.raise_for_status()
+            data = response.json()
+            if data.get("status") == 200:
+                return data.get("data", {})
+            return {}
+
+    async def get_token_details(self, token_id: str) -> Optional[Dict[str, Any]]:
+        url = f"{self.DATA_API_URL}/v2/tokens/{token_id}"
+        async with httpx.AsyncClient() as client:
+            response = await client.get(url, headers=self._data_headers(), timeout=30.0)
+            response.raise_for_status()
+            data = response.json()
+            if data.get("status") == 200:
+                return data.get("data")
+            return None
+
+    async def get_klines(
+        self,
+        token_id: str,
+        interval: str = "1h",
+        limit: int = 100,
+        start_time: Optional[int] = None,
+        end_time: Optional[int] = None,
+    ) -> List[Dict[str, Any]]:
+        url = f"{self.DATA_API_URL}/v2/klines/token/{token_id}"
+        params = {"interval": interval, "limit": limit}
+        if start_time:
+            params["start_time"] = start_time
+        if end_time:
+            params["end_time"] = end_time
+
+        async with httpx.AsyncClient() as client:
+            response = await client.get(
+                url, headers=self._data_headers(), params=params, timeout=30.0
+            )
+            response.raise_for_status()
+            data = response.json()
+            if data.get("status") == 200:
+                return data.get("data", [])
+            raise Exception(f"Failed to fetch klines: {data}")
+
+    async def get_trending_tokens(
+        self, chain: Optional[str] = None, limit: int = 20
+    ) -> List[Dict[str, Any]]:
+        url = f"{self.DATA_API_URL}/v2/tokens/trending"
+        params = {"limit": limit}
+        if chain:
+            params["chain"] = chain
+
+        async with httpx.AsyncClient() as client:
+            response = await client.get(
+                url, headers=self._data_headers(), params=params, timeout=30.0
+            )
+            response.raise_for_status()
+            data = response.json()
+            if data.get("status") == 200:
+                return data.get("data", [])
+            raise Exception(f"Failed to fetch trending tokens: {data}")
+
+    async def get_token_risk(self, contract_id: str) -> Optional[Dict[str, Any]]:
+        url = f"{self.DATA_API_URL}/v2/contracts/{contract_id}"
+        async with httpx.AsyncClient() as client:
+            response = await client.get(url, headers=self._data_headers(), timeout=30.0)
+            response.raise_for_status()
+            data = response.json()
+            if data.get("status") == 200:
+                return data.get("data")
+            return None
+
+    async def get_chain_quote(
+        self,
+        chain: str,
+        from_token: str,
+        to_token: str,
+        amount: str,
+        slippage: float = 0.5,
+    ) -> Optional[Dict[str, Any]]:
+        url = f"{self.TRADING_API_URL}/v1/chain/quote"
+        payload = {
+            "chain": chain,
+            "from_token": from_token,
+            "to_token": to_token,
+            "amount": amount,
+            "slippage": slippage,
+        }
+        async with httpx.AsyncClient() as client:
+            response = await client.post(
+                url, headers=self._trading_headers(), json=payload, timeout=30.0
+            )
+            response.raise_for_status()
+            data = response.json()
+            if data.get("status") == 200:
+                return data.get("data")
+            return None
+
+    async def get_chain_swap(
+        self,
+        chain: str,
+        from_token: str,
+        to_token: str,
+        amount: str,
+        slippage: float = 0.5,
+        wallet_address: Optional[str] = None,
+    ) -> Optional[Dict[str, Any]]:
+        url = f"{self.TRADING_API_URL}/v1/chain/swap"
+        payload = {
+            "chain": chain,
+            "from_token": from_token,
+            "to_token": to_token,
+            "amount": amount,
+            "slippage": slippage,
+        }
+        if wallet_address:
+            payload["wallet_address"] = wallet_address
+        async with httpx.AsyncClient() as client:
+            response = await client.post(
+                url, headers=self._trading_headers(), json=payload, timeout=60.0
+            )
+            response.raise_for_status()
+            data = response.json()
+            if data.get("status") == 200:
+                return data.get("data")
+            return None
+
+
+def check_tier_access(user_tier: str, feature: str) -> tuple[bool, Optional[str]]:
+    tier_access = {
+        "free": {
+            "data_rest": True,
+            "websocket": False,
+            "chain_wallet": True,
+            "proxy_wallet": False,
+        },
+        "normal": {
+            "data_rest": True,
+            "websocket": False,
+            "chain_wallet": True,
+            "proxy_wallet": True,
+        },
+        "pro": {
+            "data_rest": True,
+            "websocket": True,
+            "chain_wallet": True,
+            "proxy_wallet": True,
+        },
+    }
+
+    if user_tier not in tier_access:
+        user_tier = "free"
+
+    access = tier_access[user_tier]
+    if access.get(feature):
+        return True, None
+
+    upsell_messages = {
+        "websocket": "Upgrade to Pro plan to access WebSocket streaming data. Visit your account settings.",
+        "proxy_wallet": "Upgrade to Normal or Pro plan to access Proxy Wallet functionality. Visit your account settings.",
+    }
+
+    return False, upsell_messages.get(
+        feature, "Upgrade your plan to access this feature."
+    )
Author	SHA1	Message	Date
shokollm	0a2e347fdb	feat: Add database init on startup and documentation - Add lifespan handler to main.py for automatic DB table creation - Expand .env.example with detailed variable documentation - Add AUDIT_REPORT.md with comprehensive product/technical review - Add STRATEGY_SCHEMA.md as single source of truth for strategy config - Remove redundant init_db.py script (DB init now handled by app startup)	2026-04-09 04:49:11 +00:00
shoko	2561759b78	feat: Add deployment documentation and templates (issue #12 ) (#23 )	2026-04-09 01:23:53 +02:00
shoko	b6f99aa8fe	Merge pull request '[Backend] AVE Cloud Integration - Data and Trading APIs' (#22 ) from fix/issue-11 into main	2026-04-08 16:49:13 +02:00
shokollm	3806af3e23	feat(backend): Implement AVE Cloud integration for Data and Trading APIs - Add tier field to User model for plan detection (free/normal/pro) - Create AVE Cloud API client with all Data API endpoints: - Token search (GET /v2/tokens) - Batch prices (POST /v2/tokens/price) - Token details (GET /v2/tokens/{id}) - Kline data (GET /v2/klines/token/{id}) - Trending tokens (GET /v2/tokens/trending) - Token risk (GET /v2/contracts/{id}) - Add Trading API endpoints: - Chain wallet quote (POST /v1/chain/quote) - Chain wallet swap (POST /v1/chain/swap) - Add tier gating with upsell messaging for Pro features - Handle rate limiting gracefully with 429 responses - Add Pydantic schemas for AVE API requests/responses Fixes #11	2026-04-08 14:41:40 +00:00
shoko	a892a403fb	Merge pull request '[Frontend] Components - Chat UI, Dashboard, Visualizations' (#21 ) from fix/issue-10 into main	2026-04-08 16:23:23 +02:00