# 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`