Mean Reversion logo

Mean Reversion

Community
agiprolabs
mean-reversion

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

Overview

Publisheragiprolabs
Repositoryclaude-trading-skills
Skill namemean-reversion
Stars
434
Forks
85
Bundled files
4
LicenseMIT
Links
  • Markdown instructions

    A SKILL.md file the model loads on demand, so it only costs tokens when a request actually matches.

  • Works with any LLM

    AI skills are plain Markdown, not provider-specific code, so this works with GPT, Claude, Gemini, Grok, or a local model.

  • 4 bundled files

    Scripts, templates, and references the model can read while it works. Files are read-only and never executed.

  • Open source

    Published by agiprolabs on GitHub. Read the source before you install it.

Installation

Install the Mean Reversion AI skill in TypingMind to use it with any LLM, or drop it into another agent that reads SKILL.md.

1

Install in TypingMind

TypingMind installs a skill straight from its GitHub folder — it reads SKILL.md, bundles the resource files, and stores the result locally.

  1. Open the app and go to Plugins → Skills.
  2. Choose "Install from GitHub".
  3. Paste the skill folder URL below and confirm.
    https://github.com/agiprolabs/claude-trading-skills/tree/main/skills/mean-reversion
  4. Enable the skill in any chat where you want it available.
Plugins → Skills → Add skill → From GitHub URL, then paste the folder URL and press Continue.
2

Install in another agent

Any agent that reads the Agent Skills format can use this skill — copy the folder into that agent's skills directory.

Claude Code — .claude/skills
git clone --depth 1 https://github.com/agiprolabs/claude-trading-skills.git /tmp/claude-trading-skills
mkdir -p .claude/skills
cp -r /tmp/claude-trading-skills/skills/mean-reversion .claude/skills/mean-reversion
Restart Claude Code after copying so it picks up the new skill.

Use it in TypingMind

Enable Mean Reversion in any TypingMind chat and the model takes it from there. Its name and description sit in the system prompt, and the moment a request matches, the model loads the full instructions itself — you never invoke it by hand, and it costs no tokens until it is actually used.

The model loads Mean Reversion on its own as soon as a request matches it.

Works with any AI model

AI skills are plain Markdown instructions rather than provider-specific code, so Mean Reversion is not tied to the model it was written for. Install it once in TypingMind and use it with GPT-5, Claude, Gemini, Grok, DeepSeek, Mistral, Llama, or a local model you run yourself — all on your own API keys.

  • Loaded only when it is needed

    The system prompt carries just the name and description. The instructions are fetched on the first matching request, so an idle skill costs nothing.

  • Switch models mid-chat

    Because the skill is instructions rather than code, changing model does not break it — the next model reads the same SKILL.md.

Skill instructions

This is the SKILL.md content the model loads. Read it before installing — a skill is instructions your model will follow.

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).

python
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
python
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)
python
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

python
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:

python
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:

python
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

python
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

bash
# 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.

Bundled files

The model reads these on demand while the skill is loaded. They are exposed as readable files and are never executed.

Frequently asked questions

What does the Mean Reversion AI skill do?

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

Why use Mean Reversion on TypingMind?

Because you install it once and use it with any model. Mean Reversion is plain Markdown rather than provider-specific code, so the same skill runs on GPT-5, Claude, Gemini, Grok, or a local model — and you can switch model mid-chat without it breaking. TypingMind runs on your own API keys, so you pay providers directly instead of a per-seat subscription, and your skills and chats stay in your own storage.

How do I install Mean Reversion in TypingMind?

Open Plugins → Skills → Install from GitHub in TypingMind and paste https://github.com/agiprolabs/claude-trading-skills/tree/main/skills/mean-reversion. TypingMind reads its SKILL.md and bundles its files and installs it as a skill you can enable per chat.

Which AI models can use Mean Reversion?

Any model you connect in TypingMind. AI skills are plain Markdown instructions rather than provider-specific code, so GPT, Claude, Gemini, Grok, and local models can all load this skill when a request matches it.

How many AI models can I use with Mean Reversion?

As many as you like. As long as a model supports skills, you can use Mean Reversion with it — GPT, Claude, Gemini, Grok, DeepSeek, Mistral, Llama and more — all on TypingMind with your own API keys.

Is the Mean Reversion AI skill free?

Yes. It is published on GitHub by agiprolabs under the MIT license. You only pay your own AI provider for the tokens you use.

What are AI skills?

An AI skill is a reusable instruction bundle that teaches an AI model how to do one specific task. It follows the open Agent Skills format: a SKILL.md file with a name and description, plus any scripts, templates or reference files the model may need. The model reads the instructions only when your request matches the skill, so an installed skill costs nothing until it is used.

How are AI skills different from plugins or MCP servers?

A plugin or MCP server gives a model new tools to call — code that runs somewhere and returns a result. An AI skill gives the model knowledge and process instead: how to approach a task, which steps to follow, what good output looks like. Skills are plain Markdown, so they need no server, no API key and no runtime, and they work with any model.

View all

Set up your own AI workspace now

Get notified about new features and future giveaways by subscribing to our newsletter 👇