Market Regime Change API

02 · Paper P&L

Buying and selling SPY on the forecast

Green: buying and selling SPY on the forecast. Grey: holding SPY. Both start at 1.00 in January 2022.

How it works

Hold SPY. On about one day in twenty five, sell it at the close and sit in cash for the next day, then buy back. It is never short and it never holds anything but SPY.

On the days it is in, it holds less when SPY has been jumpy lately and more when SPY has been calm, so the amount of risk stays about the same from week to week instead of swinging with the market. Averaged over the period that works out to 1.17 times a normal position.

The forecast picks the days to sit out. It reads the fourteen numbers this site publishes, the chance of a bear market and the chance of a volatile one for each of the four forecasts, plus the two regimes showing right now, and skips the day when those numbers look their worst. Costs are charged at 2 basis points every time the position changes.

Sitting out 4% of days is enough to turn +72.1% into +157.0% because the skipped days are concentrated in the falling weeks. It is the same SPY, held slightly less often.

What this is not

The day filter was fitted using the whole 2010–2026 history, so the green line above knows things it could not have known at the time. Refit each year on past days only, it returns +71.7%, which merely matches doing nothing. Read +157.0% as what a good day filter is worth, not as a live track record.

The honest ceiling is close by. If you knew the true regime every day with no error and no delay, and knew in advance exactly how much to bet in each one, SPY would have returned +180% over these years. Perfect knowledge of tomorrow's direction is worth far more, but that is not what a regime model predicts.

03 · Five States

Five states, with meaningful changes only

When does a change become official?

One day over the line does not count. The market has to stay in the new state for three days running, and clear the line by a real margin instead of just touching it. Without that rule, one jumpy day would count as a whole new market.

What “now” tells you

Which of the five states the market is in today.

If we already know today's state, why isn't it 100%?

Because a change only counts once the market stays in the new state for three days running. Now tells you a change is happening before those three days are up, so it gets caught out when the market flips back before day three. That is the 0.6% it gets wrong. The other 99.4% it is right.

Why two views can disagree

After a three-week selloff that followed a two-month rally, the 21-day regime can already read bear while the 50-day regime still reads bull. Neither is wrong: one answers “the trend this month,” the other “the trend this quarter.” The fast view usually turns first; the views are never combined into one answer.

04 · Backtesting Results

How well did it work?

Every prediction is simulated as if it were live. The years 2010–2021 select features and settings; those choices are frozen before testing once on 2022–2026, and no test-year information ever feeds back into a choice.

The bar to beat is the baseline: guess that today's regime is still here a few days from now. Regimes are sticky, so that guess is already right most of the time, which makes it a genuinely hard bar to clear.

Accuracy: how often the forecast matched what happened; the green segment is what the model adds over the baseline. Changes caught: on the days the regime truly changed, how often the model called the new one.

Right now

The regime today, before any forecasting.

50-day trend

A regime is defined by the 25-day average against the 50-day average.

21-day trend

A regime is defined by the 10-day average against the 21-day average.

Why isn't it 100%?

Every one of the 8,576 test forecasts ended up in one of three situations. Two of them are easy and one is not.

1. The regime stayed the same. 81.6% of days.

   We were right 97.2% of the time.

2. It changed, and today's prices already showed it coming. 13.0% of days.

   We were right 98.6% of the time.

3. It changed because of moves that had not happened yet. 5.5% of days.

   We were right 19.4% of the time.

Nearly every miss is that last row. It is only 0.5% of days two days out, but 10% of days ten days out, which is why the short forecasts score higher than the long ones. When the answer is already sitting in the data, the model finds it 98.6% of the time.

Statistical check: daily forecasts overlap, so edges are tested with a moving-block bootstrap. All 8 rows beat the baseline at 95% confidence. The engine is also stress-tested against alternatives: 40 controlled experiments across ten further data families failed to beat it under this same protocol. Every negative result is recorded.

05 · Why It Works

Pipeline

1. 01

   Download a massive amount of raw data as base features

   365 vendor endpoints, untouched.

2. 02

   Build derived features from those base features

   One transform bank applied to every series.

3. 03

   Run a GPU feature-selection sweep across many AI models

   Thousands of H100 trials pick the features, not us.

4. 04

   Freeze the winning AI models and their predictions

   TabFM, Toto 2, Chronos 2. Computed once, written to disk.

5. 05

   Pass base, derived and AI features into deterministic models

   Classical models with nothing to memorize.

6. 06

   Run an orchestrator that combines them into one output

   Frozen weights per horizon.

7. 07

   Sweep the chosen deterministic models again for more alpha

   Selected on 2010–2021, locked years read once.

06 · API

Getting it yourself

One endpoint. Pick the market with symbol and the trend definition with variant. Horizons are chosen for you to match the trend speed, so you never have to reason about them. Use variant=now for both current trend views in one response.

import requests

data = requests.get(
    "https://api.regime-api.com/v1/regime",
    params={"symbol": "SOXX", "variant": "21d"},
).json()

print(data["current_regime"])
for f in data["forecasts"]:
    print(f["days_ahead"], f["regime"], f["change_probability"])

{
  "symbol": "SOXX",
  "variant": "21d",
  "as_of": "2026-08-07",
  "current_regime": "bear_volatile",
  "forecasts": [
    {
      "days_ahead": 2,
      "regime": "bear_volatile",
      "change_probability": 0.004,
      "probabilities": {
        "bull_quiet": 0.001,
        "bull_volatile": 0.001,
        "neutral": 0.001,
        "bear_quiet": 0.001,
        "bear_volatile": 0.995995
      }
    },
    { "days_ahead": 5, "regime": "bear_volatile", "...": "..." }
  ]
}

Fresh predictions are computed once per trading day at 21:30 UTC, about 90 minutes after the 4:00 PM New York close.

Returns today's regime plus a probability for each of the five regimes at both horizons. A fresh calculation takes a few minutes; repeat calls the same day are instant. No key required.