API Reference

The RegimeRadar API lets you integrate live regime data into your own systems — trading bots, risk dashboards, algo strategies, or anything else. All endpoints return JSON. Authentication uses Bearer tokens.

Base URL https://api.rradar.io

Overview

Introduction

All requests must be made over HTTPS. The API is versioned — current version is v1 for radar endpoints. Auth and billing endpoints have no version prefix.

ℹ️

API access requires Pro + API plan The /v1/radar and /v1/radar_batch endpoints are available on the Pro + API plan ($20/mo). Auth and watchlist endpoints are available on all plans including Free.

Authentication

All protected endpoints require a Bearer token in the Authorization header. Get your token by calling POST /auth/login.

HTTP Header

Authorization: Bearer <your_token>

Python

import requests

headers = {"Authorization": f"Bearer {token}"}
resp = requests.get("https://api.rradar.io/v1/radar",
                    params={"symbol": "BTCUSD"},
                    headers=headers)
data = resp.json()

⚠️

Keep your token secret Tokens do not expire automatically. Never expose them in client-side code or public repositories. If compromised, log in again to get a fresh token.

Reference

Errors

All errors return a JSON body with a detail field.

HTTP Status	Error code	Meaning
400	BAD_REQUEST	Invalid parameters or malformed request body
400	EMAIL_ALREADY_REGISTERED	Registration attempted with existing email
401	BAD_CREDENTIALS	Wrong email or password
401	NOT_AUTHENTICATED	Missing or invalid Bearer token
403	PLAN_LIMIT	Watchlist or request exceeds plan limits
403	TRIAL_EXPIRED	14-day trial has ended, upgrade required
429	RATE_LIMITED	Too many requests — slow down
503	BILLING_NOT_CONFIGURED	Stripe not set up (dev/staging only)

Reference

Rate Limits

Plan	Radar endpoints	Other endpoints
Free / Pro	Dashboard only (no direct API)	60 req/min
Pro + API	120 req/min	120 req/min

Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Reference

Plans & Access

Plan	max_symbols	API access	Trial
free	3	Dashboard only	—
trial	10	Dashboard only	14 days full access
pro	Unlimited	Dashboard only	—
pro_plus	Unlimited	✓ Full API	—

Auth Endpoints

POST /auth/register

Register

🌐 Public

Create a new account. All new users start with a 14-day trial with full Pro access. Returns an access token immediately — no email verification step required to start.

Request body

Field	Type	Required	Description
email	string	required	Valid email address. Used for login.
password	string	required	Min 8, max 128 characters.

Request

POST /auth/register
Content-Type: application/json

{
  "email": "trader@example.com",
  "password": "your_password"
}

Response 200

JSON

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "usr_abc123",
    "email": "trader@example.com",
    "plan": "trial",
    "max_symbols": 10,
    "trial_days_remaining": 14,
    "can_access": true
  }
}

POST /auth/login

Login

🌐 Public

Authenticate and get an access token. Use this token as a Bearer token in all subsequent requests.

Request

POST /auth/login
Content-Type: application/json

{
  "email": "trader@example.com",
  "password": "your_password"
}

Response 200

JSON

{
  "access_token": "eyJhbGci...",
  "user": { /* same as register response */ }
}

GET /auth/me

Get current user

🔒 Bearer token required

Returns the current authenticated user's profile including plan, trial status, and limits.

Response 200

JSON

{
  "id": "usr_abc123",
  "email": "trader@example.com",
  "plan": "pro_plus",
  "max_symbols": 999,
  "is_trial": false,
  "trial_days_remaining": 0,
  "is_trial_expired": false,
  "has_active_subscription": true,
  "can_access": true
}

Watchlist Endpoints

GET /v1/watchlist

Get watchlist

🔒 Bearer token required

All plans

Returns the user's current watchlist with all symbols and plan information.

Response 200

JSON

{
  "name": "Main",
  "symbols": ["BTCUSD", "ETHUSD", "EURUSD"],
  "plan": {
    "name": "pro_plus",
    "max_symbols": 999,
    "trial_days_remaining": 0
  }
}

POST /v1/watchlist/items

Add symbol

🔒 Bearer token required

All plans

Add a symbol to the watchlist. Returns 403 if plan limit is reached.

Field	Type	Required	Description
symbol	string	required	Symbol to add. A-Z, 0-9, dots, slashes. Max 32 chars. Example: `BTCUSD`, `EURUSD`, `AAPL`

Request

POST /v1/watchlist/items
Authorization: Bearer <token>
Content-Type: application/json

{"symbol": "SOLUSD"}

Response 200

JSON

{"ok": true, "symbol": "SOLUSD"}

Response 403 — plan limit

JSON

{
  "detail": {
    "error": "PLAN_LIMIT",
    "max_symbols": 3,
    "current": 3,
    "upgrade_url": "/billing/checkout"
  }
}

DELETE /v1/watchlist/items/{symbol}

Remove symbol

🔒 Bearer token required

All plans

Remove a symbol from the watchlist.

Request

DELETE /v1/watchlist/items/SOLUSD
Authorization: Bearer <token>

Response 200

JSON

{"ok": true, "symbol": "SOLUSD"}

Radar Data Endpoints

GET /v1/radar

Single symbol analysis

🔒 Bearer token required

Pro + API

Returns the full regime analysis for a single symbol — the same data that powers the dashboard card. Includes regime state, volatility surface, tail risk, HMM forecast, and more.

Query parameters

Parameter	Type	Default	Description
symbol	string	required	Symbol to analyze. Examples: `BTCUSD`, `EURUSD`, `AAPL`
base_tf	string	M1	Timeframe for underlying bars. `M1`, `M5`, `H1`. For crypto, H1 is recommended.
allow_stale	int	0	Set to `1` to return last known data if live feed is unavailable.
include_crypto	int	0	Set to `1` to include funding rate, OI, basis, and order book data (crypto symbols only).

Python

resp = requests.get(
    "https://api.rradar.io/v1/radar",
    params={
        "symbol": "BTCUSD",
        "base_tf": "H1",
        "include_crypto": 1,
    },
    headers={"Authorization": f"Bearer {token}"}
)
data = resp.json()

regime  = data["regime"]["label"]         # "RANGE"
sigma   = data["volatility"]["sigma_24h"]   # 0.0357
p_down  = data["tail_risk"]["p_down"]        # 0.168
attn    = data["attention"]["score"]         # 37

Response 200 — key fields

JSON (abbreviated)

{
  "symbol": "BTCUSD",
  "asof": "2025-02-27T15:30:00Z",
  "data_quality": "HIGH",

  "regime": {
    "label": "RANGE",
    "confidence": 0.92,
    "uncertainty": "LOW"
  },

  "attention": {
    "score": 37,
    "label": "MODERATE",
    "reasons": ["Regime shift detected", "High probability of regime change"]
  },

  "volatility": {
    "sigma_24h": 0.0357,
    "sigma_1h": 0.004,
    "sigma_7d": 0.0677,
    "vs_avg": 1.2,
    "term_structure": "NORMAL"
  },

  "tail_risk": [
    {
      "horizon": "24h",
      "threshold": 0.03,
      "p_down": 0.168,
      "p_up": 0.083
    }
  ],

  "hmm": {
    "current_state": "HIGH_VOL",
    "confidence": 0.46,
    "forecasts": [
      {"horizon": "1h",  "p_regime_change": 0.451},
      {"horizon": "4h",  "p_regime_change": 0.606},
      {"horizon": "24h", "p_regime_change": 0.615}
    ]
  },

  "levels": {
    "vwap_24h": 67401,
    "poc": 68529,
    "range_position": 0.26,
    "zone": "LVN",
    "liquidity_score": 94.1
  },

  "risk_score": 5,

  // crypto only (include_crypto=1)
  "crypto": {
    "funding_rate": -0.0001,
    "funding_z": -0.72,
    "oi_change_24h": -0.0232,
    "basis": -0.000367,
    "order_imbalance_top10": 0.913
  }
}

GET /v1/radar_batch

Batch analysis

🔒 Bearer token required

Pro + API

Returns analysis for multiple symbols in a single request. Processes symbols in parallel. If symbols is omitted, uses the user's watchlist. Also returns a risk map with cross-asset correlation data.

Query parameters

Parameter	Type	Default	Description
symbols	string	optional	Comma-separated list of symbols. If omitted, uses your watchlist. Example: `BTCUSD,ETHUSD,EURUSD`
base_tf	string	M1	Timeframe for all symbols.
allow_stale	int	0	Allow stale data if live feed unavailable.
cache_ttl_sec	float	3.0	Cache TTL in seconds. Range: 0–30.
risk_map_window_hours	float	24.0	Lookback for cross-asset correlation. Range: 1–168 hours.
include_crypto	int	0	Include crypto microstructure data for crypto symbols.

Python

resp = requests.get(
    "https://api.rradar.io/v1/radar_batch",
    params={
        "symbols": "BTCUSD,ETHUSD,SOLUSD",
        "base_tf": "H1",
        "include_crypto": 1,
    },
    headers={"Authorization": f"Bearer {token}"}
)
data = resp.json()

for sym, result in data["results"].items():
    if "error" not in result:
        regime = result["regime"]["label"]
        attn   = result["attention"]["score"]
        print(f"{sym}: {regime} | attention={attn}")

Response 200 — structure

JSON

{
  "meta": {
    "asof": "2025-02-27T15:30:00Z",
    "base_tf": "H1",
    "count_requested": 3,
    "count_ok": 3,
    "count_error": 0,
    "plan": "pro_plus",
    "max_symbols": 999,
    "trial_days_remaining": 0
  },
  "errors": [],
  "results": {
    "BTCUSD": { /* full radar response per symbol */ },
    "ETHUSD": { /* ... */ },
    "SOLUSD": { /* ... */ }
  },
  "risk_map": {
    "ok": true,
    "corr": {
      "BTCUSD": {"ETHUSD": 0.87, "SOLUSD": 0.79}
    },
    "clusters": [["BTCUSD", "ETHUSD", "SOLUSD"]],
    "per_asset": {
      "BTCUSD": {"avg_corr": 0.83, "concentration_risk": "HIGH"}
    }
  }
}

💡

Use risk_map for portfolio context The risk_map shows correlations between your symbols. High correlation = concentrated risk. If all your symbols cluster together, a regime shift in one likely affects all.

Billing Endpoints

POST /billing/checkout

Create checkout session

🔒 Bearer token required

Creates a Stripe Checkout session. Redirect the user to the returned checkout_url to complete payment.

Field	Type	Required	Description
plan	string	required	`"pro"` or `"pro_plus"`

JSON

{
  "checkout_url": "https://checkout.stripe.com/pay/cs_live_...",
  "session_id": "cs_live_..."
}

GET /billing/status

Billing status

🔒 Bearer token required

Returns the current subscription state for the authenticated user.

JSON

{
  "plan": "pro_plus",
  "max_symbols": 999,
  "is_trial": false,
  "trial_days_remaining": 0,
  "is_trial_expired": false,
  "has_active_subscription": true,
  "can_access": true
}

POST /billing/webhook

Stripe webhook

🌐 Stripe only

Receives Stripe webhook events. Do not call this endpoint directly — it is for Stripe's servers only. Verifies the stripe-signature header.

Reference

Full response schema

Every field returned by /v1/radar for a single symbol.

Field path	Type	Description
symbol	string	Symbol name
asof	string	ISO 8601 timestamp of the analysis
data_quality	string	HIGH / MEDIUM / LOW
regime.label	string	TREND / RANGE / TRANSITION / HIGH_VOL / UNKNOWN
regime.confidence	float	0–1 model confidence
regime.uncertainty	string	LOW / MEDIUM / HIGH
attention.score	int	0–100
attention.label	string	LOW / MODERATE / ELEVATED / HIGH
attention.reasons	string[]	Top reasons driving the score
volatility.sigma_1h	float	1-hour volatility estimate
volatility.sigma_24h	float	24-hour volatility estimate (1 std dev)
volatility.sigma_7d	float	7-day volatility estimate
volatility.term_structure	string	NORMAL / INVERTED / FLAT
tail_risk[].horizon	string	e.g. "24h"
tail_risk[].threshold	float	Move threshold, e.g. 0.03 = 3%
tail_risk[].p_down	float	Probability of −threshold move
tail_risk[].p_up	float	Probability of +threshold move
hmm.current_state	string	LOW_VOL / MEDIUM_VOL / HIGH_VOL
hmm.confidence	float	0–1
hmm.forecasts[].p_regime_change	float	Probability of state change at horizon
levels.vwap_24h	float	24h VWAP price
levels.poc	float	Point of Control price
levels.zone	string	HVN / LVN / MID
levels.liquidity_score	float	0–100
risk_score	int	1–10 composite risk score
crypto.*	object	Only present for crypto symbols when include_crypto=1

Reference

Supported symbols

Any symbol available through your connected data sources can be requested. Common examples:

Category	Examples	Notes
Crypto	`BTCUSD`, `ETHUSD`, `SOLUSD`, `XRPUSD`	Supports include_crypto=1 for microstructure data
Forex	`EURUSD`, `GBPUSD`, `USDJPY`, `AUDUSD`	Tail row hidden for low-volatility pairs
Stocks	`AAPL`, `NVDA`, `AMD`, `MSFT`	Data available during market hours; STALE outside
Commodities	`XAUUSD`, `XAGUSD`, `USOIL`	Treated as forex-class instruments