API Reference

Base URL: https://api.marketheist.io

A full OpenAPI 3.1 specification is available at: https://api.marketheist.io/api/openapi.json

---

Authentication

The /api/backtest endpoint requires a Bearer token. Obtain one by logging in at marketheist.io/backtest/ and copying the token field from localStorage["bth.session.v1"] (DevTools → Application → Local Storage).

Pass it in every authenticated request:

Authorization: Bearer <your-session-token>

Tokens are valid for 90 days.

---

GET /api/ohlcv

Fetch historical OHLCV price data for any Yahoo Finance ticker. No authentication required. Data is cached server-side for up to 1 hour.

Query parameters:

Parameter	Required	Description
ticker	yes	Yahoo Finance symbol — e.g. AAPL, ^NDX, BTC-USD, GC=F
frequency	no	1d, 1wk, or 1mo. Default: 1wk

Example:

curl "https://api.marketheist.io/api/ohlcv?ticker=%5ENDX&frequency=1wk"

Response:

{
  "ticker": "^NDX",
  "frequency": "1wk",
  "rows": [
    { "t": 1262304000000, "o": 1860.31, "h": 1876.92, "l": 1804.29, "c": 1860.31, "v": 0 }
  ]
}

• t — bar open timestamp in Unix milliseconds
• o / h / l / c — adjusted prices (adjusted close used for c)
• v — volume (may be 0 for index tickers like ^NDX)

The response includes an x-cache: HIT header when served from cache.

---

POST /api/backtest

Run a single-strategy backtest server-side. Authentication required.

Returns a light metrics payload — Sharpe, CAGR, max drawdown, Calmar, Sortino, Omega, Profit Factor, plus equity and drawdown curves.

Request body:

{
  "ticker": "^NDX",
  "frequency": "1wk",
  "config": {
    "indicator_id": "rsi",
    "indicator_params": { "period": 14 },
    "position_rule": {
      "type": "threshold",
      "threshold": 50,
      "direction": "above"
    },
    "execution_delay": 1,
    "leverage": { "mode": "none" }
  }
}

config fields:

Field	Required	Description
indicator_id	yes	Built-in indicator id. See Indicators for the full list.
indicator_params	yes	Object of param name → value. Use {} for defaults.
position_rule	yes	Position rule object — see Position Rules.
execution_delay	yes	Bars between signal and fill. Use 1 to avoid lookahead bias.
leverage	yes	Leverage config — {"mode":"none"}, {"mode":"fixed","value":2}, {"mode":"target_vol","target_vol":0.15}, or {"mode":"target_dd","target_dd":-0.40}.
transaction_costs_bps	no	One-way cost in basis points (1 bps = 0.01%). Default 0.
regime_filter	no	Optional regime filter — {"type":"trend","sma_window":200} or {"type":"volatility","atr_period":14,"max_atr_pct":3.0}.

Example:

curl -X POST https://api.marketheist.io/api/backtest \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "ticker": "^NDX",
    "frequency": "1wk",
    "config": {
      "indicator_id": "rsi",
      "indicator_params": { "period": 14 },
      "position_rule": { "type": "threshold", "threshold": 50, "direction": "above" },
      "execution_delay": 1,
      "leverage": { "mode": "none" }
    }
  }'

Response:

{
  "ticker": "^NDX",
  "frequency": "1wk",
  "indicator_id": "rsi",
  "bar_count": 2102,
  "metrics": {
    "strategy": {
      "sharpe": 0.739, "sortino": 1.071, "cagr": 0.115,
      "max_dd": -0.558, "calmar": 0.206, "omega": 1.376,
      "profit_factor": 1.376, "recovery_factor": 146.7,
      "pct_invested": 0.737
    },
    "buyhold": {
      "sharpe": 0.327, "cagr": 0.142, "max_dd": -0.826, "calmar": 0.172
    },
    "applied_leverage": 1.0,
    "leverage_mode": "none",
    "n_years": 40.4
  },
  "equity_curve": [[505976400000, 1.0], ["..."]],
  "drawdown_curve": [[505976400000, 0.0], ["..."]]
}

• equity_curve and drawdown_curve are [unixMs, value] pairs. Equity starts at 1.0; drawdown values are ≤ 0.
• metrics.strategy reflects the applied leverage. metrics.buyhold is always unleveraged.

Error responses:

Status	Meaning
400	Invalid request body or unknown indicator_id
401	Missing or invalid Bearer token
422	Insufficient data (< 20 bars) or backtest engine error
502	Yahoo Finance upstream fetch failed