/hurst-exponent

name: hurst-exponent
description: Estimate the Hurst exponent for a single ticker's daily log returns using rescaled-range (R/S) analysis, and classify the series as mean_reverting (H < 0.45), random_walk (H in [0.45, 0.55]), or trending (H > 0.55). Reports per-block R/S values and a block-bootstrap confidence band around H. Companion to pairs-scanner: pairs handles two-name cointegration, hurst handles single-name persistence. Answers "is this name a mean-reversion setup or a momentum setup?" Requires Stocks Basic. Runs on the free tier.

hurst-exponent

You hand over a ticker. The skill pulls 2 years of daily closes, computes log returns, runs R/S analysis across a log-spaced set of block sizes, and fits `log(R/S) = c + H * log(n)` by OLS. H is the slope. Classifies the series based on where H falls and adds a bootstrap confidence band so the reader can judge whether the classification is robust.

Interpretation

• **H < 0.45**: **mean-reverting**. Prices push back toward a

centerline. Pair strategies, range trading, and z-score entries historically have structural edge. Utilities and staples names tend here.

• **H in [0.45, 0.55]**: **random walk**. No persistence. Neither

trend nor mean-reversion strategies have edge from the tape alone.

• **H > 0.55**: **trending / momentum**. Prices tend to keep going.

Breakout strategies and trend-following have structural edge. Growth names in a strong run often show this.

When to invoke

• "Is AAPL trending or reverting right now?"
• Deciding whether to use pairs-scanner or a breakout entry on a

name

• Screening a watchlist for mean-reversion candidates before running

z-score entries

• The user says "Hurst", "R/S", "persistence", "mean reverting or

trending"

Not for: cross-sectional pair analysis (that's pairs-scanner). Not for regime detection at higher frequencies (this uses daily returns; intraday persistence would need tick data).

What you need

• A ticker (`--ticker`)
• `MASSIVE_API_KEY` exported
• Stocks Basic minimum

Optional:

• `--lookback-days` (default 504, ~2 years). Longer = tighter H but

more risk of masking a recent regime shift. Minimum 80.

• `--n-bootstrap` (default 100): block-bootstrap iterations for the

confidence band. Set to 0 to skip.

• `--seed` (default 42): RNG seed.

What you get back

Two output layers from one run.

**Layer 1: canonical JSON**. `hurst_exponent`, `classification` (mean_reverting / random_walk / trending), `reasoning`, `bootstrap` with p5/p50/p95 and n_valid, `per_block_rs` with (block_size, rs_mean) entries showing how R/S scales with block size, plus lookback and n_returns.

**Layer 2: rendered note**. Header + H + classification tag, bootstrap band, per-block R/S table, one-line Take with strategy implication.

How it works

1. **Pull daily closes** for the ticker over `lookback_days * 1.6` calendar days. 2. **Log returns** = diff of log(close). 3. **Block sizes**: 12 log-spaced values from min_block=10 to max_block=N/4. N/4 is the standard upper bound; going higher gives fewer blocks per size and destabilizes the regression. 4. **R/S per block size n**:

• Partition returns into non-overlapping blocks of length n.
• For each block: center by mean, take cumulative sum, R = max -

min of the cumsum, S = sample std. R/S = R/S.

• Mean R/S across blocks.

5. **OLS on log-log**: fit `log(R/S(n)) = c + H * log(n)`. H is the slope. 6. **Bootstrap**: block-bootstrap (block length 20) 100 times, refit H each iteration, report p5/p50/p95 of the H distribution. 7. **Classify** by fixed thresholds (0.45 and 0.55) so the buckets are stable across runs.

Foundations used

• [`massive-api-patterns`](../massive-api-patterns) for REST auth,

retry, and daily aggs.

Output mode: note

Narrative note with a small per-block table. A single number (H) plus its confidence band and per-block trace reads better as a short structured note than a table.

Endpoints used

• `GET /v2/aggs/ticker/{T}/range/1/day/{from}/{to}?adjusted=true`

One call per run.

Doesn't handle (yet)

• **Multi-scale Hurst**. Only one H per run. A rolling Hurst over

N-day windows would show regime changes; queued as a companion.

• **Detrended fluctuation analysis (DFA)**. R/S is the classic

method; DFA is more robust to non-stationarities. Queued.

• **Fractional differencing**. If you want to trade on the estimate,

the natural next step is fractional integration order d = H - 0.5. Beyond this skill's scope.

• **Cross-asset Hurst comparison**. No "AAPL's H vs sector median H."

Queued.

These are clean PR extensions.