# Broker-Radar (brokers) v1.1.0 Broker spreads feed. Live spread data across a broad set of retail brokers, returned in a stable JSON cell shape you can integrate directly. Base: https://api1.broker-radar.com Generated: 2026-11-21T12:58:08.719Z > AI agents: prefer GET /help?format=json — same content as this page in structured form. ## Agent quickstart 1. GET /public/brokers → array of {broker, account, name}. Cache the slug list; it changes rarely. 2. For ONE broker: GET /public/spreads/{broker}/{account}?symbols=EURUSD,XAUUSD → JSON cell envelope. For MANY brokers do NOT loop this — GET /public/spreads-bulk?brokers=slug1,slug2,...&symbols=EURUSD,XAUUSD instead (one snapshot read, never rate-limits). See the /public/spreads-bulk endpoint + filterRules.brokers. 3. Inspect each cell.market_status — "open" means usable numerics; any other value (Weekend_Market_Closed / Rollover / Holiday_Market_Close) means bid/ask/spread are status strings, not numbers. 4. Poll /healthz to check liveness (ok=true) and data freshness. Treat data older than ~5 min during open market as degraded. ## Endpoints ### GET /help This page. Returns markdown by default; add ?format=json for the structured payload (preferred for AI agents). Query: - format: md (default) | json Example: https://api1.broker-radar.com/help?format=json ### GET /healthz Feed liveness + freshness snapshot. Returns 200 even when degraded; check the body fields (ok, market.status, and the recency of the data) to decide if the feed is usable. May include additional operator-only fields not listed here — ignore them; they can change without notice. Response shape: { ok:boolean, uptimeMs, brokerCount, cellCount, market:{status:"open"|"closed", symbols:[{symbolId, code, lastChangeAt, idle}]}, ... } Example: https://api1.broker-radar.com/healthz ### GET /public/brokers Full catalog list of every brokers pair the feed knows about. Built from the static catalog (NOT the live snapshot) so list is stable across weekends and market closures. Response shape: { success:true, total:, data:[{ broker, account, name }], timestamp } Example: https://api1.broker-radar.com/public/brokers ### GET /public/spreads/:broker/:account Spread cells for one broker/account pair. Stable JSON payload shape. Use the symbols query to limit response size. Path params: - :broker: Slug from /public/brokers (case-insensitive). - :account: Account label (e.g. Alpari-Pro.ECN). The server returns the canonical account_type when it has one. Query: - symbols: Optional. Comma-separated symbol codes WITHOUT slash (e.g. EURUSD,XAUUSD,US30). See filterRules.symbols for full rules. Response shape: { success:true, broker, account, total:, data:[{ symbol, common_suffix, time, time_msc, bid, ask, spread, spread_points, spread_raw, market_status, digits, point, contract_size, volume_min, volume_max, leverage, broker_name, account_type, source }], timestamp } Example: https://api1.broker-radar.com/public/spreads/alpari/Alpari-Pro.ECN?symbols=EURUSD,XAUUSD ### GET /public/spreads-bulk BULK: spread cells for MANY brokers in ONE request, served from a single snapshot read. Use this instead of calling the per-broker endpoint in a loop — it never rate-limits, no matter how many brokers you ask for. Each entry in `results` is byte-for-byte the same envelope the single endpoint returns. Query: - brokers: REQUIRED. Comma-separated broker specs. Each spec is: [+accountType...][:SYM|SYM...]. '+' appends a case-insensitive account-type include-filter (e.g. pepperstone+ecn keeps the row only if the broker's account_type contains "ecn"; omit to keep regardless). ':' gives that one broker its own symbol list (members separated by '|', since ',' separates brokers), overriding the shared symbols param. Up to 80 brokers per request. See filterRules.brokers. - symbols: Optional. Shared symbol list applied to every spec that has no per-spec ':' override. Same codes/rules as the single endpoint — see filterRules.symbols. Response shape: { success:true, count:, timestamp, results:{ "": , ... }, skipped?:{ "": "unknown_broker"|"no_data"|"account_type_mismatch" } } Example: https://api1.broker-radar.com/public/spreads-bulk?brokers=alpari+ecn,icmarkets:EURUSD|XAUUSD&symbols=EURUSD,XAUUSD ### WS /ws/spreads WebSocket: live spread cells for the brokers you subscribe to, pushed whenever they change (looked at every second). Send {"op":"subscribe","brokers":["alpari"],"symbols":["EURUSD","XAUUSD"]} (symbols optional, up to 50 brokers a connection); {"op":"unsubscribe","brokers":[...]} stops one. A browser passes the key as ?key=. A broker outside your plan gets an error frame with status 402; a revoked, narrowed or lapsed key closes the stream with 4001, 4003 or 4002. Response shape: { kind:"snapshot"|"update", broker, data: } | { kind:"error", broker?, status?, message } | { kind:"unsubscribed", brokers } Example: wss://api1.broker-radar.com/ws/spreads?key=YOUR_API_KEY ## Payload fields - `symbol` (string) — Canonical symbol code, no slash (e.g. "EURUSD", "XAUUSD", "US30"). - `common_suffix` (string) — Duplicate of `symbol`; kept for backward compatibility. - `time` (number) — Tick timestamp in Unix SECONDS (UTC). On Typical_Spread or closed cells this is the time of the last live observation, not now. - `time_msc` (number) — Tick timestamp in Unix MILLISECONDS (UTC). 1000× of `time`. - `bid` (number | string) — Mid price minus half-spread, in price units. STRING when market_status != "open" (collapses to the status label) OR when the cell carries a typical spread with no published mid price. - `ask` (number | string) — Mid price plus half-spread, in price units. Same string-collapse rules as bid. - `spread` (number | string) — Spread in PRICE UNITS (i.e. spread_points × point). For EURUSD at 0.4 pips: spread=0.00004. Same string-collapse rules. - `spread_points` (number | string) — Spread in POINTS (= 10 × pips on 5-digit pairs). For EURUSD at 0.4 pips: spread_points=4. Integer. Same string-collapse rules. - `spread_raw` (number | string) — Identical to spread_points; kept for backward compatibility. - `market_status` (string) (one of: open, Weekend_Market_Closed, Rollover, Holiday_Market_Close) — One of the enum values in marketStatusLabels (e.g. "open", "Typical_Spread", "Weekend_Market_Closed"). When != "open", numeric fields collapse to this same string. - `digits` (number) — Decimal precision the symbol quotes at (5 for EURUSD, 3 for USDJPY, 2 for XAUUSD). Always populated. - `point` (number) — Size of one point in price units (= 10^-digits). - `contract_size` (number) — Standard lot size (100,000 for FX majors, 100 for XAUUSD, 5,000 for XAGUSD, 1 for indices/crypto). - `volume_min / volume_max` (number) — Min / max tradeable lot size. - `leverage` (number) — Typical retail leverage for the symbol class. Indicative, not broker-specific. - `broker_name` (string) — Display name (e.g. "FundingPips"). - `account_type` (string) — Canonical account label (e.g. "Alpari-Pro.ECN"). The server returns this in place of whatever you passed in the URL when it has the canonical value. - `source` (string) (one of: Broker-Radar.com Liquidity Solution) — Which Broker-Radar feed produced this cell. See the sources section for the full list of values and their freshness. ## market_status enum - `open` — Market is live and the cell holds real numeric bid/ask/spread. _(when: Weekday during the symbol's session, realtime source only.)_ - `Weekend_Market_Closed` — Numeric fields collapse to this string. time/time_msc retain the last real tick. _(when: Saturday / Sunday / Friday after the symbol's last session-end (UTC).)_ - `Rollover` — Numeric fields collapse to this string during the daily rollover window. _(when: Weekday ~21:00–22:00 UTC for FX.)_ - `Holiday_Market_Close` — Numeric fields collapse to this string. Likely a public holiday or a temporary data outage. _(when: Weekday where no broker has reported a tick for the symbol in ~5 minutes.)_ ## Data sources - `source = "Broker-Radar.com Liquidity Solution"` - Live feed with full bid/ask + spread. - Freshness: Sub-second live ticks while the market is open; reflected by the freshness fields in /healthz. - Bid/ask populated: yes ## Filter / query rules - `?symbols` — Comma-separated list of symbol codes to keep in the response. Omit to get all symbols. - Format: Codes are case-insensitive, NO SLASH, no spaces (EURUSD not EUR/USD). Server canonicalizes to uppercase-no-slash internally. - Example: `?symbols=EURUSD,XAUUSD,US30` - Notes: Up to 9 symbols today. Unknown symbol codes are silently dropped (no error). - `?brokers` — Bulk endpoint only (/public/spreads-bulk). Comma-separated list of broker specs to fetch in one shot. - Format: Per spec: [+type][+type][:SYM|SYM]. ',' separates specs, '+' separates account-type filter tokens, ':' starts a per-spec symbol override whose members are '|'-separated. Slugs/types case-insensitive; symbols uppercased no-slash. ('+' decodes to a space in query strings; the server treats space and '+' identically here, so both `slug+ecn` and a literal space work.) - Example: `?brokers=pepperstone+ecn,icmarkets+raw:GBPUSD|EURUSD,fxpro&symbols=EURUSD,XAUUSD` - Notes: Account-type is a single fixed label per broker (there is no ECN/Standard variant set) — '+type' acts purely as an include-if-match filter; a spec that matches nothing lands in 'skipped' with reason "account_type_mismatch". Unknown slug → "unknown_broker"; recognised slug with no live cells → "no_data". Unlike the single endpoint, the bulk endpoint does not fetch unknown slugs on demand. Max 80 specs; duplicates collapse (last wins). ## Freshness contract Treat as stale if the data hasn't advanced in >60s during open market. On cold start the first snapshot takes ~25s. ## Error responses 4xx/5xx responses ALWAYS carry success:false plus either `message` or `error`. Some routing misses return plain text/HTML instead — treat any non-2xx with non-JSON body as a 404. Example: {"success":false,"message":"no snapshot yet, feed still priming","data":[]} ## Notes - Closed cells: when market_status is not "open" or "Typical_Spread", numeric fields (bid/ask/spread/spread_points/spread_raw) collapse to the same status string. time/time_msc retain the last real tick. Static fields (digits/point/contract_size/leverage) stay populated. - The /public/brokers listing enumerates the supported broker slugs; treat it as the source of truth. - CORS: requests with an Origin header outside the configured allowlist receive a 403. Server-to-server requests (no Origin header, e.g. curl from a backend) always pass. - Rate limits: this service has no built-in per-request rate limit.