API Documentation

REST API for FX Engineer — RV Forecast, Positioning Events, SSI data, and price data across 28 FX pairs. Base URL: https://api.fxengineer.com

The API is currently v1 (beta). Breaking changes will be announced at least 14 days in advance. For product context, see How It Works.

Authentication

Signal and data endpoints require authentication via API key or JWT Bearer token. Track record, performance, and model info endpoints are publicly accessible.

API Key (recommended for programmatic access)

curl -H "X-API-Key: fxe_your_key_here" \
  https://api.fxengineer.com/rv/signals/latest

JWT Bearer Token (for dashboard/browser sessions)

curl -H "Authorization: Bearer eyJhbG..." \
  https://api.fxengineer.com/rv/signals/latest

API Key Security

Your API key is a credential equivalent to your password. You are responsible for all activity on your key.

Do not share your API key with anyone
Do not embed keys in client-side code, public repositories, or browser-accessible scripts
Do not use a single key across multiple applications. Create separate keys for each
Rotate keys immediately if you suspect compromise

All API requests are logged and monitored. Abuse, unauthorized redistribution of data, or violation of the Terms of Service will result in immediate key revocation and may result in permanent account suspension without refund.

API Usage Policy

Rate limits are enforced per API key. Exceeding limits results in HTTP 429 responses with a Retry-After header.

Systematic redistribution, reselling, or rebroadcasting of API data is prohibited.

Automated scraping of endpoints beyond your subscribed tier is prohibited.

Keys found in public repositories or shared across unauthorized users will be revoked immediately.

FX Engineer reserves the right to suspend or terminate API access at any time for violations, with or without notice. No refunds are issued for access terminated due to Terms of Service violations.

By using the API, you agree to the Terms of Service.

Access Tiers

Tier	Pairs	Horizons	Export
Free	Track record, performance, model info, and market data only (no live signals)
Trial	6 majors	1h, 4h	No
Pro	All 28	All 27 (15m-24h)	Yes

RV Forecast

Realized volatility spike predictions. 28 pairs, 27 horizons (15m to 24h), updated hourly. See GET /rv/model for current model versions.

GET/rv/signals/latestTrial: 6 pairs, 1h+4h | Pro: all 28, all 27

Current predictions for all pairs and horizons. Grouped by pair with full move distribution (median, p75, p90).

Auth: API key or JWT (Trial+)

GET/rv/signals/{pair}/{horizon}

Signal history for a specific pair and horizon. Up to 1,000 historical predictions. Horizon: integer hours (1-24) or decimals for sub-hourly (0.25=15m, 0.5=30m, 0.75=45m).

Auth: API key or JWT (Trial+)

GET/rv/signals/elevated?days=7&horizon=4&threshold=0.30

Pairs that showed elevated spike probability above the threshold during the lookback period. Includes peak probability, timestamp, and current level.

Auth: Public

GET/rv/track-record

Rolling AUC, Brier score, calibration stats, per-pair and per-horizon breakdowns, model metadata. Publicly available for independent verification.

Auth: Public

GET/rv/track-record/export?format=csv

Full scored outcomes as CSV or JSON. Every prediction, every outcome, every timestamp. Pull this data and verify against any public candle source.

Auth: API key or JWT (Trial+)

GET/rv/model

Current model versions, training dates, test AUC per horizon, feature count. Champion and challenger model metadata.

Auth: Public

Positioning Events

Detected when the retail crowd reaches extreme positioning. Each event is tracked for a fixed measurement window (8 or 12 hours). 91% produce a 15+ pip move.

GET/patterns/active

Currently active positioning events with full context: crowd position, fade direction, measurement window, z-scores, checkpoint data, MFE/MAE.

Auth: API key or JWT (subscriber)

GET/patterns/history?limit=50&offset=0

Completed events with result (Worked/Failed), final pips, MFE, MAE, entry conditions. Filterable by symbol, result. Sorted by entry_time DESC.

Auth: Public (limited) / Subscriber (full)

GET/patterns/approaching

Pairs nearing detection threshold. Shows z-score distance, urgency level (IMMINENT/APPROACHING), and session.

Auth: API key or JWT (subscriber)

GET/patterns/stats?days=7

Aggregate statistics for the lookback period: total events, vol hit rate (15+ pip moves via MFE/MAE), avg MFE, avg MAE, directional fade rate. FX-spot only. Min N=5 for rate display.

Auth: Public

GET/patterns/{pattern_id}

Full detail for a single event including entry conditions, checkpoint history, and resolution data.

Auth: API key or JWT (subscriber)

Market Data

Price data (OANDA M1) and retail positioning (SSI) across 28 FX pairs.

GET/price/current?symbols=EURUSD,GBPUSD

Latest OHLC for all (or specified) FX pairs. From OANDA 1-minute candles, ~2 minute lag.

Auth: Public

GET/price/changes?window=7d

Batch price changes with pip conversion for all 28 FX pairs. Windows: 1d, 7d, 30d. Returns current close, previous close, % change, and pips.

Auth: Public

GET/price/movers?window=7d&n=5

Top N pairs by pip range (high minus low) over the window. Captures real volatility — a pair that moves 80 pips up then 80 down shows 160p range even with 0% close change.

Auth: Public

GET/price/context/{symbol}

Price context: daily/weekly/monthly ranges, position within range, distance from highs/lows in pips.

Auth: Public

GET/ssi/snapshot

Full 28-pair positioning snapshot: SSI ratio, % long, z-scores (48h, 14d), historical percentile, bias direction, streak hours, last flip. Pre-computed hourly.

Auth: Public

GET/ssi/current

Current SSI positioning for all symbols. Raw ratio and long percentage.

Auth: Public

GET/ssi/history/{symbol}?hours=168

Time-series SSI positioning for a specific pair. Configurable lookback in hours.

Auth: Public

Performance & Analytics

Historical performance data for positioning events. All publicly accessible.

GET/performance/summary

Overall positioning event performance: win rate, avg pips, MFE:MAE ratio, vol hit rate. Includes rolling 12-month stats.

Auth: Public

GET/performance/by-year

Year-by-year breakdown: events, win rate, avg pips per strategy.

Auth: Public

GET/performance/by-symbol

Per-pair performance table with tier, win rate, total events.

Auth: Public

Response Format

All responses are JSON. Timestamps are ISO 8601 UTC. Numeric values are floats.

GET /rv/signals/latest — response (truncated)

{
  "generated_at": "2026-04-21T00:00:00+00:00",
  "tier": "pro",
  "pairs": 28,
  "signals": [
    {
      "pair": "EURUSD",
      "horizons": {
        "4": {
          "signal_ts": "2026-04-21T00:00:00",
          "score": 0.142,
          "calibrated_prob": 0.138,
          "expected_move_pct": 0.00185,
          "median_move_pct": 0.00142,
          "p75_move_pct": 0.00258,
          "p90_move_pct": 0.00401,
          "threshold": 0.0012,
          "confidence_tier": "normal",
          "model_version": "lgbm_v4_m1_20260321"
        }
      }
    }
  ]
}

GET /patterns/stats?days=7 — response

{
  "period_days": 7,
  "total_events": 5,
  "vol_hits": 4,
  "vol_hit_rate": 80.0,
  "avg_mfe": 16.2,
  "avg_mae": 11.4,
  "avg_pips": 2.1,
  "favorable_count": 3,
  "favorable_rate": 60.0
}

GET /price/movers?window=7d&n=3 — response

{
  "window": "7d",
  "movers": [
    {"pair": "GBPAUD", "range_pips": 283, "high": 1.9842, "low": 1.9559},
    {"pair": "GBPCAD", "range_pips": 238, "high": 1.8501, "low": 1.8263},
    {"pair": "EURAUD", "range_pips": 222, "high": 1.7291, "low": 1.7069}
  ]
}

Notes

Rate limiting: Rate limits will be enforced in a future release. Current usage is unthrottled but monitored.

Caching: Most public endpoints return Cache-Control: public, max-age=300 (5 minutes). Active pattern data uses shorter TTLs (60s). Plan accordingly for polling frequency.

Model versions: Current champion model versions are returned by GET /rv/model. Model changes are logged in GET /rv/track-record.

Data sources: Price data from OANDA (M1 candles, ~2 min lag). SSI from FXCM (hourly). Positioning events validated against 9,100+ historical patterns (2014-2026, bid/ask M1).

Need an API key or have integration questions?

Request API Access