Overview

MacroPulse exposes a REST API that returns daily macro regime classifications, net Fed liquidity, PCA factor scores, and backtesting utilities. All responses are JSON.

Base URL

HTTPS · https://api.macropulse.live

Authentication

Authenticated endpoints require an X-MacroPulse-Key header. Obtain a key by registering below or at macropulse.live/#register.

bash

curl -H "X-MacroPulse-Key: mp_..." https://api.macropulse.live/v1/signals/latest

Rate Limits

Limits are enforced per API key, per rolling 24-hour window.

Plan	Requests / day	Historical data
Free	50	30 days
Starter	500	Full (2yr+)
Pro	Unlimited	Full

ℹ When you exceed your limit the API returns 429 Too Many Requests. The X-RateLimit-Reset header contains the UTC epoch when the window resets.

Error Codes

All errors return a JSON body with detail and code fields. HTTP status codes follow standard semantics.

Status	Meaning
401	Missing or invalid API key
403	Key revoked
404	No data for requested date
422	Invalid parameters (see response body for field errors)
429	Rate limit exceeded
503	Data pipeline lag — daily ETL job in progress

GET /v1/signals/latest

GET Authenticated Primary

Returns the complete signal package for the most recent trading day. This is the primary endpoint — use this to get the current macro regime, liquidity signals, and PCA factors. All downstream strategies should start here.

Request Headers

Header	Required	Description
X-MacroPulse-Key	Yes	Your API key (`mp_...`)

Python Example

python

import requests

resp = requests.get(
    "https://api.macropulse.live/v1/signals/latest",
    headers={"X-MacroPulse-Key": "mp_..."}
)
signal = resp.json()

# Regime-aware equity exposure
EXPOSURE = {
    "expansion":  1.00,
    "recovery":   0.75,
    "tightening": 0.25,
    "risk_off":   0.00,
}
weight = EXPOSURE[signal["regime"]["most_likely"]]

Response Schema

json

{
  "date": "2026-03-15",
  "regime": {
    "most_likely": "recovery",
    "probabilities": {
      "expansion":  0.08,
      "recovery":   0.72,
      "tightening": 0.15,
      "risk_off":   0.05
    },
    "confidence": "HIGH",
    "persistence_days": 14,
    "expected_duration_remaining_days": 8
  },
  "net_liquidity": {
    "level_bn": 5842.3,
    "change_4w_bn": -124.5,
    "zscore": -1.1,
    "trend": "CONTRACTING"
  },
  "pca_factors": {
    "pc1": 0.82,
    "pc2": -0.34,
    "pc3": 0.11,
    "pc4": -0.05,
    "variance_explained_pct": [0.42, 0.22, 0.14, 0.09]
  },
  "model_metadata": {
    "pca_fit_date": "2026-01-15",
    "hmm_fit_date": "2026-01-15",
    "data_vintage": "2026-03-15T18:31:22Z"
  }
}

Regime Field Descriptions

Field	Type	Description
most_likely	string	Dominant regime: `expansion`, `recovery`, `tightening`, `risk_off`
probabilities	object	Posterior probability for each state. Values sum to `1.0`
confidence	string	`HIGH` (≥70%), `MODERATE` (≥50%), `LOW` (<50%)
persistence_days	int	Consecutive days the model has held the current regime
expected_duration_remaining_days	int	HMM-derived forward estimate of days remaining in this regime

GET /v1/signals/{date}

GET Authenticated

Retrieve the complete signal package for a specific historical date. Returns 404 if no data exists for the requested date (weekends, holidays, or dates before the data start).

Path Parameters

Parameter	Type	Description
date	string	ISO 8601 date in `YYYY-MM-DD` format

Example

bash

curl -H "X-MacroPulse-Key: mp_..." \
  https://api.macropulse.live/v1/signals/2025-10-01

Response schema is identical to GET /v1/signals/latest.

GET /v1/signals/range

GET Authenticated

Returns a time-series array of signal packages for a date range. Useful for backtesting and portfolio research. Maximum window: 365 calendar days.

Query Parameters

Parameter	Required	Description
start	Yes	Start date, ISO format `YYYY-MM-DD`
end	Yes	End date, ISO format `YYYY-MM-DD`

Python Example — Backtest Workflow

python

import requests, pandas as pd

resp = requests.get(
    "https://api.macropulse.live/v1/signals/range",
    params={"start": "2025-01-01", "end": "2025-12-31"},
    headers={"X-MacroPulse-Key": "mp_..."}
)
signals = pd.DataFrame(resp.json())
signals["regime"] = signals["regime"].apply(lambda x: x["most_likely"])

GET /v1/regime/current

GET Public

Returns the most recent regime classification. No API key required — suitable for public dashboards, widgets, and open integrations.

Example

bash

curl https://api.macropulse.live/v1/regime/current

Response

json

{
  "timestamp": "2026-03-15T00:00:00",
  "macro_regime": "recovery",
  "risk_score": 22.5,
  "probabilities": {
    "expansion":  0.08,
    "recovery":   0.72,
    "tightening": 0.15,
    "risk_off":   0.05
  },
  "volatility_state": "normal",
  "model_version": "v2"
}

GET /v1/regime/history

GET Public

Returns a paginated list of historical regime rows in reverse-chronological order. Useful for charting regime timelines without authentication.

Query Parameters

Parameter	Default	Description
limit	90	Number of rows to return. Maximum `1000`
start	—	ISO date filter — restrict results on or after this date
end	—	ISO date filter — restrict results on or before this date

Python Example

python

import requests, pandas as pd

history = requests.get(
    "https://api.macropulse.live/v1/regime/history",
    params={"limit": 365}
).json()
df = pd.DataFrame(history)

GET /v1/liquidity

GET Public

Returns net Fed liquidity time-series. Net liquidity is computed as Fed Assets − RRPO − TGA in billions of USD, with daily changes and z-scores.

Query Parameters

Parameter	Default	Max
limit	30	500

Example

bash

curl "https://api.macropulse.live/v1/liquidity?limit=90"

GET /v1/scorecard

GET Public

Returns 5 normalized macro signal gauges in the range [-1.0, +1.0]. Each gauge is the 20-day momentum of a key macro indicator, standardized by historical volatility.

Response

json

{
  "growth_momentum":    0.42,
  "inflation_momentum": -0.18,
  "liquidity":          -0.65,
  "financial_stress":   0.31,
  "dollar_strength":    0.12,
  "computed_at":        "2026-03-15T18:31:22.401Z"
}

Signal Definitions

Signal	Positive (+1)	Negative (−1)	Source indicator
growth_momentum	Yield curve steepening	Flattening / inversion	`d_yield_curve` 20d momentum
inflation_momentum	Rising 10Y yields	Falling 10Y yields	`d_10y` 20d momentum
liquidity	High net Fed liquidity	Liquidity drain	net_liquidity z-score
financial_stress	Calm markets	Stress / widening spreads	`-(d_hy + d_vix)` momentum
dollar_strength	Strong USD	Weak USD	`d_dxy` 20d momentum

POST /v1/backtest

POST Authenticated

Run a historical regime replay over a specified date range. Returns aggregate statistics about regime distribution, persistence, and risk score trajectory. Useful for strategy validation before live deployment.

Request Body

json

{
  "start": "2024-01-01",
  "end":   "2025-01-01"
}

Python Example

python

resp = requests.post(
    "https://api.macropulse.live/v1/backtest",
    json={"start": "2024-01-01", "end": "2025-01-01"},
    headers={"X-MacroPulse-Key": "mp_..."}
)
bt = resp.json()
print(bt["summary"]["avg_persistence_days"])  # e.g. 18.4

Response Summary Fields

Field	Description
total_days	Trading days included in the backtest range
transitions	Number of regime-change events detected
avg_persistence_days	Mean number of consecutive days per regime episode
mean_risk_score	Average signed risk score over the full period
regime_distribution	Percentage of trading days in each regime state

GET /v1/performance

GET Authenticated

Returns performance attribution comparing a regime-filtered strategy against a buy-and-hold benchmark. All metrics are computed using daily SPY returns as the base instrument.

Response Includes

Field	Description
sharpe	Annualized Sharpe ratio for the regime-filtered strategy
max_drawdown	Maximum peak-to-trough drawdown (negative float)
total_return	Cumulative return over the full period
alpha	Annualized alpha versus buy-and-hold benchmark
by_regime	Per-regime breakdown of returns and hit rate

Authentication Endpoints

POST /v1/auth/register

POST Public

Step 1 of 2: submit your email to receive a 6-digit verification code. Registration is a two-step flow to ensure only real email addresses receive API keys.

Request Body

json

{ "email": "you@example.com" }

Response (202 Accepted)

json

{
  "status": "verification_sent",
  "email": "you@example.com"
}

ℹ A 6-digit code valid for 15 minutes is emailed to you. Pass it to POST /v1/auth/verify to complete registration and receive your API key.

POST /v1/auth/verify

POST Public

Step 2 of 2: submit the verification code from your email to create your account and receive your API key.

Request Body

json

{ "email": "you@example.com", "code": "483921" }

Response (201 Created)

json

{
  "api_key":     "mp_...",
  "email":       "you@example.com",
  "tier":        "free",
  "daily_limit": 50
}

⚠ The api_key value is shown once. Copy and store it securely — it cannot be retrieved again. Use POST /v1/auth/rotate if you lose access.

POST /v1/auth/rotate

POST Authenticated

Rotate your API key. The current key is immediately revoked and a new one is returned. Update any applications before calling this endpoint.

Request Headers

Header	Required	Description
X-MacroPulse-Key	Yes	Your current API key. It will be invalidated upon success.

Example

bash

curl -X POST \
  -H "X-MacroPulse-Key: mp_old_key" \
  https://api.macropulse.live/v1/auth/rotate

⚠ The old key stops working immediately. Ensure all production integrations are updated before rotating.

GET /v1/regime/export Starter Pro

Download the full regime history as a CSV file. Free tier is limited to 30 days. Starter and Pro receive up to 730 days.

Query Parameters

limit

integer

Max rows to return. Free: capped at 30. Starter/Pro: up to 730. Default: 730.

Response

Returns a text/csv file with columns: date, regime, risk_score, equity_exposure, prob_expansion, prob_recovery, prob_tightening, prob_risk_off.

date,regime,risk_score,equity_exposure,prob_expansion,...
2026-03-17,recovery,1.24,0.75,0.12,0.71,0.11,0.06
2026-03-16,recovery,1.18,0.75,0.13,0.69,0.12,0.06

POST /v1/webhook/set Pro

Configure a webhook URL to receive a JSON POST on every regime transition. Pro tier only. Set url to null to remove the webhook.

Request Body

{ "url": "https://your-endpoint.com/macropulse" }

Webhook Payload

{
  "regime_change": {
    "from": "recovery",
    "to": "tightening",
    "from_label": "Recovery",
    "to_label": "Tightening",
    "equity_exposure": "25%",
    "risk_score": -1.4,
    "date": "2026-03-17"
  }
}

ℹ Use GET /v1/webhook/test to send a test payload to your configured URL. Use GET /v1/webhook/info to inspect your current configuration.