# rates-feed Live Iranian-market rates: 38 fiat currencies quoted against the Toman and 7 domestic gold instruments. Every price is a POOLED RANGE — the lowest and highest quote across several independent market sources — not a single dealer's number. Snapshot over REST at https://api4.broker-radar.com/rates; live updates push over WebSocket at wss://api4.broker-radar.com/ws/rates. ## Quickstart 1. EVERY data request needs an API key from https://portal.broker-radar.com. Send it as `X-API-Key: `, `Authorization: Bearer `, or `?key=` — the last is the only option for a browser WebSocket. Without one you get 401. Only /healthz and /help are open. 2. GET https://api4.broker-radar.com/rates for everything, or /rates/fx and /rates/gold for one family. 3. Each instrument carries `buy` and/or `sell` as {low, high} in Toman, plus `quotes` = how many sources backed that range. 4. A range where low == high means only one source currently quotes that instrument. 5. `unit_multiplier` appears on symbols quoted per MORE than one unit (100 for amd/iqd/jpy/krw/syp — e.g. amd is 100 Armenian dram). It is omitted when the quote is per single unit. Ignore it and those five are wrong by 100x. 6. For live updates open WS wss://api4.broker-radar.com/ws/rates?key=. First frame is {kind:"snapshot"}; every frame after is {kind:"change"} carrying ONLY the bands that moved. Reconnect with exponential backoff on any error. 7. Poll https://api4.broker-radar.com/healthz for freshness — `lastFetchAgeSec` is the age of the current snapshot. ## Endpoints ### GET /rates Full snapshot: every FX pair and gold instrument, each as a pooled low/high band in Toman. https://api4.broker-radar.com/rates Note: Values are Toman, not Rial. Gold instruments are priced per their own unit (a gram for 18-carat, a full coin for سکه). ### GET /rates/fx FX only — 38 fiat currencies against the Toman. https://api4.broker-radar.com/rates/fx Note: `currency_iso` is null for compound market variants that do not map onto a single ISO 4217 code. ### GET /rates/gold Domestic gold only — melted gold, 18-carat gram, and the coin series. https://api4.broker-radar.com/rates/gold ### GET /healthz Liveness plus snapshot freshness. Never gated, safe to poll. https://api4.broker-radar.com/healthz Note: status is "degraded" when the snapshot is older than three poll intervals. It still answers 200 with the last good data — degraded means stale, not down. `unmatched` counts upstream rows outside our catalog and sits at 11 normally. The `persistence` block is operator telemetry about a downstream database write and says nothing about the freshness of what you are reading. ### WS /ws/rates Live updates. Snapshot frame on connect, then partial change frames. wss://api4.broker-radar.com/ws/rates Note: A change frame lists only instruments that actually moved, and within those only the bands that changed — apply it as a partial patch. Instruments that vanish from a source do NOT emit a frame; sources drop rows transiently and erasing on that would lose good data. ### GET /help This document. Parameters: - format: "json" for the machine-readable doc; anything else renders markdown. https://api4.broker-radar.com/help?format=json ## Notes - Every response carries `success`, `total`, and `timestamp` (RFC-3339, millisecond precision) — the same envelope as the other Broker Radar feeds. - Prices serialize as JSON numbers with a decimal point (51590.0). They are whole Toman; the .0 is a serialization artefact, not precision. - A 401 means the key is missing, wrong, revoked, or blocked by an IP/Origin restriction set on it. The response body says which. If a restriction is the cause and you did not set it, contact whoever issued the key. - All prices are in TOMAN. If you are comparing against a source that quotes Rial, divide that source by 10. - `symbol` is unique WITHIN a family, not across them: `sek` is the Swedish krona in fx (~20,200) and the gram gold coin in gold (~20,370,000). If you merge /rates/fx and /rates/gold into one map, key it on family+symbol or the coin will overwrite the currency. - `quotes` tells you how many independent sources backed a band, so you can weigh a wide range against a thin one. Which sources they are is not disclosed. - A wide band is information, not an error: it means the market genuinely disagrees right now. Sources that disagree violently with their peers are quarantined before publication rather than widening the band. - Prices refresh on a ~60s cycle. Upstream markets move on a several-minute rhythm, so a change frame typically arrives every few minutes during trading hours and rarely outside them. - Frame silence is not degradation on its own — if nothing moved, there is nothing to push. Use /healthz lastFetchAgeSec to distinguish a quiet market from a stalled feed.