randebu/docs/STRATEGY_SCHEMA.md

# 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*