Bitcoin Regime API

Real-time Bitcoin market regime signals powered by a 4-state Gaussian Hidden Markov Model. Get JSON responses with the current regime, confidence score, transition probabilities, and historical state sequence. Free tier available.

Get API Key → View Pricing

Authentication

All API requests require an API key passed as a header. Get your key by contacting us or signing up for a Pro plan.

# Include this header in all requests
X-API-Key: btcm_live_your_api_key_here

Free tier keys are prefixed btcm_free_ and limited to 100 requests/day. Pro keys are prefixed btcm_live_.

GET /regime/current

Returns the current Bitcoin market regime decoded by the Viterbi algorithm, with confidence score and transition matrix row for the active state.

Query Parameters

Parameter	Type	Description
asset optional	`string`	Asset symbol. Default: `BTC`. Pro: `ETH`, `SOL`.

Example Response

{
  "timestamp":    "2025-06-15T14:32:00Z",
  "asset":         "BTC",
  "regime":        "low_vol_bull",
  "confidence":    0.87,
  "duration_days": 8,
  "regime_meta": {
    "label":           "Low Volatility Bull",
    "mean_return":    0.0035,
    "daily_vol":      0.022,
    "expected_dur_days": 8.3
  },
  "transition_probs": {
    "low_vol_bull":  0.88,
    "low_vol_bear":  0.05,
    "hv_bear":       0.02,
    "transition":    0.05
  },
  "model_version": "v2.4.1"
}

curl -H "X-API-Key: btcm_live_your_key" \
     "https://api.btcmonitors.com/v1/regime/current"

import requests

response = requests.get(
    "https://api.btcmonitors.com/v1/regime/current",
    headers={"X-API-Key": "btcm_live_your_key"}
)
data = response.json()
print(data["regime"], data["confidence"])

const response = await fetch(
  'https://api.btcmonitors.com/v1/regime/current',
  { headers: { 'X-API-Key': 'btcm_live_your_key' } }
);
const { regime, confidence } = await response.json();
console.log(regime, confidence);

GET /regime/history

Returns the Viterbi-decoded regime sequence for a date range, with one entry per day.

Parameter	Type	Description
days optional	`integer`	Number of trailing days. Default: `30`. Max: `90` (Pro) / `7` (Free).
from optional	`date`	Start date ISO 8601. Overrides `days` if provided.
to optional	`date`	End date ISO 8601. Defaults to today.

{
  "asset":  "BTC",
  "from":   "2025-05-16",
  "to":     "2025-06-15",
  "regimes": [
    { "date": "2025-05-16", "regime": "low_vol_bull",  "confidence": 0.91, "close": 68420 },
    { "date": "2025-05-17", "regime": "low_vol_bull",  "confidence": 0.88, "close": 69150 },
    { "date": "2025-05-18", "regime": "transition",    "confidence": 0.72, "close": 67800 },
    // ... more entries
  ]
}

GET /regime/probabilities

Returns the full forward-algorithm posterior probabilities for each state — the filtered α distribution — not just the most likely state.

{
  "timestamp": "2025-06-15T14:32:00Z",
  "probabilities": {
    "low_vol_bull": 0.83,
    "low_vol_bear": 0.07,
    "hv_bear":      0.02,
    "transition":   0.08
  },
  "entropy_bits": 0.74
}

WS wss://api.btcmonitors.com/v1/stream Pro only

Real-time WebSocket stream. Pushes an update whenever the regime state or confidence changes by more than 5%.

const ws = new WebSocket('wss://api.btcmonitors.com/v1/stream');
ws.onopen = () => ws.send(JSON.stringify({
  auth: 'btcm_live_your_key',
  subscribe: ['regime', 'probabilities']
}));
ws.onmessage = e => console.log(JSON.parse(e.data));

Error Codes

Code	Message	Action
`401`	Invalid or missing API key	Check your `X-API-Key` header
`429`	Rate limit exceeded	Upgrade plan or reduce request frequency
`403`	Endpoint not available on your plan	Upgrade to Pro or Institutional
`503`	Model temporarily unavailable	Retry after 30s; check status page

API Pricing

Free

$0/mo

100 requests/day
/regime/current endpoint
7-day history only
JSON responses
WebSocket stream
/regime/probabilities
SLA guarantee

Get Free Key

Pro