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

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

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

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

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

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