> For the complete documentation index, see [llms.txt](https://statalpha.gitbook.io/statalpha-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://statalpha.gitbook.io/statalpha-docs/stats/trend.md).

# Trend

The **Trend** module identifies the current **market regime** (bullish, bearish, sideways) and estimates the **probability of reversals or regime transitions**.\
It integrates multiple technical indicators (EMA alignment, MACD, RSI, ADX, Bollinger Bandwidth, slope, and z-score) into a unified market-state model.

***

## Concept

* Detects trend direction and strength using multi-indicator consensus.
* Evaluates **bullish**, **bearish**, or **sideways** regimes based on moving average and momentum alignment.
* Provides a **reversal warning** when exhaustion conditions appear (e.g., overbought RSI, cooling MACD histogram, falling ADX).
* Includes **multi-timeframe consensus** (short, medium, long) and a **reversal backtest** tool to evaluate the heuristic’s historical accuracy.

***

## Parameters

| Parameter                 | Type   | Description                                                          |
| ------------------------- | ------ | -------------------------------------------------------------------- |
| `symbol`                  | string | Target asset (e.g. `AAPL`, `BTCUSD`)                                 |
| `start_date` / `end_date` | string | Analysis period (`YYYY-MM-DD`)                                       |
| `time_window`             | string | Predefined range (e.g. `3M`, `6M`, `12M`, `24M`, `5Y`)               |
| `horizon_days`            | int    | Lookahead window for reversal backtest (default `3`)                 |
| `threshold_pct`           | float  | Required counter‑move threshold for a valid reversal (default `1.0`) |

***

## Endpoints

| Endpoint                             | Description                                                                         |
| ------------------------------------ | ----------------------------------------------------------------------------------- |
| `GET /stats/trend/state`             | Returns the current market regime, confidence, and reversal assessment              |
| `GET /stats/trend/consensus`         | Multi‑timeframe consensus (short/medium/long) with sideways score and breakout bias |
| `GET /stats/trend/reversal/backtest` | Backtests reversal heuristic on historical data                                     |
| `GET /stats/trend/documentation`     | Returns endpoint and field descriptions for developers                              |

***

## Example Requests

### 1. Current regime & reversal assessment

```bash
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://api.statalpha.market/stats/trend/state?symbol=AAPL&time_window=6M"
```

### 2. Multi-timeframe consensus

```bash
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://api.statalpha.market/stats/trend/consensus?symbol=AAPL&time_window=12M"
```

### 3. Reversal heuristic backtest

```bash
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://api.statalpha.market/stats/trend/reversal/backtest?symbol=TSLA&time_window=12M&horizon_days=3&threshold_pct=1.5"
```

***

## Example Response (trend state)

```json
{
  "symbol": "AAPL",
  "time_window": "6M",
  "regime": "bullish",
  "confidence_pct": 82.3,
  "reversal_warning": {
    "likely": true,
    "direction": "bearish",
    "reasons": ["RSI overbought (>=70)", "MACD momentum cooling"]
  },
  "metrics": {
    "close": 232.47,
    "ema50": 228.15,
    "ema200": 216.90,
    "rsi14": 71.3,
    "adx14": 24.8,
    "macd": 1.42,
    "macd_signal": 1.28,
    "macd_hist": 0.14,
    "bb_width20": 0.083,
    "slope50_pct_per_day": 0.042,
    "close_z20": 1.52
  }
}
```

***

## Interpretation

| Metric                      | Meaning                                                        |
| --------------------------- | -------------------------------------------------------------- |
| **regime**                  | Current dominant state (`bullish`, `bearish`, `sideways`)      |
| **confidence\_pct**         | Strength of the detected regime (0–100%)                       |
| **reversal\_warning**       | Possible near-term reversal, direction, and reasons            |
| **metrics**                 | Key technical values supporting the regime classification      |
| **sideways.score\_0\_3**    | Degree of sideways compression (only for sideways markets)     |
| **sideways.breakout\_bias** | Likely breakout direction if sideways (`up` / `down`)          |
| **consensus.overall**       | Majority signal across short, medium, and long-term timeframes |

***

## Notes

* The trend model is heuristic and **not predictive**, but provides probabilistic context for trend strength and potential regime shifts.
* Confidence blends multiple components (MA alignment, slope, MACD, ADX).
* Sideways detection combines low ADX, narrow Bollinger Bands, and flat slope.
* Cached responses are returned for repeated queries for consistency.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://statalpha.gitbook.io/statalpha-docs/stats/trend.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.