MCPInstall

mean-reversion

Mean-reversion strategy tools including Hurst exponent, half-life estimation, z-score signals, ADF testing, and Ornstein-Uhlenbeck modeling

Installs
495
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/agiprolabs/claude-trading-skills --skill mean-reversion
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads mean-reversion automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Mean Reversion

Mean reversion is the statistical tendency for prices, spreads, or other financial variables to return toward a long-run average after deviating from it. A mean-reverting series overshoots its mean, then corrects back -- creating predictable oscillations that can be traded.

When Mean Reversion Works

  • Ranging markets: Sideways price action with clear support/resistance
  • Pairs spreads: Spread between cointegrated assets reverts to equilibrium
  • Oversold/overbought extremes: RSI, Bollinger Band, or z-score extremes in stationary series
  • Funding rate arbitrage: Perpetual funding rates revert to baseline
  • Stablecoin depegs: Classic mean-reversion opportunity (peg = known mean)
  • Post-dump recovery: Brief mean-reversion windows after initial PumpFun dumps

When Mean Reversion Fails

  • Strong trending markets (most crypto most of the time)
  • Regime changes: what was stationary becomes non-stationary
  • Structural breaks: token migration, protocol upgrade, delistings
  • Low liquidity: wide spreads consume mean-reversion profits

Testing for Mean Reversion

Before trading mean reversion, you must statistically confirm the series is mean-reverting. Three complementary tests:

1. Augmented Dickey-Fuller (ADF) Test

Tests the null hypothesis that a series has a unit root (non-stationary).

from scipy import stats
import numpy as np

def adf_test(series: np.ndarray, max_lag: int = 0) -> dict:
    """Run ADF test. Reject null (p < 0.05) → stationary → mean-reverting."""
    # See references/statistical_tests.md for full implementation
    # Use statsmodels.tsa.stattools.adfuller for production
    pass
  • p < 0.01: Strong evidence of stationarity
  • p < 0.05: Evidence of stationarity
  • p > 0.10: Cannot reject unit root -- likely non-stationary

2. Hurst Exponent

Measures the long-range dependence of a time series.

Hurst ValueInterpretationTrading Implication
H < 0.5Mean-revertingTrade mean reversion
H = 0.5Random walkNo edge
H > 0.5TrendingTrade momentum
def hurst_exponent(series: np.ndarray) -> float:
    """Compute Hurst exponent via R/S method. H < 0.5 → mean-reverting."""
    # See references/statistical_tests.md for full R/S algorithm
    pass

3. Variance Ratio Test

Compares variance of multi-period returns to single-period variance.

  • VR < 1: Negative autocorrelation (mean-reverting)
  • VR = 1: Random walk
  • VR > 1: Positive autocorrelation (trending)
def variance_ratio(series: np.ndarray, q: int = 5) -> float:
    """Compute variance ratio at horizon q. VR < 1 → mean-reverting."""
    returns = np.diff(np.log(series))
    var_1 = np.var(returns)
    returns_q = np.diff(np.log(series[::q]))
    var_q = np.var(returns_q)
    return var_q / (q * var_1)

See references/statistical_tests.md for complete implementations and interpretation guides.


Half-Life Estimation

The half-life tells you how many periods it takes for a deviation to decay to half its size. This is the single most important parameter for mean-reversion trading.

AR(1) Regression Method

Fit the autoregressive model: delta_X_t = alpha + beta * X_{t-1} + epsilon

def half_life(series: np.ndarray) -> float:
    """Estimate mean-reversion half-life from AR(1) regression.

    Returns:
        Half-life in periods. Negative means non-mean-reverting.
    """
    y = np.diff(series)
    x = series[:-1]
    x = np.column_stack([np.ones(len(x)), x])
    beta = np.linalg.lstsq(x, y, rcond=None)[0][1]
    if beta >= 0:
        return -1.0  # Not mean-reverting
    return -np.log(2) / np.log(1 + beta)

Using Half-Life

ParameterRule of Thumb
Lookback window2x half-life
Holding period1x half-life
Maximum hold3x half-life (stop)
Signal recalc0.5x half-life

Z-Score Signal Framework

The z-score normalizes the deviation from the mean, providing standardized entry/exit signals.

z = (price - rolling_mean) / rolling_std

Signal Rules

ConditionSignalAction
z < -2.0BuyEnter long (price below mean)
z > +2.0SellEnter short (price above mean)
z crosses 0ExitClose position (returned to mean)
abs(z) > 3.0StopClose position (reversion failed)

Lookback Window

Set the rolling window to approximately 2x the half-life:

def z_score_signals(
    prices: np.ndarray,
    lookback: int,
    entry_z: float = 2.0,
    exit_z: float = 0.0,
    stop_z: float = 3.0,
) -> np.ndarray:
    """Generate z-score-based mean-reversion signals.

    Returns:
        Array of signals: 1 (long), -1 (short), 0 (flat).
    """
    rolling_mean = pd.Series(prices).rolling(lookback).mean().values
    rolling_std = pd.Series(prices).rolling(lookback).std().values
    z = (prices - rolling_mean) / rolling_std
    # See scripts/mean_reversion_test.py for full signal generation
    ...

Position Sizing with Z-Score

Scale position size with z-score magnitude for better risk-adjusted returns:

size = base_size * min(abs(z) / entry_threshold, max_scale)

See references/strategy_design.md for complete entry/exit framework and sizing.


Ornstein-Uhlenbeck (OU) Process

The OU process is the continuous-time model of mean reversion:

dX = theta * (mu - X) * dt + sigma * dW
ParameterMeaningEstimation
thetaSpeed of mean reversionFrom AR(1) beta: theta = -ln(1+beta)/dt
muLong-run meanFrom AR(1) intercept: mu = -alpha/beta
sigmaVolatility of innovationsResidual std from AR(1)

Parameter Estimation

def estimate_ou_params(series: np.ndarray, dt: float = 1.0) -> dict:
    """Estimate OU process parameters from observed series.

    Returns:
        Dict with keys: theta, mu, sigma, half_life.
    """
    y = np.diff(series)
    x = series[:-1]
    x_with_const = np.column_stack([np.ones(len(x)), x])
    params = np.linalg.lstsq(x_with_const, y, rcond=None)[0]
    alpha, beta = params[0], params[1]

    theta = -np.log(1 + beta) / dt
    mu = -alpha / beta if beta != 0 else np.mean(series)
    residuals = y - (alpha + beta * x)
    sigma = np.std(residuals) * np.sqrt(2 * theta / (1 - np.exp(-2 * theta * dt)))

    return {
        "theta": theta,
        "mu": mu,
        "sigma": sigma,
        "half_life": np.log(2) / theta if theta > 0 else -1,
    }

Strategy Types

Single-Asset Mean Reversion

Apply z-score framework directly to a token's price series. Works best on:

  • Stablecoins (USDC/USDT spread)
  • Tokens in established ranges
  • After confirming stationarity with ADF test

Pairs Trading

Trade the spread between two cointegrated assets:

  1. Confirm cointegration (see cointegration-analysis skill)
  2. Compute spread: S = Y - beta * X
  3. Apply z-score framework to the spread
  4. Go long spread (buy Y, sell X) when z < -2
  5. Go short spread (sell Y, buy X) when z > +2

Statistical Arbitrage

Multi-asset extension of pairs trading:

  • Eigenportfolios from PCA of correlated assets
  • Trade the smallest eigenvalue portfolios (most mean-reverting)
  • Requires larger universe (10+ assets)

Crypto-Specific Considerations

  1. Most crypto trends: Hurst exponent for BTC, ETH, SOL is typically 0.55-0.70. Raw price mean reversion is rare.
  2. Where to find mean reversion:
    • Pairs spreads (SOL/ETH ratio, BTC dominance)
    • Funding rates on perpetuals
    • Basis between spot and futures
    • Stablecoin depegs
    • Fee tier spreads across DEXs
  3. Short lookbacks: Crypto mean reversion has short half-lives (hours to days, not weeks)
  4. Transaction costs: DEX swap fees (0.25-1%) can eat mean-reversion profits. Factor in slippage.
  5. Regime awareness: Use regime-detection skill to only trade mean reversion in ranging regimes.

Integration with Other Skills

SkillIntegration
cointegration-analysisFind cointegrated pairs for pairs trading
pandas-taRSI, Bollinger Bands as mean-reversion indicators
regime-detectionFilter: only trade MR in ranging regimes
vectorbtBacktest mean-reversion strategies
volatility-modelingEstimate sigma for OU model
slippage-modelingFactor execution costs into P&L estimates
position-sizingSize positions using Kelly + z-score scaling

Files

References

  • references/statistical_tests.md -- ADF, Hurst exponent, variance ratio, and half-life estimation with full implementations and interpretation
  • references/strategy_design.md -- Z-score framework, position sizing, pairs trading setup, risk management, and backtest considerations

Scripts

  • scripts/mean_reversion_test.py -- Comprehensive mean-reversion analysis: ADF, Hurst, variance ratio, half-life, OU estimation, z-score signals
  • scripts/pairs_scanner.py -- Scan multiple assets for mean-reverting pairs: correlation, cointegration, spread analysis, ranking

Quick Start

# Run mean-reversion analysis on synthetic data
python scripts/mean_reversion_test.py --demo

# Scan for mean-reverting pairs
python scripts/pairs_scanner.py --demo

# Analyze a specific token (requires BIRDEYE_API_KEY)
BIRDEYE_API_KEY=your_key TOKEN_MINT=So11...1 python scripts/mean_reversion_test.py

This skill provides analytical tools and information only. It does not constitute financial advice or trading recommendations.

FAQ

What does the mean-reversion skill do?

Mean-reversion strategy tools including Hurst exponent, half-life estimation, z-score signals, ADF testing, and Ornstein-Uhlenbeck modeling

How do I install mean-reversion?

Run npx skills add https://github.com/agiprolabs/claude-trading-skills --skill mean-reversion in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/mean-reversion/ (personal) or .claude/skills/mean-reversion/ (project).

Which AI agents can use mean-reversion?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is mean-reversion safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains mean-reversion?

It is published by agiprolabs in agiprolabs/claude-trading-skills. It has 495 recorded installs.

More from agiprolabs/claude-trading-skills

View all →

walk-forward-validation

agiprolabs/claude-trading-skills

Walk-forward validation framework for trading strategies and ML models with time-series-aware splits, overfit detection, and regime-aware validation

Business & Finance714 installs

risk-management

agiprolabs/claude-trading-skills

Portfolio-level risk controls, drawdown management, exposure limits, and circuit breakers for crypto trading

Business & Finance637 installs

pandas-ta

agiprolabs/claude-trading-skills

Technical analysis with 130+ indicators using pandas-ta for crypto market data

Data & Databases593 installs

position-sizing

agiprolabs/claude-trading-skills

Trade sizing methods including fixed fractional, volatility-adjusted, Kelly criterion, and liquidity-constrained sizing

Business & Finance581 installs

regime-detection

agiprolabs/claude-trading-skills

Market regime identification using volatility clustering, trend detection, and statistical methods for adaptive trading

Business & Finance578 installs

kelly-criterion

agiprolabs/claude-trading-skills

Kelly criterion optimal sizing with fractional variants, edge estimation, and practical application for crypto trading

Business & Finance534 installs

Popular testing & qa skills

View category →

tdd

mattpocock/skills

Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.

Testing & QA1.2M installs

grilling

mattpocock/skills

Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.

Testing & QA996.2K installs

migrate-to-shoehorn

mattpocock/skills

Migrate test files from as type assertions to @total-typescript/shoehorn. Use when user mentions shoehorn, wants to replace as in tests, or needs partial test data.

Testing & QA484.1K installs

run-train

lllllllama/rigorpilot-skills

Rigor Train skill for deep learning research repositories. Use when a documented or selected training command should be run conservatively for startup verification, short-run verification, full kickoff, or resume, with command, config, seed, log, checkpoint, status, and metric evidence written to standardized trainoutputs/. Do not use for environment setup, exploratory sweeps, speculative idea implementation, or end-to-end orchestration.

Testing & QA337.8K installs

test-driven-development

obra/superpowers

Use when implementing any feature or bugfix, before writing implementation code

Testing & QA261.8K installs

Use when implementation is complete, all tests pass, and you need to decide how to integrate the work

Testing & QA216.8K installs