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. Announcement frames arrive only when a release is ingested; heartbeat frames keep idle connections observable.

Minimal connection (URL plus upgrade header):

wss://api.fxmacrodata.com/v1/ws/events?currencies=usd&indicators=inflation&payload=full
X-API-Key: YOUR_API_KEY

Authentication and filters

Send your key in the X-API-Key header.

The WebSocket stream is designed for server-side clients. Send your key as an X-API-Key header on the upgrade request; WebSocket libraries such as Node.js ws and Python websockets support custom headers. Live WebSocket delivery requires an active trial or subscription API key.

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.

Node.js worker

Send the key in the upgrade request headers.

import WebSocket from "ws";

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");

let lastEventId = null;

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

  const socket = new WebSocket(wsUrl, {
    headers: { "X-API-Key": process.env.FXMD_API_KEY },
  });

  socket.on("message", (raw) => {
    const message = JSON.parse(raw.toString());
    if (message.type === "announcement") {
      lastEventId = message.id;
      handleRelease(message.data);
    }
    if (message.type === "error") {
      process.stderr.write(`${message.code}: ${message.message}\n`);
    }
  });

  socket.on("close", () => {
    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",
        }
        if last_event_id:
            params["last_event_id"] = last_event_id

        try:
            async with websockets.connect(
                f"{BASE_URL}?{urlencode(params)}",
                additional_headers={"X-API-Key": API_KEY},
            ) 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.