WebSocket release streams

Endpoint contract

Connect directly to the API WebSocket host.

The WebSocket stream uses the same announcement event source as SSE. Query parameters match the SSE stream, while each server message is a JSON text frame with a top-level type.

Minimal URL:

wss://api.fxmacrodata.com/v1/ws/events?currencies=usd&indicators=inflation&payload=full

Authentication and filters

Use query parameters for browser-compatible auth.

Browser WebSocket constructors cannot set custom request headers, so query-parameter authentication is the most portable option. Server-side clients may use X-API-Key during the upgrade request.

Message schema

Each announcement message wraps the release payload.

The envelope gives your client a stable message type and ID. The data object uses the same compact or full payload shape as the SSE stream.

{"type":"connected","stream":"announcement_events","protocol":"websocket","payload":"full","currencies":["usd"],"indicators":["inflation"],"last_event_id":null,"heartbeat_interval_seconds":15,"subscriber_count":1}

{"type":"announcement","event":"announcement","id":"usd_inflation_1772109000","data":{"event_id":"usd_inflation_1772109000","currency":"usd","indicator":"inflation","records_written":1,"timestamp":1772109002,"latest_announcement":{"date":"2026-02-28","val":3.1,"announcement_datetime":1772109000},"date":"2026-02-28","val":3.1,"forecast":3.0,"previous":3.1,"announcement_datetime":1772109000}}

Client examples

Connect, parse, dedupe, and reconnect.

Browser client

Use native WebSocket and query-parameter auth.

const apiKey = "YOUR_API_KEY";
const wsUrl = new URL("wss://api.fxmacrodata.com/v1/ws/events");
wsUrl.searchParams.set("currencies", "eur,gbp");
wsUrl.searchParams.set("indicators", "inflation,policy_rate");
wsUrl.searchParams.set("payload", "full");
wsUrl.searchParams.set("api_key", apiKey);

let lastEventId = null;
let socket = null;

function connect() {
  if (lastEventId) {
    wsUrl.searchParams.set("last_event_id", lastEventId);
  }

  socket = new WebSocket(wsUrl);

  socket.addEventListener("message", async ({ data }) => {
    const message = JSON.parse(data);
    if (message.type === "announcement") {
      lastEventId = message.id;
      renderRelease(message.data);
    }
    if (message.type === "error") {
      showStreamError(message.code, message.message);
    }
  });

  socket.addEventListener("close", () => {
    window.setTimeout(connect, 3000);
  });
}

connect();

Python worker

Use a WebSocket client library for persistent workers.

import asyncio
import json
from urllib.parse import urlencode

import websockets


API_KEY = "YOUR_API_KEY"
BASE_URL = "wss://api.fxmacrodata.com/v1/ws/events"


async def consume() -> None:
    last_event_id = None

    while True:
        params = {
            "currencies": "eur,gbp",
            "indicators": "inflation,policy_rate",
            "payload": "full",
            "api_key": API_KEY,
        }
        if last_event_id:
            params["last_event_id"] = last_event_id

        try:
            async with websockets.connect(f"{BASE_URL}?{urlencode(params)}") as ws:
                async for raw_message in ws:
                    message = json.loads(raw_message)
                    if message["type"] == "announcement":
                        last_event_id = message["id"]
                        print(message["data"])
        except Exception as exc:
            print(f"WebSocket disconnected: {exc}; reconnecting in 3 seconds")
            await asyncio.sleep(3)


asyncio.run(consume())

Related docs

Use WebSocket streams with the rest of the API surface.