MRI API Docs · v1.0.4 · API v2.3

Macro Risk Data,
Programmable

Free programmatic access to the moneyfeel Macro & Geopolitical Risk Index. Regime classifications, probability vectors, strategy metrics and full historical datasets — 5 regions, 3 timeframes, 2007 to present.

🔑 Get Free API Key GitHub Repository Live Dashboard Excel Template

Regions

Timeframes

2007

Coverage from

Free

All registered users

Daily

Updated

Base URL

endpoint

https://api.moneyfeel.ai/v1

All endpoints are prefixed with /v1. A GET /v1 returns the API index (endpoint list). The API is hosted on Cloudflare Workers — globally distributed and optimized for low-latency access.

Quick Start

Up and running in 3 minutes

Create a free account at moneyfeel.it. No credit card required. Takes 30 seconds.

Generate your API key

Go to your account page → find the MRI API Access section → click Generate API Key. Your key starts with mf_live_

Make your first call

Pass the key in the Authorization header. Start with /v1/current — no auth required.

 bash 
# Public — no authentication required curl "https://api.moneyfeel.ai/v1/current" # Authenticated — historical regime data curl -H "Authorization: Bearer mf_live_YOUR_KEY" \ "https://api.moneyfeel.ai/v1/history?region=US&tf=WEEKLY&from=2020-01-01" # Download full CSV dataset curl -H "Authorization: Bearer mf_live_YOUR_KEY" \ "https://api.moneyfeel.ai/v1/download?region=US&tf=WEEKLY" \
 -o mri_US_WEEKLY.csv

Windows PowerShell: curl is aliased to Invoke-WebRequest — use curl.exe for the syntax above (with -H and \ for line continuation), or see the native syntax in the PowerShell tab in Quick Start.

 python 
# pip install moneyfeel-mri from moneyfeel import MRI  client = MRI("mf_live_YOUR_KEY") # Current regime for all regions current = client.current()
print(current[0]) # US Weekly history as pandas DataFrame df = client.history_df("US", "WEEKLY", from_date="2020-01-01")
print(df.tail()) # Performance metrics metrics = client.metrics("US", "WEEKLY")
print(metrics[0]["sharpe"]) # Full dataset as DataFrame full_df = client.download("US", "WEEKLY")
print(full_df.tail())

 r 
library(httr2) library(dplyr)  API_KEY <- "mf_live_YOUR_KEY" BASE <- "https://api.moneyfeel.ai/v1" # Helper function mri <- function(endpoint, params = list()) {
 request(BASE) |>
 req_url_path_append(endpoint) |>
 req_url_query(!!!params) |>
 req_headers(Authorization = paste("Bearer", API_KEY)) |>
 req_perform() |>
 resp_body_json()
} # US Weekly history since 2020 hist <- mri("history", list(region = "US", tf = "WEEKLY", from = "2020-01-01"))
df <- as.data.frame(do.call(rbind, lapply(hist$data, as.data.frame))) # Performance metrics metrics <- mri("metrics", list(region = "US", tf = "WEEKLY"))
cat("Sharpe:", metrics$data[[1]]$sharpe, "\n")

 javascript 
const API_KEY = "mf_live_YOUR_KEY"; const BASE = "https://api.moneyfeel.ai/v1"; async function mri(endpoint, params = {}) { const url = new URL(`${BASE}/${endpoint}`);
 Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v)); const r = await fetch(url, {
 headers: { "Authorization": `Bearer ${API_KEY}` }
 }); return r.json();
} // Current regime — no auth needed const current = await fetch(`${BASE}/current`).then(r => r.json()); // US Weekly history const history = await mri("history", { region: "US", tf: "WEEKLY", from: "2020-01-01" });

 powershell 
# Current regime — no authentication required Invoke-RestMethod -Uri "https://api.moneyfeel.ai/v1/current" # Authenticated — historical regime data $headers = @{ Authorization = "Bearer mf_live_YOUR_KEY" } Invoke-RestMethod -Uri "https://api.moneyfeel.ai/v1/history?region=US&tf=WEEKLY&from=2020-01-01" -Headers $headers # Download full CSV dataset Invoke-WebRequest -Uri "https://api.moneyfeel.ai/v1/download?region=US&tf=WEEKLY" -Headers $headers -OutFile mri_US_WEEKLY.csv

Authentication

API Key — Bearer Token

Pass your API key in the Authorization header as a Bearer token. Keys are permanent and do not expire. You can revoke or regenerate them at any time from your account page.

header

Authorization: Bearer mf_live_YOUR_KEY

✓ Security notes

Keys are stored as SHA-256 hash — never in plaintext
Shown once at generation — copy it immediately
Revocation is instant — propagates in <1 second
One active key per account

⚠ Best practices

Never commit keys to public repositories
Store in environment variables or secret managers
Rotate keys periodically via your account page
If compromised, revoke immediately

Endpoints

All API Endpoints

Public endpoints require no authentication. Authenticated endpoints require a valid API key in the Authorization header.

GET /v1 API index Public

Returns the API name, version and the list of public and protected endpoints. Useful as a discovery entry point.

bash

curl "https://api.moneyfeel.ai/v1"

 response 
{ "name": "moneyfeel MRI Public API", "version": "2.3", "docs": "https://github.com/moneyfeel-io/mri-api", "public_endpoints":    ["/v1/status", "/v1/ping", "/v1/regions", "/v1/current"], "protected_endpoints": ["/v1/history", "/v1/regime/latest", "/v1/metrics", "/v1/timeseries", "/v1/eoy", "/v1/drawdowns", "/v1/download", "/v1/features"] }

GET /v1/status Health check Public

Returns worker status, version and current timestamp. Use to verify connectivity before making data requests. /v1/ping is an alias of this endpoint.

bash

curl "https://api.moneyfeel.ai/v1/status"

 response 
{ "status": "ok", "worker": "mri-public-api", "version": "2.3", "ts": "2026-05-21T22:00:00.000Z" }

GET /v1/regions Available regions and timeframes Public

Returns the list of valid region and tf values to use in other endpoints.

bash

curl "https://api.moneyfeel.ai/v1/regions"

 response 
{ "regions": ["GLOBAL", "US", "EU", "ASIA", "EM"], "timeframes": ["DAILY", "WEEKLY", "MONTHLY"], "coverage": "2007-01-04 to present", "updated": "daily at market close (UTC)" }

GET /v1/current Current regime for all 5 regions Public

Returns the latest regime classification across all 5 regions and all 3 timeframes (daily, weekly, monthly), with DEFCON level and display color per timeframe. No authentication required. Updated daily at market close.

bash

curl "https://api.moneyfeel.ai/v1/current"

 response 
{ "data": [
 { "region": "US", "regime_daily": "NEUTRAL", "regime_weekly": "BEAR", "regime_monthly": "BEAR", "score_daily": -0.5467, "score_weekly": -0.5091, "score_monthly": -0.6929, "confidence_daily": 0.4094, "confidence_weekly": 0.4313, "confidence_monthly": 0.5242, "days_in_daily": 18, "days_in_weekly": 1, "days_in_monthly": 2, "changed_daily": 0, "changed_weekly": 1, "defcon_daily": 3, "defcon_weekly": 2, "defcon_monthly": 2, "color_daily": "#6b7a99", "color_weekly": "#f5a623", "color_monthly": "#f5a623", "updated_at": "2026-05-21" }, ...
 ], "updated_at": "2026-05-21", "source": "moneyfeel — moneyfeel MRI" }

GET /v1/history Historical regime classifications Auth required

Returns regime classifications and probability vectors for a given region and timeframe over a date range.

Parameter	Type	Required	Description
region	string	Required	GLOBAL · US · EU · ASIA · EM
tf	string	Optional	DAILY · WEEKLY · MONTHLY (default: WEEKLY)
from	date	Optional	Start date YYYY-MM-DD (default: 2007-01-01)
to	date	Optional	End date YYYY-MM-DD (default: today)

bash

curl -H "Authorization: Bearer mf_live_YOUR_KEY" \ "https://api.moneyfeel.ai/v1/history?region=US&tf=WEEKLY&from=2020-01-01"

GET /v1/regime/latest Latest regime for region + timeframe Auth required

Returns the most recent regime record for the requested region and timeframe.

bash

curl -H "Authorization: Bearer mf_live_YOUR_KEY" \ "https://api.moneyfeel.ai/v1/regime/latest?region=US&tf=WEEKLY"

GET /v1/metrics Strategy performance KPIs Auth required

Returns scalar performance metrics for the MRI overlay strategy: CAGR, Sharpe, Sortino, Max Drawdown, Alpha, Beta, VaR, CVaR, Win Month %, and more. Pass region to filter, or omit to get all 15 combinations.

bash

curl -H "Authorization: Bearer mf_live_YOUR_KEY" \ "https://api.moneyfeel.ai/v1/metrics?region=US&tf=WEEKLY"

GET /v1/timeseries Daily strategy vs benchmark series Auth required

Returns the full daily return series for the MRI overlay strategy and the benchmark, including cumulative returns, active returns, rolling Sharpe (6M), rolling Beta (6M), rolling Volatility (6M) and drawdown series.

bash

curl -H "Authorization: Bearer mf_live_YOUR_KEY" \ "https://api.moneyfeel.ai/v1/timeseries?region=US&tf=WEEKLY"

GET /v1/eoy Year-by-year returns Auth required

Returns annual return comparison between the MRI overlay and the B&H benchmark, with win/loss status per year. Available from 2007 to present.

bash

curl -H "Authorization: Bearer mf_live_YOUR_KEY" \ "https://api.moneyfeel.ai/v1/eoy?region=US&tf=WEEKLY"

GET /v1/drawdowns Top drawdown periods Auth required

Returns the 10 largest peak-to-trough drawdowns for the MRI overlay strategy: start date, recovery date, drawdown percentage and duration in days.

bash

curl -H "Authorization: Bearer mf_live_YOUR_KEY" \ "https://api.moneyfeel.ai/v1/drawdowns?region=US&tf=WEEKLY"

GET /v1/download Full CSV download Auth required

Downloads the complete dataset as a CSV file — regime classifications and strategy timeseries merged by date. Includes comment headers with attribution and download date. One request returns the full history (~5,000 rows for DAILY, ~1,100 for WEEKLY).

bash

curl -H "Authorization: Bearer mf_live_YOUR_KEY" \ "https://api.moneyfeel.ai/v1/download?region=US&tf=WEEKLY" \
 -o mri_US_WEEKLY.csv

GET /v1/features Macro signal breakdown Auth required

Returns the latest macro signal breakdown for a region: credit stress, normalized volatility, momentum z-score, sovereign spread and policy rates (VIX, Fed, ECB). Pass region to filter; omit to get the first available region.

bash

curl -H "Authorization: Bearer mf_live_YOUR_KEY" \ "https://api.moneyfeel.ai/v1/features?region=US"

 response 
{ "region": "US", "data": { "region": "US", "as_of_date": "2026-05-21", "credit_stress_index": 0.42, "vol_normalized": 1.18, "momentum_z": -0.73, "sovereign_spread_pct": 0.31, "vix": 18.4, "fed_rate": 4.5, "ecb_rate": 2.4, "updated_at": "2026-05-21" } }

Data Schema

Regime History — Field Reference

Fields returned by /v1/history and /v1/regime/latest.

Field	Type	Description
as_of_date	string	Date of the regime classification (YYYY-MM-DD)
region	string	GLOBAL · US · EU · ASIA · EM
timeframe	string	DAILY · WEEKLY · MONTHLY
regime	string	STRONG_BULL · BULL · NEUTRAL · BEAR · STRONG_BEAR
regime_numeric	integer	+2 / +1 / 0 / -1 / -2 (ordered encoding)
mri_score	float	Normalized regime signal in [−2, +2]. Not a price index.
prob_strong_bull	float	Posterior probability — Strong Bull regime [0, 1]
prob_bull	float	Posterior probability — Bull regime [0, 1]
prob_neutral	float	Posterior probability — Neutral regime [0, 1]
prob_bear	float	Posterior probability — Bear regime [0, 1]
prob_strong_bear	float	Posterior probability — Strong Bear regime [0, 1]
regime_confidence	float	argmax of the probability vector — confidence of the dominant regime
days_in_regime	integer	Consecutive days in the current regime
regime_changed	integer	1 if the regime changed vs previous period, 0 otherwise

Error Handling

Error Codes

All errors return a consistent JSON structure with a machine-readable error code, a human-readable message and a link to this documentation.

 error response structure 
{ "error": "rate_limit_exceeded", "message": "30 requests/minute exceeded. Retry after 42 seconds.", "status": 429, "docs": "https://github.com/moneyfeel-io/mri-api" }

HTTP	error code	When it happens	Resolution
401	`missing_auth`	No Authorization header (or not a Bearer token)	Add `Authorization: Bearer mf_live_YOUR_KEY`
401	`invalid_api_key`	API key not found or revoked	Generate a new key from your account page
401	`invalid_auth`	Token is not a valid API key or session	Use a valid `mf_live_` key
429	`rate_limit_exceeded`	Over 30 req/min	Wait `Retry-After` seconds
429	`daily_quota_exceeded`	Over 2,000 req/day	Quota resets at 00:00 UTC. Use `/v1/download` for bulk data.
400	`invalid_param`	Invalid or missing region / timeframe	Use values from `/v1/regions`
404	`no_data`	No records for the requested filters	Try a broader date range
404	`not_found`	Endpoint path does not exist	Check the endpoint list above
500	`internal_error`	Unexpected server error	Retry after a few seconds. If persistent, contact support.

Rate Limits

Usage Limits

All limits apply per API key. Daily quotas reset at 00:00 UTC. When a limit is exceeded, the response includes a Retry-After header with the seconds to wait.

Requests / minute

2,000

Requests / day

2007

History from

Free

All registered users

💡 Tips to stay within limits

→ Use /v1/download (1 request) instead of paginating /v1/history for bulk exports
→ Cache locally — MRI data updates once per day, no need to poll more than once daily
→ Space requests across a minute if fetching all 5 regions simultaneously
→ DAILY timeframe returns ~5,000 rows — download once and store

Open Source

GitHub Repository

The API documentation, Python and R client examples, curl scripts and full data schema are available on GitHub under the moneyfeel-io organization.

moneyfeel-io / mri-api

REST API documentation, Python & R examples, curl scripts, full data schema and changelog.

moneyfeel-io

The moneyfeel GitHub organization — open data and tools for quantitative macro research.

Data Attribution

How to Cite

If you use MRI data in research, publications or products, please include the following attribution:

citation

moneyfeel (2026). Macro & Geopolitical Risk Index (MRI).
moneyfeel.it. Retrieved from https://moneyfeel.it/dashboard/macro-regime-index/ # Geopolitical risk component: Iacoviello, M. (2022). Measuring Geopolitical Risk.
American Economic Review, 113(4), 1194–1225.
https://www.matteoiacoviello.com/gpr.htm

Data is provided under CC BY-NC 4.0 — free for research and non-commercial use.

Macro Risk Data,Programmable

Up and running in 3 minutes

API Key — Bearer Token

All API Endpoints

Regime History — Field Reference

Error Codes

Usage Limits

GitHub Repository

How to Cite

Macro Risk Data,
Programmable