# Broker-Radar (calendar) v1.1.0 Live economic-calendar feed across multiple calendars (economic, crypto, metals, energy). Live updates push over WebSocket (wss://ws4.broker-radar.com/ws/calendar) and optional webhooks; per-source REST endpoints serve current data plus backfilled history via the kickoff endpoint. Multilingual: add ?lang= to the events endpoints to get event names in that language (English by default) — see GET /calendar/languages. Base: https://api3.broker-radar.com Generated: 2026-11-21T12:58:17.159Z > AI agents: prefer GET /help?format=json — same content as this page in structured form. ## Agent quickstart 1. GET /calendar/sources → per-source counts + earliest/latest dateline. Use this to see what's already cached. 2. If you need history beyond the cached range, POST /calendar/:source/backfill (HMAC-signed) with {from, to} as month slugs like "jan.2024" → returns 202 + jobId. 3. Poll GET /calendar/:source/backfill/:jobId every ~10s until status=completed. 4. For browse / list flows, GET /calendar/:source/events?from=YYYY-MM-DD&to=YYYY-MM-DD&impact=high. Always paginate with limit (default 1000, max 5000). 5. Non-English names: GET /calendar/languages for supported codes, then add ?lang=fa to any events endpoint — the event 'name' comes back localized (English fallback), and 'name_en' + 'name_i18n' ({en, fa, ...}) are always included. WS/webhook frames carry static.translations for the same purpose. 6. For live updates, open WS wss://ws4.broker-radar.com/ws/calendar (canonical; wss://api3.broker-radar.com/ws/calendar works too) — first frame is {kind:"snapshot"}, subsequent frames are {kind:"change"} with the changed live fields. Reconnect on any error with exponential backoff. 7. Webhook alternative for live updates: register your endpoint with the operator. You'll receive the same change frames as HMAC-signed POSTs (good for serverless consumers). ## 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://api3.broker-radar.com/help?format=json ### GET /healthz Per-source liveness. Returns 200 even when degraded; check the body to decide if the feed is usable. May include additional operator-only fields not listed here — ignore them. Response shape: { ok, mode:"calendar", uptimeMs, workers:[{source, ...}], storeSize, wsSubscribers, ... } Example: https://api3.broker-radar.com/healthz ### GET /calendar/sources Per-source counts and dateline coverage. Use this to find out what's already cached before triggering a backfill. Response shape: { success:true, sources:[{source, total, withActual, earliestDateline, latestDateline}], timestamp } Example: https://api3.broker-radar.com/calendar/sources ### GET /calendar/languages Supported languages for event names + coverage. Use the codes with ?lang= on the events endpoints. English (en) is always available; untranslated names fall back to English. Response shape: { success:true, default:"en", languages:[{code, name, native, names}], usage, timestamp } Example: https://api3.broker-radar.com/calendar/languages ### GET /calendar/:source/events List events for one source. Use ?from/?to (ISO dates) to slice a date range and ?impact=high to filter by impact. Path params: - :source: One of: economic | crypto | metals | energy. Query: - from: ISO date (inclusive lower bound on dateline) - to: ISO date (exclusive upper bound on dateline) - impact: holiday | low | medium | high - limit: Max rows (default 1000, max 5000) - lang: Language code for names (default en). See /calendar/languages. name_en + name_i18n always included. Response shape: { success:true, source, lang, total, events:[{static:{source, eventId, dateline, name (localized to lang), name_en, name_i18n:{en, fa}, currency, countryCode, impact, detailUrl (source-site permalink), apiUrl (this API's detail route)}, live:{actual, forecast, previous, revision, hasNotice, updatedAt}}], timestamp } Example: https://api3.broker-radar.com/calendar/economic/events?from=2026-05-01&to=2026-06-01&impact=high&lang=fa ### GET /calendar/:source/events/:eventId Single event + rich detail (specs & release history). Path params: - :source: One of: economic | crypto | metals | energy. - :eventId: Numeric event id (from list response). Query: - lang: Language code (default en). Localizes name + detail spec title/text where a translation exists. Response shape: { success:true, lang, event:{static:{…, apiUrl, soloUrl, ebaseId}, live:{…}, detail:{specs:[{key, title, html, text, order, title_en?, text_en?}], history:[{eventId, date, impact, actual, forecast, previous, revision}], historyHasMore, nextRelease:{date, eventId}|null, soloUrl, ebaseId, fetchedAt} | null}, detailStatus?:"pending" } Example: https://api3.broker-radar.com/calendar/economic/events/149355 ### POST /calendar/:source/backfill (auth: hmac) Kick off a historical (or future) backfill for one source. HMAC-protected. Body: {from, to} as month slugs like "jan.2024". Returns 202 with the job id; poll the status endpoint until status=completed. Path params: - :source: One of: economic | crypto | metals | energy. Response shape: { success:true, job:{jobId, source, from, to, status, monthsTotal, monthsCompleted, eventsUpserted, startedAt, finishedAt|null, error|null} } Example: curl -X POST https://api3.broker-radar.com/calendar/economic/backfill \ -H 'x-hmac: ' \ -H 'Content-Type: application/json' \ -d '{"from":"jan.2024","to":"dec.2026"}' ### GET /calendar/:source/backfill List backfill jobs for one source (newest first). Response shape: { success:true, source, jobs:[{jobId, status, monthsTotal, monthsCompleted, eventsUpserted, startedAt, finishedAt|null}] } Example: https://api3.broker-radar.com/calendar/economic/backfill ### GET /calendar/:source/backfill/:jobId Status of one backfill job; poll until status=completed. Response shape: { success:true, job:{jobId, status:"queued"|"running"|"completed"|"failed", monthsTotal, monthsCompleted, eventsUpserted, error|null} } Example: https://api3.broker-radar.com/calendar/economic/backfill/ ### GET /calendar/events Combined snapshot across all sources (current week only — does NOT include backfilled history). Use the per-source endpoints for full coverage. Query: - source: Optional: economic | crypto | metals | energy Response shape: { success:true, total, source:"all"|, events:[{static:{...}, live:{...}}], timestamp } Example: https://api3.broker-radar.com/calendar/events?source=economic ### WS /ws/calendar Live update stream. Server sends one JSON frame per state change. First frame after connect is {kind:"snapshot"} bootstrap; every subsequent frame is {kind:"change"} with the changed live fields and the post-change event. Query: - source: Optional source filter (same values as REST). Response shape: # initial frame { kind:"snapshot", source:|null, events:[{static:{...}, live:{...}}] } # subsequent change frames { kind:"change", source, eventId, changed:{actual?, forecast?, previous?, revision?, hasNotice?}, event:{static:{...}, live:{...}} } Example: wss://ws4.broker-radar.com/ws/calendar?source=economic ## Payload fields - `static.source` (string) (one of: economic, crypto, metals, energy) — Which calendar this event came from. - `static.eventId` (number) — Numeric event id; (source, eventId) is the global unique key. - `static.dateline` (number) — Scheduled release time as Unix SECONDS (UTC). - `static.name` (string) — English event headline (e.g. "Non-Farm Employment Change"). - `static.currency / static.countryCode` (string) — ISO codes. Empty string for All-Day or Tentative events. - `static.impact` (string) (one of: holiday, low, medium, high) — Impact tag. - `static.detailUrl` (string) — Permalink on the source calendar's own site (relative URL), NOT this API. To fetch this event from us, use `apiUrl` instead. - `static.apiUrl` (string) — Absolute link back to THIS API's single-event detail route (e.g. "https://rest4.broker-radar.com/calendar/economic/events/149355"). Carries ?lang= when a non-default language was requested. GET it to retrieve this one event. - `live.actual / live.forecast / live.previous / live.revision` (string) — Release values. STRINGS (values are sometimes non-numeric, e.g. "<0.01"). Empty string when not yet published. - `live.hasNotice` (boolean) — An editorial notice is attached to this event (e.g., "Postponed"). - `live.updatedAt` (number) — Unix MILLISECONDS of the last live update. 0 if never updated. - `detail (single-event route only)` (object | null) — Rich detail for the event: specs[] (Source, Measures, Usual Effect, Frequency, Next Release, Notes, Why Traders Care, Derived Via, Also Called, Acro Expand — each with `html` and tag-stripped `text`), history[] (past releases of the series), soloUrl (the source's own detail page), ebaseId. NULL with top-level detailStatus:"pending" means it's being prepared on demand — retry in a moment. Omitted entirely on the list route to keep it lean. ## Filter / query rules - `?from` — Inclusive lower bound on event dateline (i.e. release time). - Format: ISO date YYYY-MM-DD (UTC). Optional. - Example: `?from=2026-05-01` - `?to` — Exclusive upper bound on event dateline. - Format: ISO date YYYY-MM-DD (UTC). Optional. - Example: `?to=2026-06-01` - `?impact` — Filter to a single impact tier. - Format: Lowercase enum. - Example: `?impact=high` - `?limit` — Cap response size. - Format: Integer 1..5000. - Example: `?limit=200` - Notes: Default 1000. ## Auth (HMAC) - Header: `x-hmac` - Algorithm: HMAC-SHA256 over the raw request body (bytes as sent). - Scope: Required on POST /calendar/:source/backfill. Example: # bash + openssl example. SHARED_SECRET is the value provisioned out-of-band by the operator. BODY='{"from":"jan.2024","to":"dec.2026"}' SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SHARED_SECRET" | awk '{print $2}') curl -X POST https://api3.broker-radar.com/calendar/economic/backfill \ -H "x-hmac: $SIG" \ -H "Content-Type: application/json" \ -d "$BODY" Note: Webhook consumers receive the same change frames in their POST body, HMAC-signed in `x-calendar-signature` over `.` (note the prefix). Verify the timestamp is within ~5 min to defend against replay. ## Freshness contract Static event metadata (name/currency/impact/dateline) refreshes every ~6 hours and on every successful backfill month. Live release values arrive via WS within ~2s of publication. WS frame silence is NOT degradation on its own — outside release windows there's nothing to push. ## Error responses 4xx responses ALWAYS carry success:false plus an `error` string. 500s log on the server; consumers should retry idempotent reads with backoff. Example: {"success":false,"error":"unknown source; expected one of economic, crypto, metals, energy"} ## Notes - Per-source endpoints include backfilled history. The combined /calendar/events and the WS snapshot frame cover the current week only. - Consume live updates via this service's WS (canonical: wss://ws4.broker-radar.com/ws/calendar). - Reconnect strategy: on WS close, wait 1s, reconnect; if 3 failures inside 30s, switch to REST polling (/calendar/:source/events) until the WS recovers. Always re-subscribe with the same ?source filter.