{ "openapi": "3.1.0", "info": { "title": "ForexNewsRadar Quantitative Macro News & Prop VETO API", "version": "4.3.4", "termsOfService": "https://forexnewsradar.com/terms", "summary": "Real-time Actual vs Forecast macro releases, standardized sigma surprise telemetry, T-5m pre-news countdowns, directional impulse scoring, and automated VETO shields across 18 Forex & Precious Metals pairs (EURUSD is free & live).", "description": "Machine-readable instructions for AI agents: https://forexnewsradar.com/llms.txt", "contact": { "name": "ForexNewsRadar Desk", "url": "https://forexnewsradar.com", "email": "support@forexnewsradar.com" } }, "servers": [ { "url": "https://forexnewsradar.com", "description": "Cloudflare Global Edge Production" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Optional for EURUSD (free forever). Required to unlock paid pairs (fnr_live_<48_hex>). Stateless Bearer calls allow 240 req/min across multiple cloud/VPS IPs." } }, "schemas": { "RadarHealth": { "type": "object", "required": [ "synced_live", "mode", "stale" ], "properties": { "synced_live": { "type": "boolean" }, "mode": { "type": "string", "enum": [ "live", "stale", "standby" ] }, "last_heartbeat_at": { "type": [ "string", "null" ], "format": "date-time" }, "heartbeat_age_sec": { "type": [ "integer", "null" ] }, "stale": { "type": "boolean" } } }, "UpcomingCatalyst": { "type": "object", "required": [ "event_id", "currency", "title", "tier", "scheduled_at", "starts_in_sec" ], "properties": { "event_id": { "type": "string" }, "currency": { "type": "string", "example": "USD" }, "title": { "type": "string", "example": "US Core CPI (MoM)" }, "tier": { "type": "string", "enum": [ "high", "medium", "low" ] }, "scheduled_at": { "type": "string", "format": "date-time" }, "forecast": { "type": [ "string", "null" ] }, "previous": { "type": [ "string", "null" ] }, "starts_in_sec": { "type": [ "integer", "null" ] }, "pre_veto_minutes": { "type": "integer", "example": 5 }, "post_veto_minutes": { "type": "integer", "example": 5 } } }, "AgentGuidance": { "type": "object", "required": [ "safe_to_trade", "prop_safe_to_trade", "recommended_action", "trader_headline", "reason_code", "wait_seconds", "prop_wait_seconds", "explanation" ], "properties": { "safe_to_trade": { "type": "boolean" }, "prop_safe_to_trade": { "type": "boolean" }, "recommended_action": { "type": "string", "enum": [ "CLEAR_NORMAL_SETUP", "STAND_ASIDE_PRE_NEWS", "STAND_ASIDE", "DIRECTIONAL_BUY_BIAS", "DIRECTIONAL_SELL_BIAS" ] }, "trader_headline": { "type": "string" }, "reason_code": { "type": "string" }, "wait_seconds": { "type": "integer" }, "prop_wait_seconds": { "type": "integer" }, "explanation": { "type": "string" } } }, "LiveState": { "type": "object", "required": [ "status", "strength", "impulse_level", "veto_active", "veto_remaining_sec", "prop_window_remaining_sec", "safe_to_trade", "prop_safe_to_trade" ], "properties": { "status": { "type": "string", "enum": [ "CLEAR", "PRE_NEWS", "BUY", "SELL", "VETO" ] }, "strength": { "type": "string", "enum": [ "weak", "normal", "strong", "extreme" ] }, "impulse_level": { "type": "integer", "minimum": 0, "maximum": 4 }, "veto_active": { "type": "boolean" }, "veto_reason": { "type": [ "string", "null" ] }, "veto_until": { "type": [ "string", "null" ], "format": "date-time" }, "veto_remaining_sec": { "type": "integer" }, "prop_window_remaining_sec": { "type": "integer" }, "signal_age_sec": { "type": [ "integer", "null" ] }, "safe_to_trade": { "type": "boolean" }, "prop_safe_to_trade": { "type": "boolean" }, "trigger_event": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "CompactPairResponse": { "type": "object", "required": [ "ok", "symbol", "status", "prop_safe_to_trade", "safe_to_trade", "stale", "direction_bias", "impulse_level", "veto_remaining_sec", "veto_reason", "surprise_z", "updated_at" ], "properties": { "ok": { "type": "boolean", "const": true }, "symbol": { "type": "string", "enum": [ "EURUSD", "XAUUSD", "GBPUSD", "USDJPY", "XAGUSD", "EURJPY", "GBPJPY", "AUDUSD", "USDCAD", "USDCHF", "NZDUSD", "EURAUD", "GBPAUD", "CADJPY", "AUDJPY", "NZDJPY", "CHFJPY", "EURCHF" ] }, "status": { "type": "string", "enum": [ "CLEAR", "PRE_NEWS", "BUY", "SELL", "VETO" ] }, "prop_safe_to_trade": { "type": "boolean" }, "safe_to_trade": { "type": "boolean" }, "stale": { "type": "boolean" }, "direction_bias": { "type": "string", "enum": [ "BUY", "SELL", "NEUTRAL" ] }, "impulse_level": { "type": "integer", "minimum": 0, "maximum": 4 }, "veto_remaining_sec": { "type": "integer", "minimum": 0 }, "veto_reason": { "type": [ "string", "null" ] }, "surprise_z": { "type": [ "number", "null" ] }, "updated_at": { "type": "string", "format": "date-time" } } }, "PairDetailResponse": { "type": "object", "required": [ "ok", "schema", "generated_at", "symbol", "radar_health", "agent_guidance", "live_state", "recent_releases" ], "properties": { "ok": { "type": "boolean", "const": true }, "schema": { "type": "string", "example": "forexnewsradar.pair_detail.v4" }, "generated_at": { "type": "string", "format": "date-time" }, "symbol": { "type": "string", "enum": [ "EURUSD", "XAUUSD", "GBPUSD", "USDJPY", "XAGUSD", "EURJPY", "GBPJPY", "AUDUSD", "USDCAD", "USDCHF", "NZDUSD", "EURAUD", "GBPAUD", "CADJPY", "AUDJPY", "NZDJPY", "CHFJPY", "EURCHF" ] }, "requested_symbol": { "type": "string", "example": "EURUSD.pro" }, "display": { "type": "string", "example": "EUR/USD" }, "name": { "type": "string", "example": "Euro / US Dollar" }, "base": { "type": "string", "example": "EUR" }, "quote": { "type": "string", "example": "USD" }, "group": { "type": "string" }, "tier": { "type": "string", "enum": [ "free", "pro" ] }, "radar_health": { "$ref": "#/components/schemas/RadarHealth" }, "agent_guidance": { "$ref": "#/components/schemas/AgentGuidance" }, "live_state": { "$ref": "#/components/schemas/LiveState" }, "next_event": { "anyOf": [ { "$ref": "#/components/schemas/UpcomingCatalyst" }, { "type": "null" } ] }, "recent_releases": { "type": "array", "items": { "type": "object" } }, "archive_examples": { "type": "array", "items": { "type": "object" } }, "strategy_activity": { "type": "object" } } }, "PairsListResponse": { "type": "object", "required": [ "ok", "schema", "generated_at", "radar_health", "auth", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "schema": { "type": "string", "example": "forexnewsradar.pairs.v4" }, "compact": { "type": "boolean" }, "generated_at": { "type": "string", "format": "date-time" }, "synced_live": { "type": "boolean" }, "radar_health": { "$ref": "#/components/schemas/RadarHealth" }, "auth": { "type": "object" }, "plans": { "type": "array", "items": { "type": "object" } }, "data": { "type": "array", "items": { "type": "object" } } } }, "MacroFeedResponse": { "type": "object", "required": [ "ok", "schema", "generated_at", "radar_health", "subscription", "active_vetoes", "upcoming_events", "pair_matrix", "releases" ], "properties": { "ok": { "type": "boolean", "const": true }, "schema": { "type": "string", "example": "forexnewsradar.macro_feed.v4" }, "generated_at": { "type": "string", "format": "date-time" }, "radar_health": { "$ref": "#/components/schemas/RadarHealth" }, "subscription": { "type": "object" }, "active_vetoes": { "type": "array", "items": { "type": "object" } }, "upcoming_events": { "type": "array", "items": { "$ref": "#/components/schemas/UpcomingCatalyst" } }, "pair_matrix": { "type": "array", "items": { "type": "object" } }, "releases": { "type": "array", "items": { "type": "object" } } } }, "MeResponse": { "type": "object", "required": [ "ok", "schema", "authenticated", "tier", "scopes", "entitlements", "unlocked_pairs", "rate_limit" ], "properties": { "ok": { "type": "boolean", "const": true }, "schema": { "type": "string", "example": "forexnewsradar.me.v4" }, "authenticated": { "type": "boolean" }, "tier": { "type": "string", "enum": [ "free", "pro" ] }, "token_prefix": { "type": [ "string", "null" ] }, "plan_id": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "entitlements": { "type": "array", "items": { "type": "object", "properties": { "scope": { "type": "string" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } } }, "unlocked_pairs": { "type": "array", "items": { "type": "string" } }, "unlocked_count": { "type": "integer" }, "locked_pairs_count": { "type": "integer" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "web_sessions": { "type": "object" }, "rate_limit": { "type": "object", "properties": { "limit_per_minute": { "type": "integer" }, "remaining": { "type": "integer" }, "reset_in_sec": { "type": "integer" }, "reset_at_epoch": { "type": "integer" } } } } }, "PairLockedError": { "type": "object", "required": [ "ok", "error", "status", "symbol", "unlock_single_usdt", "unlock_all_18_usdt", "unlock_url" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string", "const": "pair_locked" }, "status": { "type": "integer", "const": 402 }, "symbol": { "type": "string", "example": "XAUUSD" }, "free_demo_endpoint": { "type": "string", "example": "https://forexnewsradar.com/api/v1/pairs/EURUSD" }, "unlock_single_usdt": { "type": "number", "example": 9 }, "unlock_all_18_usdt": { "type": "number", "example": 29 }, "unlock_url": { "type": "string", "example": "https://forexnewsradar.com/?unlock=XAUUSD" } } } } }, "paths": { "/api/v1/me": { "get": { "operationId": "getCallerEntitlements", "summary": "Inspect active token scopes, per-pair expiries, device slots, and rate limits", "security": [ {}, { "bearerAuth": [] } ], "responses": { "200": { "description": "Caller entitlement & rate-limit summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeResponse" } } } }, "401": { "description": "Invalid or expired Bearer token" } } } }, "/api/v1/pairs": { "get": { "operationId": "listPairs", "summary": "List all 18 FX & Metals pairs with live status for EURUSD + unlocked scopes", "security": [ {}, { "bearerAuth": [] } ], "parameters": [ { "name": "compact", "in": "query", "description": "Set compact=1 for slim payload suited to MT5 WebRequest polling", "schema": { "type": "integer", "enum": [ 0, 1 ] } } ], "responses": { "200": { "description": "18-pair catalog in demand-priority order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PairsListResponse" } } } }, "401": { "description": "Invalid or expired Bearer token" }, "429": { "description": "Rate limit exceeded" } } } }, "/api/v1/pairs/{symbol}": { "get": { "operationId": "getPairIntelligence", "summary": "Get live signal/veto status, prop_safe_to_trade gate, upcoming catalyst countdown, and macro releases for a pair (broker suffixes normalized automatically)", "security": [ {}, { "bearerAuth": [] } ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "Canonical ticker or broker symbol (e.g. EURUSD, EURUSD.pro, XAUUSDm, GBP/USD). EURUSD is free without key.", "schema": { "type": "string", "example": "EURUSD" } }, { "name": "compact", "in": "query", "description": "Set compact=1 (or format=compact) for a ~240-byte single-object response designed for MetaTrader 5 WebRequest() polling.", "schema": { "type": "integer", "enum": [ 0, 1 ] } } ], "responses": { "200": { "description": "Live pair quantitative telemetry (or CompactPairResponse when compact=1)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PairDetailResponse" }, { "$ref": "#/components/schemas/CompactPairResponse" } ] } } } }, "402": { "description": "Pair is locked — purchase single pair (9 USDT/mo) or all 18 pairs (29 USDT/mo)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PairLockedError" } } } }, "404": { "description": "Unknown symbol" }, "429": { "description": "Rate limit exceeded" } } } }, "/api/v1/feed": { "get": { "operationId": "getMacroFeed", "summary": "Normalized macro news, upcoming catalysts, & active VETO stream (EURUSD free without token; all unlocked pairs with token)", "security": [ {}, { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Number of historical releases to return (0 returns matrix & vetoes only)", "schema": { "type": "integer", "minimum": 0, "maximum": 50, "default": 20 } }, { "name": "currency", "in": "query", "schema": { "type": "string", "example": "USD" } }, { "name": "symbol", "in": "query", "schema": { "type": "string", "example": "XAUUSD" } } ], "responses": { "200": { "description": "Live macro release, upcoming catalyst, & VETO stream", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MacroFeedResponse" } } } }, "402": { "description": "Requested symbol filter is locked for current token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PairLockedError" } } } }, "429": { "description": "Rate limit exceeded" } } } } } }