BtcForecaster
Forecast Track record How it works Feedback About

BtcForecaster API for developers

A free, read-only JSON API with BtcForecaster's Bitcoin price range forecasts for the next 1, 4 and 24 hours, every past forecast with its outcome, and the live track record. No sign-up and no API key.

What it offers and who it's for

Every 5 minutes BtcForecaster forecasts how far the Bitcoin price (Binance BTC/USDT) is likely to move: a 50% range and a 90% range for 1, 4 and 24 hours ahead. It doesn't forecast direction. Every forecast is then scored in public against what the price actually did. The API gives you the same numbers the site shows:

It's meant for hobby projects, dashboards, research, teaching and journalism. Everything is in plain JSON over HTTPS, with an OpenAPI 3 spec you can load into your tools, and an interactive viewer to try each call in the browser.

Quick start

curl https://btcforecaster.com/api/v1/forecast?horizon=1h

Endpoints

GET /api/v1/forecast: the latest forecast

The ranges the site currently shows, for every horizon. Each has the reference price it's centred on (the price when the forecast was made) and its time, the 50% and 90% ranges (low/high in USDT, and lowPct/highPct as % of the reference price), when it was made and the time it refers to.

ParameterMeaning
horizonOptional: 1h, 4h or 24h. Omit for all three.
curl https://btcforecaster.com/api/v1/forecast?horizon=1h
{
  "source": "BtcForecaster",
  "terms": "https://btcforecaster.com/developers#terms",
  "generatedUtc": "2026-11-11T09:06:12.481Z",
  "modelRelease": "v2-har",
  "modelName": "v2 (HAR-RV-J)",
  "note": "range50 and range90 are central ranges around the reference price ...",
  "forecasts": [
    {
      "horizon": "1h",
      "horizonMinutes": 60,
      "modelRelease": "v2-har",
      "forecastMadeUtc": "2026-11-11T09:05:00Z",
      "targetUtc": "2026-11-11T10:05:00Z",
      "referencePrice": 81250.4,
      "referenceTimeUtc": "2026-11-11T09:05:00Z",
      "range50": { "low": 81012.9, "high": 81488.6, "lowPct": -0.2923, "highPct": 0.2932 },
      "range90": { "low": 80588.1, "high": 81918.2, "lowPct": -0.8151, "highPct": 0.8219 },
      "priceSource": "binance"
    }
  ]
}

GET /api/v1/forecasts: past forecasts and their outcomes

Live forecasts made in a period, oldest first, each with its ranges and, once its target time has passed, the price it was scored against and whether that landed inside the 50% and 90% ranges. Only forecasts made in real time are included, never ones recreated from history.

ParameterMeaning
fromStart (inclusive), UTC ISO 8601. Default: 24 hours before to.
toEnd (exclusive). Default: now. At most 7 days after from.
horizonOptional: 1h, 4h or 24h. Omit for all three.
modelOptional: v1-baseline, v2-har or v3-har-cal90 (a shadow candidate). Default: the model the site shows.
page, pageSizePagination: page from 1; up to 1000 per page (default 500). Follow nextPage until it's null.

A forecast is made every 5 minutes per horizon, so a day holds up to 288 per horizon (864 for all three). outcome.status is pending until the result is known, scored once it is, or excluded in the rare case the outcome price came from a different price feed than the forecast (those are never scored). 

curl "https://btcforecaster.com/api/v1/forecasts?from=2026-11-10T00:00:00Z&to=2026-11-11T00:00:00Z&horizon=1h"
{
  "source": "BtcForecaster",
  "terms": "https://btcforecaster.com/developers#terms",
  "generatedUtc": "2026-11-11T09:06:30.112Z",
  "modelRelease": "v2-har",
  "fromUtc": "2026-11-10T00:00:00Z",
  "toUtc": "2026-11-11T00:00:00Z",
  "horizon": "1h",
  "page": 1,
  "pageSize": 500,
  "totalCount": 288,
  "totalPages": 1,
  "nextPage": null,
  "note": "Live forecasts only (never recreated from history), oldest first. ...",
  "forecasts": [
    {
      "horizon": "1h",
      "horizonMinutes": 60,
      "modelRelease": "v2-har",
      "forecastMadeUtc": "2026-11-10T00:00:00Z",
      "targetUtc": "2026-11-10T01:00:00Z",
      "referencePrice": 80410.0,
      "referenceTimeUtc": "2026-11-10T00:00:00Z",
      "range50": { "low": 80190.3, "high": 80630.3, "lowPct": -0.2732, "highPct": 0.274 },
      "range90": { "low": 79801.7, "high": 81022.9, "lowPct": -0.7565, "highPct": 0.7622 },
      "priceSource": "binance",
      "outcome": { "status": "scored", "actualPrice": 80655.2, "inside50": false, "inside90": true, "miss90": null }
    }
  ]
}

GET /api/v1/live-stats: the live track record

The same content as /api/live-stats (which keeps working unchanged), plus source, terms and modelRelease. Per model and horizon: how often the 50% and 90% ranges held, with a 95% margin of error that allows for overlapping forecasts (an effective sample size of n ÷ overlap), the average width, the interval score, misses above and below the range, and daily and rolling 7-day breakdowns. Live forecasts only.

ParameterMeaning
modelOptional: one model release, e.g. v2-har. Omit for all.
curl https://btcforecaster.com/api/v1/live-stats?model=v2-har
{
  "source": "BtcForecaster",
  "terms": "https://btcforecaster.com/developers#terms",
  "modelRelease": "v2-har",
  "generatedUtc": "2026-11-11T09:06:00.000Z",
  "headlineModelRelease": "v2-har",
  "note": "Live forecasts only (backtest excluded). ...",
  "models": [
    {
      "modelRelease": "v2-har",
      "displayName": "v2 (HAR-RV-J)",
      "isHeadline": true,
      "liveSinceUtc": "2026-10-28T12:00:00Z",
      "horizons": [
        {
          "horizonHours": 1,
          "samples": 4012,
          "hit90Pct": 89.6,
          "hit50Pct": 50.8,
          "range90": { "targetPct": 90, "samples": 4012, "hitRatePct": 89.6, "margin95": 3.3, "meanWidthPct": 1.62 },
          "intervalScorePct": 2.71,
          "misses90Above": 209,
          "misses90Below": 208,
          "rolling7d": [ ... ]
        }
      ]
    }
  ],
  "priceSource": "binance BTCUSDT"
}

Shortened: the full response has more fields (daily breakdowns, interval scores per range, fallback-feed details). The OpenAPI spec lists them all.

GET /api/v1/status: service health

Whether prices and forecasts are up to date, when the data last changed, and which price feed is in use: Binance, or the CoinGecko fallback when Binance doesn't answer (forecasts pause then, because the two feeds are never mixed). It always answers 200 while the service is up; read status: ok, degraded or down. 

curl https://btcforecaster.com/api/v1/status
{
  "source": "BtcForecaster",
  "terms": "https://btcforecaster.com/developers#terms",
  "generatedUtc": "2026-11-11T09:06:41.733Z",
  "apiVersion": "v1",
  "status": "ok",
  "message": "Prices and forecasts are up to date.",
  "modelRelease": "v2-har",
  "lastPriceUpdateUtc": "2026-11-11T09:06:00Z",
  "lastForecastUtc": "2026-11-11T09:05:00Z",
  "priceSource": "binance",
  "priceSourceIsFallback": false,
  "forecastsPaused": false,
  "forecastIntervalMinutes": 5
}

Errors

Errors are JSON too, with the HTTP status, a stable code and a message that says what to change:

{
  "source": "BtcForecaster",
  "terms": "https://btcforecaster.com/developers#terms",
  "error": { "status": 400, "code": "bad_request", "message": "horizon must be one of 1h, 4h, 24h; got '2h'." }
}
StatusCodeWhen
400bad_requestA parameter is missing its format or out of range (e.g. more than 7 days).
404not_foundNo such endpoint, or an unknown model.
429rate_limitedToo many requests; wait the number of seconds in the Retry-After header.
503unavailableNo forecast yet, or the data is temporarily unavailable. Try again shortly.

Rate limits, caching and CORS

Terms of use

Open-source scoring

The code that scores the forecasts (hit rates, effective sample size and margins, the interval score) and the tools used to compare models (the Diebold-Mariano test, walk-forward splits) are open source, so anyone can check exactly how BtcForecaster scores itself and run the same checks on the data from this API. It's on GitHub: github.com/pelusoft/btcforecaster-eval.

How the forecasts themselves are made and checked is explained on How it works.

Changelog

Questions or ideas for the API? See the about page for how to get in touch.

An unhandled error has occurred. Reload 🗙