ai/gateway/knowledge/strategy-development.md

---
description: "PandasStrategy class API, order placement, backtesting, and paper trading patterns for automated crypto strategy development."
---

# Strategy Development Guide

Strategies on Dexorder are `PandasStrategy` subclasses that receive a live stream of OHLCV bars and call `self.buy()` / `self.sell()` / `self.flatten()` to place orders.

See [`api-reference`](api-reference.md) for the DataAPI and ChartingAPI used in research scripts. For indicator calculations, see [`pandas-ta-reference`](pandas-ta-reference.md).

---

## PandasStrategy API

```python
from dexorder.nautilus.pandas_strategy import PandasStrategy, PandasStrategyConfig

class MyStrategy(PandasStrategy):

    def evaluate(self, dfs: dict[str, pd.DataFrame]) -> None:
        """Called after every new bar across all feeds.

        Args:
            dfs: dict mapping feed_key → pd.DataFrame
                 Columns: timestamp (ns), open, high, low, close, volume,
                          buy_vol, sell_vol, open_interest
                 Rows accumulate over time — last row = latest bar.
        """
        df = dfs.get("BTC/USDT.BINANCE:300")
        if df is None or len(df) < 20:
            return  # not enough data yet

        close = df["close"]
        # ... compute signals ...

        if buy_signal:
            self.buy(quantity=0.1)
        elif sell_signal:
            self.sell(quantity=0.1)
```

### Feed key format

`"{SYMBOL.EXCHANGE}:{period_seconds}"` — e.g. `"BTC/USDT.BINANCE:900"` for 15-minute bars.

Access all feeds via `self.config.feed_keys` (tuple of strings).

### Order methods

```python
self.buy(quantity: float, feed_key: str = None)
self.sell(quantity: float, feed_key: str = None)
self.flatten(feed_key: str = None)   # close all open positions
```

If `feed_key` is omitted, the first feed in `feed_keys` is used. `quantity` is in base currency units (e.g. 0.1 BTC).

### Available data

Strategies may only use data in the `dfs` feeds: crypto OHLCV + buy/sell volume split + open interest. The following are **not available**:
- TradFi data (equities, forex, bonds, options, macro indicators)
- Alternative data (news, social sentiment, on-chain metrics, economic calendars)

---

## Using pandas_ta

Use `import pandas_ta as ta` for all indicator calculations. Never write manual `rolling()` or `ewm()` implementations.

```python
import pandas_ta as ta

rsi = ta.rsi(df["close"], length=14)
macd_df = ta.macd(df["close"], fast=12, slow=26, signal=9)
hist = macd_df.iloc[:, 2]   # histogram column

ema = ta.ema(df["close"], length=20)
atr = ta.atr(df["high"], df["low"], df["close"], length=14)
```

See [`pandas-ta-reference`](pandas-ta-reference.md) for the full indicator catalog and multi-output column extraction patterns.

---

## Using Custom Indicators

Prefer referencing a custom indicator that already exists in the `indicator` category rather than duplicating the logic inline. Custom indicators appear on the user's chart, making the signal transparent.

```python
import pandas_ta as ta

def evaluate(self, dfs):
    df = dfs.get("BTC/USDT.BINANCE:3600")
    if df is None or len(df) < 20:
        return

    vw_rsi = ta.custom_vw_rsi(df["close"], df["volume"], length=14)
    if vw_rsi is None or vw_rsi.isna().all():
        return

    if vw_rsi.iloc[-1] < 30:
        self.buy(0.01)
    elif vw_rsi.iloc[-1] > 70:
        self.sell(0.01)
```

Custom indicator names follow the pattern `ta.custom_{sanitized_name}`. See [`indicator-development`](indicator-development.md) for naming rules and how to create custom indicators.

---

## Strategy Metadata

When writing a strategy with `PythonWrite(category="strategy", ...)`, always provide:

| Field | Required | Description |
|-------|----------|-------------|
| `description` | yes | One-sentence summary |
| `details` | yes | Full markdown: algorithm, entry/exit logic, parameters, data feeds, position sizing. Enough detail to reproduce the code from scratch. |

```python
PythonWrite(
    category="strategy",
    name="RSI Mean Reversion",
    description="Buy oversold, sell overbought based on RSI(14) on BTC/USDT 5m bars.",
    details="""## RSI Mean Reversion
...""",
    code="""...""",
    metadata={
        "data_feeds": [
            {"symbol": "BTC/USDT.BINANCE", "period_seconds": 300, "description": "BTC/USDT 5m"}
        ],
        "parameters": {
            "rsi_length": {"default": 14, "description": "RSI lookback period"},
            "oversold":   {"default": 30, "description": "Buy threshold"},
            "overbought": {"default": 70, "description": "Sell threshold"},
            "trade_qty":  {"default": 0.01, "description": "Trade quantity in BTC"}
        }
    }
)
```

---

## Backtest Workflow

1. **Check existing indicators** first: `PythonList(category="indicator")` — reuse signals already on the chart.
2. **Write** the strategy: `PythonWrite(...)` — runs against synthetic data automatically.
3. **Run a backtest** targeting 100,000–200,000 bars (max 5 years):
   ```
   BacktestStrategy(
       strategy_name="RSI Mean Reversion",
       feeds=[{"symbol": "BTC/USDT.BINANCE", "period_seconds": 900}],
       from_time="2023-01-01",
       to_time="2024-12-31",
       initial_capital=10000
   )
   ```
4. **Interpret results**:
   - `summary.total_return` — total fractional return (0.15 = +15%)
   - `summary.sharpe_ratio` — annualized Sharpe (>1.0 good, >2.0 excellent)
   - `summary.max_drawdown` — maximum peak-to-trough loss
   - `summary.win_rate` — fraction of profitable trades
   - `statistics.profit_factor` — gross profit / gross loss (>1.5 good)
5. **Iterate** with `PythonEdit`, re-run backtest.
6. **Activate** (paper first): `ActivateStrategy(..., paper=True)`

### Bar resolution and backtest window

Choose the resolution appropriate to the strategy's signal frequency, then set the date range to hit 100k–200k bars:

| Resolution | ~100k bars | ~200k bars |
|---|---|---|
| 5m | 1 year | 2 years |
| 15m | 2.9 years | 5 years |
| 1h | cap at 5 yr (≈44k bars) | — |
| 4h | cap at 5 yr (≈11k bars) | — |

---

## Strategy Patterns

### Trend following

Follow sustained price movements using moving average crossovers, breakout of price channels, or trend-direction filters:

```python
ema_fast = ta.ema(df["close"], length=20)
ema_slow = ta.ema(df["close"], length=50)
bullish = ema_fast.iloc[-1] > ema_slow.iloc[-1]
crossover = ema_fast.iloc[-2] <= ema_slow.iloc[-2]

if bullish and crossover:
    self.buy(qty)
```

### Mean reversion

Profit from price returning to an average after extremes:

```python
rsi = ta.rsi(df["close"], length=14)
if rsi.iloc[-1] < 30:
    self.buy(qty)
elif rsi.iloc[-1] > 70:
    self.sell(qty)
```

### Multi-timeframe confluence

Use a higher-timeframe trend filter with a lower-timeframe entry signal:

```python
df_4h = dfs.get("BTC/USDT.BINANCE:14400")
df_15m = dfs.get("BTC/USDT.BINANCE:900")
if df_4h is None or df_15m is None:
    return

ema_4h = ta.ema(df_4h["close"], length=20)
bullish_trend = df_4h["close"].iloc[-1] > ema_4h.iloc[-1]

macd_df = ta.macd(df_15m["close"])
hist = macd_df.iloc[:, 2]

if bullish_trend and hist.iloc[-1] > 0 and hist.iloc[-2] <= 0:
    self.buy(qty, feed_key="BTC/USDT.BINANCE:900")
```

---

## Important Rules

- **`evaluate()` must be fast, lightweight, and deterministic** — no model inference, file I/O, network calls, or randomness. It runs on every bar during backtests over potentially hundreds of thousands of bars.
- **No LLM calls inside strategies** — strategies must be fully reproducible.
- **Guard for insufficient data** — always check `len(df) >= min_required` before computing indicators with a lookback period.
- **Use `.get()` for feeds** — multi-feed strategies may have feeds missing during warm-up.
- **Size conservatively** — a typical trade quantity is `0.001–0.01 * initial_capital / price`.
- **No `import` from `dexorder` inside `evaluate()`** — the strategy file is exec'd in a sandbox; PandasStrategy and pandas_ta are pre-loaded.

---

## Performance Metrics Reference

| Metric | Good | Excellent |
|---|---|---|
| Sharpe ratio | > 1.0 | > 2.0 |
| Profit factor | > 1.5 | > 2.0 |
| Max drawdown | < 20% | < 10% |
| Win rate | context-dependent | — |

A strategy with a lower win rate can still be profitable if winners are larger than losers (profit factor > 1). Focus on Sharpe and max drawdown as primary quality metrics.

### Avoiding overfitting

- Do not optimize parameters on the same data used for validation
- Use a held-out out-of-sample period to verify results
- Prefer fewer parameters — simpler strategies generalize better
- Walk-forward analysis: re-fit on a rolling window, evaluate on the next

---

## See Also

- [`pandas-ta-reference`](pandas-ta-reference.md) — Indicator catalog and usage examples
- [`indicator-development`](indicator-development.md) — Creating custom indicators
- [`api-reference`](api-reference.md) — DataAPI reference (for research scripts)
- [`usage-examples`](usage-examples.md) — Research script patterns