randebu/docs/IMPLEMENTATION_PLAN.md

AVE Trading Bot - Implementation Plan

Project Overview: An AI-powered trading bot platform where users create and manage trading bots through natural language chat, with backtesting and simulation capabilities.

---

1. Concept & Vision

1.1 What We're Building

A prompt-driven AI trading bot platform that democratizes agentic trading by letting anyone create automated trading strategies through conversation - no coding required.

Core Promise: "Create a trading bot by chatting with AI. Test it risk-free. Deploy when you're ready."

1.2 Target Audience

• People familiar with trading but not agentic/automated trading
• Want to learn agentic concepts without high barrier to entry
• Have money to trade but limited technical skills
• Age: Productive age (working adults)
• Tech-savvy: Low to moderate - can't run their own agent locally

1.3 Core Experience

Chat-first interface where users:

1. Describe trading strategies in natural language
2. AI interprets and creates bot configuration
3. User can modify by continuing the conversation
4. Run backtests to validate strategy
5. Run simulations to see real-time signals
6. Deploy to trade live (future phase)

Multi-bot support: Up to 3 bots per user, selectable in chat

---

2. Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    FRONTEND (Svelte)                         │
│  - Chat interface (bot creation/modification)                 │
│  - Bot selector (max 3 bots)                               │
│  - Backtest results visualization                           │
│  - Simulation signals dashboard                             │
└─────────────────────────────────────────────────────────────┘
                              ↕
┌─────────────────────────────────────────────────────────────┐
│                 BACKEND (Python FastAPI)                   │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐   │
│  │ Auth        │  │ Bot Config  │  │ User Management │   │
│  │ (JWT)       │  │ (CRUD)      │  │                 │   │
│  └─────────────┘  └─────────────┘  └─────────────────┘   │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐   │
│  │ AI Agent    │  │ Strategy    │  │ Execution       │   │
│  │ (CrewAI)    │  │ Compiler    │  │ Engine          │   │
│  └─────────────┘  └─────────────┘  └─────────────────┘   │
│  ┌─────────────┐  ┌─────────────┐                         │
│  │ Backtest    │  │ Simulate    │                         │
│  │ Engine      │  │ Engine      │                         │
│  └─────────────┘  └─────────────┘                         │
└─────────────────────────────────────────────────────────────┘
                              ↕
┌─────────────────────────────────────────────────────────────┐
│                   EXTERNAL SERVICES                         │
│  ┌─────────────────────┐  ┌────────────────────────────┐  │
│  │ SQLite              │  │ AVE Cloud APIs             │  │
│  │ - users             │  │ - Data API (klines, prices)│  │
│  │ - bots              │  │ - Trading API (chain wallet│  │
│  │ - signals           │  │ - Proxy wallet (Pro tier) │  │
│  │ - backtests         │  └────────────────────────────┘  │
│  │ - simulations       │  ┌────────────────────────────┐  │
│  └─────────────────────┘  │ MiniMax API               │  │
│                            │ (Anthropic format)       │  │
│                            └────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

---

3. Tech Stack

Layer	Technology	Rationale
Frontend	Svelte + TypeScript	No Next.js, good DX, lightweight
Backend	Python FastAPI	Phase 1 - quick to prototype
Backend (Phase 2)	Bun/TypeScript	Performance, single language
AI Agent	CrewAI + MiniMax	Multi-agent orchestration
LLM	MiniMax (Anthropic format)	User has API key
Database	SQLite	File-based, simple for MVP
Deployment	Self-hosted (Debian)	User's server, subdomain

---

4. Database Schema

4.1 Tables

-- Users table
CREATE TABLE users (
    id TEXT PRIMARY KEY,           -- UUID
    email TEXT UNIQUE NOT NULL,
    password_hash TEXT NOT NULL,  -- bcrypt hashed
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Bots table (max 3 per user)
CREATE TABLE bots (
    id TEXT PRIMARY KEY,           -- UUID
    user_id TEXT NOT NULL,
    name TEXT NOT NULL,
    description TEXT,              -- AI-generated description
    strategy_config JSON NOT NULL, -- The trading strategy
    llm_config JSON NOT NULL,     -- Model, temperature, etc.
    status TEXT DEFAULT 'draft',  -- draft, active, paused
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(id)
);

-- Bot conversations (chat history)
CREATE TABLE bot_conversations (
    id TEXT PRIMARY KEY,
    bot_id TEXT NOT NULL,
    role TEXT NOT NULL,            -- user, assistant, system
    content TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (bot_id) REFERENCES bots(id)
);

-- Backtest results
CREATE TABLE backtests (
    id TEXT PRIMARY KEY,
    bot_id TEXT NOT NULL,
    started_at TIMESTAMP NOT NULL,
    ended_at TIMESTAMP,
    status TEXT NOT NULL,          -- running, completed, failed
    config JSON NOT NULL,         -- Backtest parameters
    result JSON,                  -- Final results
    FOREIGN KEY (bot_id) REFERENCES bots(id)
);

-- Simulation results
CREATE TABLE simulations (
    id TEXT PRIMARY KEY,
    bot_id TEXT NOT NULL,
    started_at TIMESTAMP NOT NULL,
    status TEXT NOT NULL,          -- running, stopped
    config JSON NOT NULL,          -- Simulation parameters
    signals JSON,                  -- Generated signals
    FOREIGN KEY (bot_id) REFERENCES bots(id)
);

-- Signals log (for both backtest and simulate)
CREATE TABLE signals (
    id TEXT PRIMARY KEY,
    bot_id TEXT NOT NULL,
    run_id TEXT NOT NULL,          -- backtest_id or simulation_id
    signal_type TEXT NOT NULL,     -- buy, sell, hold
    token TEXT NOT NULL,
    price REAL NOT NULL,
    confidence REAL,               -- AI confidence %
    reasoning TEXT,                -- Why this signal
    executed BOOLEAN DEFAULT FALSE, -- If actually executed
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (bot_id) REFERENCES bots(id)
);

4.2 Indexes

CREATE INDEX idx_bots_user_id ON bots(user_id);
CREATE INDEX idx_conversations_bot_id ON bot_conversations(bot_id);
CREATE INDEX idx_backtests_bot_id ON backtests(bot_id);
CREATE INDEX idx_simulations_bot_id ON simulations(bot_id);
CREATE INDEX idx_signals_bot_id ON signals(bot_id);
CREATE INDEX idx_signals_run_id ON signals(run_id);

---

5. API Endpoints

5.1 Auth Routes

Method	Endpoint	Description
POST	/api/auth/register	Register new user
POST	/api/auth/login	Login, returns JWT
POST	/api/auth/logout	Logout (invalidate token)
GET	/api/auth/me	Get current user

5.2 Bot Routes

Method	Endpoint	Description
GET	/api/bots	List user's bots (max 3)
POST	/api/bots	Create new bot
GET	/api/bots/{id}	Get bot details
PUT	/api/bots/{id}	Update bot
DELETE	/api/bots/{id}	Delete bot
POST	/api/bots/{id}/chat	Send message to bot
GET	/api/bots/{id}/history	Get chat history

5.3 Backtest Routes

Method	Endpoint	Description
POST	/api/bots/{id}/backtest	Start backtest
GET	/api/bots/{id}/backtest/{run_id}	Get backtest status/results
GET	/api/bots/{id}/backtests	List all backtests for bot
POST	/api/bots/{id}/backtest/{run_id}/stop	Stop running backtest

5.4 Simulation Routes

Method	Endpoint	Description
POST	/api/bots/{id}/simulate	Start simulation
GET	/api/bots/{id}/simulate/{run_id}	Get simulation status/signals
GET	/api/bots/{id}/simulations	List all simulations for bot
POST	/api/bots/{id}/simulate/{run_id}/stop	Stop simulation

5.5 Config Routes

Method	Endpoint	Description
GET	/api/config/chains	Get supported chains
GET	/api/config/tokens	Get common tokens

---

6. CrewAI Agent Design

6.1 Agent Roles

# For parsing user intent → strategy config
trading_designer = Agent(
    role="Trading Strategy Designer",
    goal="Design clear, executable trading strategies from natural language",
    backstory="Expert in DeFi trading with deep knowledge of indicators, "
              "tokenomics, and market patterns. You specialize in translating "
              "user requirements into precise trading rules.",
)

# For validating strategy feasibility
strategy_validator = Agent(
    role="Strategy Validator",
    goal="Ensure strategies are realistic and well-formed",
    backstory="Risk management specialist who checks if strategies "
              "are implementable and identifies potential issues.",
)

# For generating explanations
strategy_explainer = Agent(
    role="Strategy Explainer",
    goal="Make complex strategies understandable",
    backstory="Education specialist who simplifies trading concepts "
              "for beginners without losing accuracy.",
)

6.2 Default Crew for Bot Chat

trading_crew = Crew(
    agents=[trading_designer, strategy_validator, strategy_explainer],
    tasks=[understand_intent, validate_strategy, update_config, explain_changes],
    process=Process.sequential
)

6.3 Strategy Config Schema

{
  "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
  }
}

---

7. Backtest Engine

7.1 Algorithm

1. Parse strategy_config → conditions + actions
2. Fetch historical klines from AVE Cloud API
   - GET /v2/klines/token/{token-id} or /v2/klines/pair/{pair-id}
   - Time range: user-specified
3. For each time point in klines:
   a. Check if any condition is met
   b. If met → generate signal (buy/sell/hold)
   c. Simulate portfolio change
   d. Log signal to signals table
4. Calculate metrics:
   - Total return %
   - Win rate (% correct predictions)
   - Max drawdown
   - Sharpe ratio
   - Number of trades
5. Store results in backtests table

7.2 Backtest Response

{
  "id": "backtest-uuid",
  "status": "completed",
  "duration_seconds": 45,
  "config": {
    "token": "PEPE-bsc",
    "timeframe": "1h",
    "start_date": "2024-01-01",
    "end_date": "2024-02-01"
  },
  "results": {
    "total_return": 15.4,
    "win_rate": 62.5,
    "total_trades": 24,
    "buy_signals": 12,
    "sell_signals": 12,
    "max_drawdown": 8.2,
    "sharpe_ratio": 1.45
  },
  "signals": [...]
}

---

8. Simulate Engine

8.1 Algorithm

1. Load bot's strategy_config
2. Start loop (user-initiated):
   a. Fetch current prices for relevant tokens
      - GET /v2/tokens/price (batch, up to 200)
   b. Check if any condition is met
   c. If met:
      - Generate signal with confidence score
      - Log to signals table
      - If auto_execute=true → call trading API
      - Else → notify user
   d. Wait N seconds (configurable, 60s default for free tier)
3. Stop when user stops or max_duration reached

8.2 User Notice

┌─────────────────────────────────────────────────────────────┐
│  ⚠️ Simulation Mode - Free Tier                            │
│                                                             │
│  Using REST polling (every 60s). For real-time signals,    │
│  consider upgrading to Pro tier for WebSocket streams.      │
└─────────────────────────────────────────────────────────────┘

---

9. Frontend Components

9.1 Pages

Route	Purpose
/	Landing or dashboard (if logged in)
/login	Login form
/register	Registration form
/dashboard	Main dashboard (list of bots)
/bot/:id	Bot chat interface
/bot/:id/backtest	Backtest results view
/bot/:id/simulate	Simulation monitor view
/settings	User settings, API keys

9.2 Key Components

Component	Purpose
ChatInterface	Message input, AI responses, chat history
BotCard	Bot preview card for dashboard
BotSelector	Dropdown to select which bot to modify (max 3)
StrategyPreview	Shows parsed strategy config in readable format
SignalChart	Visual representation of signals over time
BacktestChart	Line chart of portfolio value over time
ProUpgradeBanner	Banner shown when feature requires Pro tier
TokenPicker	Search/select tokens for conditions
ConditionBuilder	UI for building price/volume conditions

---

10. Tier Gating

Feature	Free	Normal	Pro
Bot creation (max 3)	✅	✅	✅
Chat interface	✅	✅	✅
Backtest	✅	✅	✅
Simulate (REST polling)	✅	✅	✅
Simulate (WebSocket)	❌	❌	✅
Chain Wallet trading	✅	✅	✅
Proxy Wallet trading	❌	✅	✅
Scheduled bot runs	❌	❌	✅

---

11. Environment Configuration

11.1 Backend .env

# Database
DATABASE_URL=sqlite:///./data/app.db

# Auth
SECRET_KEY=your-super-secret-key-change-in-production
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=1440

# MiniMax
MINIMAX_API_KEY=your-minimax-api-key
MINIMAX_MODEL=MiniMax-Text-01

# AVE Cloud
AVE_API_KEY=your-ave-cloud-api-key
AVE_API_PLAN=free

# Server
HOST=0.0.0.0
PORT=8000
DEBUG=false

11.2 Frontend .env

VITE_API_URL=https://bot.yourdomain.com/api
VITE_WS_URL=wss://bot.yourdomain.com/ws

---

12. Project Structure

/home/shoko/repositories/randebu/
├── docs/
│   ├── ave-hackathon-research.md      # AVE Cloud research
│   ├── scripts/                       # AVE Cloud API scripts
│   │   ├── ave_data_rest.py
│   │   ├── ave_data_wss.py
│   │   ├── ave_trade_rest.py
│   │   └── requirements.txt
│   └── IMPLEMENTATION_PLAN.md         # This document
├── src/
│   ├── backend/                       # Python FastAPI backend
│   │   ├── app/
│   │   │   ├── api/
│   │   │   │   ├── __init__.py
│   │   │   │   ├── auth.py
│   │   │   │   ├── bots.py
│   │   │   │   ├── backtest.py
│   │   │   │   ├── simulate.py
│   │   │   │   └── config.py
│   │   │   ├── core/
│   │   │   │   ├── __init__.py
│   │   │   │   ├── config.py
│   │   │   │   ├── security.py
│   │   │   │   └── database.py
│   │   │   ├── db/
│   │   │   │   ├── __init__.py
│   │   │   │   ├── models.py
│   │   │   │   └── schemas.py
│   │   │   ├── services/
│   │   │   │   ├── __init__.py
│   │   │   │   ├── ai_agent/
│   │   │   │   │   ├── __init__.py
│   │   │   │   │   ├── crew.py
│   │   │   │   │   └── llm_connector.py
│   │   │   │   ├── backtest/
│   │   │   │   │   ├── __init__.py
│   │   │   │   │   └── engine.py
│   │   │   │   └── simulate/
│   │   │   │       ├── __init__.py
│   │   │   │       └── engine.py
│   │   │   └── main.py
│   │   ├── requirements.txt
│   │   ├── run.py
│   │   └── setup.py
│   └── frontend/                      # Svelte frontend
│       ├── src/
│       │   ├── lib/
│       │   │   ├── components/
│       │   │   ├── stores/
│       │   │   └── api/
│       │   ├── routes/
│       │   └── app.html
│       ├── svelte.config.js
│       ├── package.json
│       └── vite.config.ts
└── README.md

---

13. Deployment

13.1 Prerequisites

• Debian server with 8GB RAM, 4 cores
• Python 3.10+
• Node.js 18+
• Nginx
• SSL certificate (Let's Encrypt)

13.2 Deployment Steps

1. Clone repo to server
   git clone https://github.com/your-repo/ave-trading-bot.git

2. Setup Python virtual environment
   cd ave-trading-bot/src/backend
   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt

3. Setup SQLite database
   mkdir -p data

4. Configure Nginx (reverse proxy to localhost:8000)

5. Setup systemd service for auto-restart

6. Start backend service

7. Build frontend
   cd ../frontend
   npm install
   npm run build

8. Serve frontend via Nginx

---

14. Phase 1 Deliverables

Deliverable	Status
User auth (register, login, logout)	☐
Bot CRUD (max 3 per user)	☐
Chat interface with CrewAI	☐
Strategy parser (NL → config)	☐
Backtest engine + API	☐
Backtest results visualization	☐
Simulate engine + API	☐
Simulation signals dashboard	☐
AVE Cloud Data API integration	☐
AVE Cloud Trading API integration (Chain Wallet)	☐
Free tier detection + upsell messaging	☐
SQLite persistence	☐
Environment config via env vars	☐
Nginx deployment config	☐
Systemd service config	☐
Working deployment on subdomain	☐

---

15. Phase 2 Considerations

Feature	Notes
Proxy Wallet	Requires Normal+ tier
WebSocket streams	Requires Pro tier
Scheduled jobs	Need cron/background worker
Multiple coordinated bots	Portfolio management
Local agent runner	For advanced users
Bun/TypeScript backend	Migration from Python

---

16. Open Questions

• Server SSH access details (to be provided later)
• Domain/subdomain DNS configuration (to be set up)
• MiniMax API key (provided via env var)
• AVE Cloud API key (provided via env var)

---

17. Appendix: Supported Conditions (MVP)

Condition Type	Description	Parameters
price_drop	Token price drops by X%	threshold, timeframe
price_rise	Token price rises by X%	threshold, timeframe
volume_spike	Trading volume increases X%	threshold, timeframe
price_level	Price crosses above/below X	price, direction

---

Document Version: 1.0
Created: 2026-04-05