# ForexNewsRadar — Real-Time Forex & Gold Macro News + Prop VETO API (v4)

> Quantitative macroeconomic release telemetry (`Actual vs Forecast`, standardized `surprise_z` in `σ`), scheduled pre-news countdowns (`PRE_NEWS`), directional impulse scoring (`weak | normal | strong | extreme`), and automated protective `VETO` shields (`Whipsaw | Collision | Foreign Noise | Toxic Window`) across 16 FX pairs plus Gold (`XAUUSD`) and Silver (`XAGUSD`). Built for discretionary traders, funded prop-firm EAs (MetaTrader 5 / Python), and autonomous AI agents.

## Instant Zero-Key Live Test (EUR/USD is FREE Forever)

Test live right now without an account or API key:

```bash
curl -sS https://forexnewsradar.com/api/v1/pairs/EURUSD
```

Broker suffixes & delimiters (`EURUSD.pro`, `XAUUSDm`, `GBPUSD.raw`, `EUR/USD`) are normalized automatically on `/api/v1/pairs/{SYMBOL}` and `/api/v1/feed?symbol=...`.

## Environment Configuration (`.env`)

```ini
FNR_BASE_URL=https://forexnewsradar.com/api/v1
FNR_API_KEY=fnr_live_paste_your_token_here  # Optional for EURUSD; unlocks paid pairs (9 USDT/mo single pair or 29 USDT/mo all 18 pairs)
```

## Core V1 Endpoints

- `GET https://forexnewsradar.com/api/v1/pairs` — All 18 instruments in priority order (`EURUSD`, `XAUUSD`, `GBPUSD`, `USDJPY`, `XAGUSD`, ...). Add `?compact=1` for a lightweight multi-pair snapshot.
- `GET https://forexnewsradar.com/api/v1/pairs/{SYMBOL}` — Real-time quantitative telemetry for one instrument: `radar_health`, `agent_guidance` (`safe_to_trade` + `prop_safe_to_trade`), `live_state` (`CLEAR | PRE_NEWS | BUY | SELL | VETO`), `next_event` countdown, recent macro releases, and strategy positions. Add `?compact=1` (or `?format=compact`) for a ~240-byte single-object response tailored for MetaTrader 5 `WebRequest()` EAs. `EURUSD` is free; locked pairs return `402 Payment Required` with structured unlock URLs.
- `GET https://forexnewsradar.com/api/v1/feed` — Unified macro event, `upcoming_events`, & `active_vetoes` stream across unlocked pairs (`?limit=0..50`, `?currency=USD`, `?symbol=XAUUSD`).
- `GET https://forexnewsradar.com/api/v1/me` — Token introspection: active scopes, per-pair expiration timestamps, web device slots, and live rate-limit counters (`240 req/min` authenticated, `30 req/min` anonymous).
- `GET https://forexnewsradar.com/openapi.json` — Complete OpenAPI 3.1.0 specification with typed `200 OK` and `402` JSON schemas.
- `GET https://forexnewsradar.com/llms-full.txt` — Full integration reference with Python, MetaTrader 5 (`MQL5`), and TypeScript snippets.

## Minimal Pre-Trade & Prop-Firm Risk Gate (Python)

```python
import os, json, urllib.request, urllib.error

BASE = os.getenv("FNR_BASE_URL", "https://forexnewsradar.com/api/v1")
KEY = os.getenv("FNR_API_KEY", "")

def can_open_trade(symbol: str = "EURUSD", prop_account: bool = True) -> dict:
    headers = {"Accept": "application/json"}
    if KEY and not KEY.endswith("paste_your_token_here"):
        headers["Authorization"] = f"Bearer {KEY}"
    req = urllib.request.Request(f"{BASE}/pairs/{symbol}", headers=headers)
    try:
        with urllib.request.urlopen(req, timeout=8) as r:
            data = json.loads(r.read().decode())
            if data.get("radar_health", {}).get("stale"):
                return {"allowed": False, "reason": "stale_radar_heartbeat"}
            g = data["agent_guidance"]
            allowed = g["prop_safe_to_trade"] if prop_account else g["safe_to_trade"]
            return {
                "allowed": allowed,
                "status": data["live_state"]["status"],
                "wait_seconds": g["prop_wait_seconds"] if prop_account else g["wait_seconds"],
                "next_event": data.get("next_event"),
            }
    except urllib.error.HTTPError as e:
        body = json.loads(e.read().decode() or "{}")
        return {"allowed": False, "http_status": e.code, "error": body.get("error"), "unlock_url": body.get("unlock_url")}
```

## Pricing & Single-Token Entitlements

One token (`FNR_API_KEY`) holds all scopes — buying additional pairs extends the same token automatically:
- **`EURUSD`:** `0 USDT` (Free forever & live; `30 req/min` anonymous, `240 req/min` authenticated)
- **Single Pair (`XAUUSD`, `GBPUSD`, etc.):** `9 USDT / 1m` · `24 USDT / 3m` · `79 USDT / 12m`
- **All 18 Pairs + Gold & Silver (`Full Radar Pass`):** `29 USDT / 1m` (save 81%) · `69 USDT / 3m` · `199 USDT / 12m`
- Instant non-custodial `USDT (TRC-20)` checkout at `https://forexnewsradar.com/?unlock=ALL`
- Binding Terms of Service, Single-User API License & Risk Disclosure: `https://forexnewsradar.com/terms`

---

## Supported 18 Instruments (Priority Order)

1. `EURUSD` (EUR/USD — Euro / US Dollar, Majors, FREE FOREVER) — https://forexnewsradar.com/pairs/eurusd
2. `XAUUSD` (XAU/USD — Gold Spot / US Dollar, Metals) — https://forexnewsradar.com/pairs/xauusd
3. `GBPUSD` (GBP/USD — British Pound / US Dollar, Majors) — https://forexnewsradar.com/pairs/gbpusd
4. `USDJPY` (USD/JPY — US Dollar / Japanese Yen, Majors) — https://forexnewsradar.com/pairs/usdjpy
5. `XAGUSD` (XAG/USD — Silver Spot / US Dollar, Metals) — https://forexnewsradar.com/pairs/xagusd
6. `EURJPY` (EUR/JPY — Euro / Japanese Yen, Crosses) — https://forexnewsradar.com/pairs/eurjpy
7. `GBPJPY` (GBP/JPY — British Pound / Japanese Yen, Crosses) — https://forexnewsradar.com/pairs/gbpjpy
8. `AUDUSD` (AUD/USD — Australian Dollar / US Dollar, Majors) — https://forexnewsradar.com/pairs/audusd
9. `USDCAD` (USD/CAD — US Dollar / Canadian Dollar, Majors) — https://forexnewsradar.com/pairs/usdcad
10. `USDCHF` (USD/CHF — US Dollar / Swiss Franc, Majors) — https://forexnewsradar.com/pairs/usdchf
11. `NZDUSD` (NZD/USD — New Zealand Dollar / US Dollar, Majors) — https://forexnewsradar.com/pairs/nzdusd
12. `EURAUD` (EUR/AUD — Euro / Australian Dollar, Crosses) — https://forexnewsradar.com/pairs/euraud
13. `GBPAUD` (GBP/AUD — British Pound / Australian Dollar, Crosses) — https://forexnewsradar.com/pairs/gbpaud
14. `CADJPY` (CAD/JPY — Canadian Dollar / Japanese Yen, Crosses) — https://forexnewsradar.com/pairs/cadjpy
15. `AUDJPY` (AUD/JPY — Australian Dollar / Japanese Yen, Crosses) — https://forexnewsradar.com/pairs/audjpy
16. `NZDJPY` (NZD/JPY — New Zealand Dollar / Japanese Yen, Crosses) — https://forexnewsradar.com/pairs/nzdjpy
17. `CHFJPY` (CHF/JPY — Swiss Franc / Japanese Yen, Crosses) — https://forexnewsradar.com/pairs/chfjpy
18. `EURCHF` (EUR/CHF — Euro / Swiss Franc, Crosses) — https://forexnewsradar.com/pairs/eurchf

## Status & Prop-Firm VETO Taxonomy

- `CLEAR` — Calm microstructure; no active macro shock or imminent Tier-1 release.
- `PRE_NEWS` — Scheduled high-impact catalyst within `pre_veto_minutes` (default `T-5m`). Both `safe_to_trade` and `prop_safe_to_trade` become `false` so funded EAs flatten or hold before the Restricted News Window begins.
- `VETO` — Active post-release microstructure lock (`safe_to_trade = false`, `prop_safe_to_trade = false`):
  - `Whipsaw` — Violent two-way order-book sweep & spread expansion immediately post-release; wait until `veto_remaining_sec == 0`.
  - `Collision` — Simultaneous conflicting macro releases across base and quote currencies creating non-directional noise.
  - `Foreign Noise` — Cross-pair turbulence driven by an unrelated leg (e.g. USD shock distorting minor crosses).
  - `Toxic Window` — Scheduled central bank press conference or illiquid rollover window with elevated slippage risk.
- `BUY | SELL` — Clean directional post-release impulse (`weak | normal | strong | extreme`). Note: during the first `post_veto_minutes` (default `5m`) after a Tier-1 release, `safe_to_trade` is `true` for directional news traders while `prop_safe_to_trade` stays `false` until the prop-firm restriction window clears (`prop_window_remaining_sec == 0`).

## MetaTrader 5 (`MQL5`) Expert Advisor Pre-Trade Gate

Whitelist `https://forexnewsradar.com` in MT5 (`Tools -> Options -> Expert Advisors -> Allow WebRequest for listed URL`):

```cpp
input string FNR_ApiKey = ""; // Optional for EURUSD; paste fnr_live_... for XAUUSD / All 18 Pairs

bool FNR_IsPropSafe(string brokerSymbol) {
   string url = "https://forexnewsradar.com/api/v1/pairs/" + brokerSymbol + "?compact=1";
   string headers = "Accept: application/json\r\n";
   if(StringLen(FNR_ApiKey) > 10)
      headers += "Authorization: Bearer " + FNR_ApiKey + "\r\n";
   char post[], result[];
   string resHeaders;
   int code = WebRequest("GET", url, headers, 5000, post, result, resHeaders);
   if(code == 402) {
      Print("ForexNewsRadar: ", brokerSymbol, " is locked (402). Unlock at https://forexnewsradar.com/?unlock=ALL");
      return false; // Fail-closed on locked pair
   }
   if(code != 200) return false; // Fail-closed on network error
   string json = CharArrayToString(result);
   if(StringFind(json, "\"stale\":true") >= 0) return false;
   return (StringFind(json, "\"prop_safe_to_trade\":true") >= 0);
}
```

## HTTP Status Codes & Rate Limits

- `200 OK` — Live telemetry returned. Rate-limit headers included: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.
- `401 Unauthorized` — Malformed or expired `FNR_API_KEY`.
- `402 Payment Required` — Valid request for a locked pair (`error: "pair_locked"`). Present `unlock_url`, `unlock_single_usdt` (`9 USDT`), and `unlock_all_18_usdt` (`29 USDT`) to the user, or fall back to `https://forexnewsradar.com/api/v1/pairs/EURUSD`.
- `403 Forbidden` — Token manually suspended.
- `429 Too Many Requests` — Rate limit exceeded (`30 req/min` anonymous, `240 req/min` with Bearer key). Respect `Retry-After`.

## Support & Managed ECN Accounts

- Support & Lost Key Recovery: `https://forexnewsradar.com/` (`Lost key?` self-serve recovery) or `support@forexnewsradar.com`
- Managed ECN Accounts ($50k+ · 100% Non-Custodial LPOA Profit-Share Mandate): request terms via `https://forexnewsradar.com/` footer modal or `support@forexnewsradar.com`