Skip to content

WEB_API.md

Latest commit

 

History

History
261 lines (197 loc) · 8.05 KB

WEB_API.md

File metadata and controls

261 lines (197 loc) · 8.05 KB

Web API Reference

The mtdata Web API exposes a focused REST surface for market data, forecasting, analysis, and the bundled Web UI. Use it when you want local HTTP access from dashboards, notebooks, scripts, or another application.

Base URL: http://localhost:8000 (default)

Route versioning:

  • Every API route below is available under both /api/... and /api/v1/....
  • Prefer /api/v1 for new integrations.
  • The examples below use /api for brevity.

The Web API is intentionally smaller than the full CLI/MCP tool surface. If an endpoint is not listed here, use mtdata-cli or an MCP client for that tool.

Quick Start

Start the local server:

mtdata-webapi

Check health and fetch a small candle sample:

curl http://127.0.0.1:8000/api/v1/health
curl "http://127.0.0.1:8000/api/v1/history?symbol=EURUSD&timeframe=H1&limit=50"

Open the bundled UI after building webui/dist/:

http://127.0.0.1:8000/app

Authentication

By default the API binds to 127.0.0.1 and permits loopback clients without a token.

If you want remote access, set WEBAPI_ALLOW_REMOTE=1, use a non-loopback WEBAPI_HOST, and provide WEBAPI_AUTH_TOKEN. When a token is configured, clients must send either:

  • Authorization: Bearer <token>
  • X-API-Key: <token>

Credentialed CORS requests require explicit origins. CORS_ORIGINS=* is rejected.

Security checklist for remote access:

  • Keep the default local bind (127.0.0.1) unless another machine must connect.
  • Set WEBAPI_AUTH_TOKEN before using WEBAPI_ALLOW_REMOTE=1.
  • Use explicit CORS_ORIGINS; do not rely on browser defaults.
  • Treat API access as sensitive because endpoints can expose account, symbol, and market context from the running MT5 terminal.

Response Style

Responses are JSON. Most endpoints return compact, UI-oriented payloads rather than the full CLI/MCP output contract. For richer historical rows or method diagnostics, prefer the CLI with --json and --extras.

Endpoints

Health / UI

GET /

Basic health check. Returns JSON, not the SPA.

GET /health

Same health payload as /.

GET /app

Serves the built Web UI (if webui/dist/ exists).

GET /api/health

API health check. Also available at GET /api/v1/health.

Market Data

GET /api/instruments

Search for available trading symbols.

  • Query Params:
    • search (string, optional): Search query for symbol name/description.
    • limit (int, optional): Max results to return.

GET /api/timeframes

Get supported timeframes.

GET /api/history

Fetch OHLCV candles for a symbol.

  • Query Params:
    • symbol (string, required): e.g., "EURUSD".
    • timeframe (string): Default "H1".
    • limit (int): Number of bars (default 500).
    • start, end (string, optional): ISO dates or relative strings.
    • ohlcv (string): Column selector (default "ohlc").
    • include_spread (bool): Append the historical candle spread field without changing the default row shape.
    • include_incomplete (bool): Include the latest forming candle.
    • denoise_method (string, optional): Apply denoising (e.g., "ema").
    • denoise_params (string, optional): JSON or "k=v" params for denoising.
  • Response Notes:
    • Both /api/history and /api/v1/history include modern runtime timezone metadata under meta.runtime.timezone (utc, server, and client when configured). The legacy used timezone compatibility field is not emitted.

GET /api/tick

Get the latest real-time tick.

  • Query Params:
    • symbol (string, required).

Analysis

GET /api/pivots

Calculate pivot points.

  • Query Params:
    • symbol (string, required).
    • timeframe (string): Default "D1".
    • method (string): "classic", "fibonacci", "woodie", "camarilla", "demark".

GET /api/support-resistance

Identify support and resistance levels, plus Fibonacci retracement/extension levels from the most relevant completed swing.

  • Query Params:
    • symbol (string, required).
    • timeframe (string): Default "auto". auto merges levels from M15, H1, H4, and D1.
    • limit (int): History depth to analyze.
    • tolerance_pct (float): Clustering tolerance (0.0015 = 0.15%).
    • min_touches (int): Minimum touches per level (default 2).
    • max_levels (int): Max levels per side (default 4).
  • Response Notes:
    • Each level includes a price zone_low/zone_high envelope rather than only a single line.
    • status and breakout_analysis expose broken levels and role-reversal confirmations.
    • In auto mode, overlapping same-event confirmations across timeframes are deduped instead of fully double-counted.
    • Qualification now uses distinct test episodes, while raw touches remain available as secondary detail.
    • The response includes both base and effective adaptive settings: tolerance_pct/reaction_bars are the inputs, while effective_tolerance_pct/effective_reaction_bars reflect the current ATR regime.
    • A fibonacci section exposes retracement levels 23.6%, 38.2%, 50%, 61.8%, 78.6% and extensions 127.2%, 161.8%, anchored to ATR-filtered historical swings and labeled relative to the latest price.

GET /api/denoise/methods

List available denoising algorithms and their parameters.

GET /api/denoise/wavelets

List available wavelet families/names (when PyWavelets is installed).

GET /api/dimred/methods

List available dimensionality reduction methods (PCA, UMAP, t-SNE, etc.) with parameter suggestions.

Forecasting

GET /api/methods

List available forecasting models and their requirements.

GET /api/volatility/methods

List available volatility models and their requirements.

GET /api/sktime/estimators

List sktime estimators (when sktime is installed).

POST /api/forecast/price

Generate price forecasts.

Note: The Web API always uses the native forecast library regardless of any library field in the request body. For other libraries (sktime, mlforecast, statsforecast) use the CLI.

Body (JSON):

{
  "symbol": "EURUSD",
  "timeframe": "H1",
  "method": "theta",
  "horizon": 12,
  "lookback": null,
  "as_of": null,
  "params": {},
  "ci_alpha": 0.05,
  "quantity": "price",
  "denoise": {
    "method": "ema",
    "params": {"alpha": 0.2}
  },
  "features": null,
  "dimred_method": null,
  "dimred_params": null,
  "target_spec": null
}

POST /api/forecast/volatility

Generate volatility forecasts.

Body (JSON):

{
  "symbol": "EURUSD",
  "timeframe": "H1",
  "horizon": 1,
  "method": "ewma",
  "proxy": null,
  "params": {"lambda": 0.94},
  "as_of": null,
  "denoise": null
}

POST /api/backtest

Run a rolling-origin backtest.

Body (JSON):

{
  "symbol": "EURUSD",
  "timeframe": "H1",
  "horizon": 12,
  "steps": 20,
  "spacing": 10,
  "methods": ["theta", "naive"],
  "params_per_method": null,
  "quantity": "price",
  "denoise": null,
  "params": null,
  "features": null,
  "dimred_method": null,
  "dimred_params": null,
  "slippage_bps": 0.0,
  "trade_threshold": 0.0,
  "extras": null
}

Compact response shape is the default. Use extras (for example ["metadata"] or "all") when you need richer sections such as per-anchor detail records.

Running the Server

Start the API server using the packaged entry point:

mtdata-webapi

Or directly via Uvicorn (if installed):

uvicorn mtdata.core.web_api:app --host 127.0.0.1 --port 8000

Configuration

Control the server host and port via environment variables:

  • WEBAPI_HOST: Bind address (default 127.0.0.1).
  • WEBAPI_PORT: Listen port (default 8000).
  • WEBAPI_ALLOW_REMOTE: Set to 1 to allow non-loopback binds.
  • WEBAPI_AUTH_TOKEN: Bearer/API key token required for authenticated API access.
  • CORS_ORIGINS: Comma-separated list of explicit allowed origins.
  • WEBUI_DIST_DIR: Override the built SPA directory (default webui/dist).

See Also