How to Use All FXMacroData API Endpoints: A Complete Guide

By the end of this guide you will have working examples for each endpoint family in the FXMacroData API, from announcement series and the release calendar to COT positioning, commodities, FX rates, rate curves, market sessions and real-time release delivery. Every sample response below is a real, trimmed API response captured on 5 October 2026, so you can see the actual field names and values you will parse.

Endpoint map at a glance

The production API covers 22 currencies: AUD, BRL, CAD, CHF, CNH, CNY, DKK, EUR, GBP, HUF, ILS, JPY, KRW, MYR, NGN, NOK, NZD, PEN, SEK, THB, TWD and USD. The table groups the paths in the public API reference by family. "Free" means the route answers without a key; "USD free" means USD works without a key and every other currency needs one; "Plan key" means every request needs an Individual or Business key.

Authenticated examples all use the same header. Replace YOUR_API_KEY with the key from your account page:

X-API-Key: YOUR_API_KEY

Step 1 — Announcements: historical indicator series

The announcements endpoint is the core of FXMacroData. It returns a normalized, timestamped time series for a macroeconomic indicator. Each row carries the reference-period date (month-end for monthly data), the released value val, the prior value and the change from it, and the exact publication time as an epoch-seconds announcement_datetime.

USD requests work without a key on the free tier. For any other currency, send your key in the header. Use start_date and end_date (YYYY-MM-DD) to set the window. Rows come back newest first, 20 per page by default; use limit (up to 100) and offset to page.

# USD CPI inflation: no key needed on the free tier
curl "https://api.fxmacrodata.com/v1/announcements/usd/inflation"

# AUD policy rate: plan key required
curl -H "X-API-Key: YOUR_API_KEY" "https://api.fxmacrodata.com/v1/announcements/aud/policy_rate"

# EUR GDP with a custom date range
curl -H "X-API-Key: YOUR_API_KEY" "https://api.fxmacrodata.com/v1/announcements/eur/gdp?start_date=2024-01-01&end_date=2026-09-30"

The newest row of the USD CPI response, trimmed (the full response adds provenance, revision history and data-quality blocks):

{
  "currency": "USD",
  "indicator": "inflation",
  "name": "Inflation (CPI)",
  "source": "BLS",
  "latest_available_date": "2026-08-31",
  "data": [
    {
      "date": "2026-08-31",
      "val": 3.4,
      "previous_value": 3.4,
      "previous_date": "2026-07-31",
      "change_from_previous": 0.0,
      "val_mom": 0.4,
      "announcement_datetime": 1789129800,
      "announcement_datetime_local": "2026-09-11T08:30:00-04:00"
    }
  ]
}

The announcement_datetime field (seconds, UTC) is the moment the figure was officially published, here 12:30 UTC on 11 September 2026 for August CPI. Use it for event-study alignment and to avoid look-ahead bias in backtests. For a one-call snapshot of the most recent print of every indicator in a currency, use /v1/announcements/usd/latest. Indicator slugs and history for USD inflation are documented on the USD inflation API page.

Step 2 — Release Calendar: upcoming announcement times

The calendar endpoint returns the scheduled announcement timestamps for upcoming macro releases in a currency. Use it to schedule a targeted fetch at release time rather than polling on a fixed interval. USD works without a key; other currencies need one. Filter with the optional indicator parameter, and pass timezone (an IANA name) for an extra converted timestamp. The special code COMM returns the commodity release schedule.

# Upcoming USD non-farm payrolls releases: no key needed
curl "https://api.fxmacrodata.com/v1/calendar/usd?indicator=non_farm_payrolls"

# All upcoming EUR releases
curl -H "X-API-Key: YOUR_API_KEY" "https://api.fxmacrodata.com/v1/calendar/eur"

# Commodity release schedule
curl -H "X-API-Key: YOUR_API_KEY" "https://api.fxmacrodata.com/v1/calendar/COMM"

The first row of the USD payrolls response, trimmed:

{
  "currency": "USD",
  "timezone": "America/New_York",
  "indicator": "non_farm_payrolls",
  "data": [
    {
      "release": "non_farm_payrolls",
      "name": "Nonfarm Payrolls",
      "announcement_datetime": 1793971800,
      "announcement_datetime_utc": "2026-11-06T13:30:00+00:00",
      "announcement_datetime_local": "2026-11-06T08:30:00-05:00",
      "reference_period": "October 2026",
      "date": "2026-10-31",
      "release_date_confirmed": true,
      "event_importance": "high"
    }
  ]
}

Convert the epoch timestamp with datetime.fromtimestamp(ts, tz=timezone.utc) in Python or new Date(ts * 1000).toISOString() in JavaScript. For a complete scheduling pattern, see How to Use the Release Calendar API to Schedule Indicator Fetches, or browse the release calendar dashboard.

Step 3 — Data Catalogue: discover available indicators

Before writing code that targets a specific indicator, query the catalogue to confirm what exists for a currency. The response maps each indicator slug to its name, unit, source, release frequency, coverage metadata and whether an official forecast exists. No key is required.

# List all indicators for EUR
curl "https://api.fxmacrodata.com/v1/data_catalogue/eur"

# Add routing and capability metadata per indicator
curl "https://api.fxmacrodata.com/v1/data_catalogue/usd?include_capabilities=true"

Three of the 36 EUR entries, trimmed to their headline fields:

{
  "gdp": {
    "name": "GDP",
    "unit": "EUR bn",
    "frequency": "Quarterly",
    "source": "Eurostat",
    "has_official_forecast": true
  },
  "inflation": {
    "name": "Inflation (HICP)",
    "unit": "%YoY",
    "frequency": "Monthly",
    "source": "ECB / Eurostat",
    "has_official_forecast": true
  },
  "policy_rate": {
    "name": "ECB Deposit Facility Rate",
    "unit": "%",
    "frequency": "~8x/year",
    "source": "ECB"
  }
}

The top-level keys are the exact {indicator} slugs to use in announcements calls. Each entry also carries a coverage block with the latest available date and a freshness rating, so you can check a series is current before building a signal on it.

Step 4 — Forecasts and predictions: the expectation side of a release

A release only moves a currency relative to what was expected. The predictions endpoint joins forecasts to the release they target: official forecasts where a publisher issues them, plus FXMacroData's own pre-release forecast, each stamped with when it was generated. It requires a plan key.

curl -H "X-API-Key: YOUR_API_KEY" "https://api.fxmacrodata.com/v1/predictions/usd/inflation"

On 5 October 2026 the first upcoming row targeted October CPI (reference date 2026-10-31), scheduled for 13:30 UTC on 10 November 2026, with an FXMacroData forecast of 3.49% against the last actual of 3.4%. Store the forecast alongside the eventual val from Step 1 and you have a surprise series for event studies.

Step 5 — COT Positioning: speculative futures data

The Commitment of Traders endpoint delivers weekly CFTC positioning for currency futures. It splits open interest between non-commercial (speculative), commercial (hedger) and non-reportable participants, a widely tracked gauge of crowded positioning. Contracts covered include AUD, CAD, CHF, EUR, GBP, JPY, NZD and USD. USD is free; the others need a plan key.

# USD COT history: no key needed
curl "https://api.fxmacrodata.com/v1/cot/usd"

# EUR COT
curl -H "X-API-Key: YOUR_API_KEY" "https://api.fxmacrodata.com/v1/cot/eur"

The newest EUR row, trimmed (rows also carry z-scores for every column):

{
  "currency": "EUR",
  "instrument": "EURO FX - CHICAGO MERCANTILE EXCHANGE",
  "fx_overlay": { "pair": "EUR/USD" },
  "data": [
    {
      "date": "2026-09-29",
      "announcement_datetime": 1790969400,
      "open_interest": 853959,
      "noncommercial_long": 238183,
      "noncommercial_short": 301439,
      "noncommercial_net": -63256,
      "noncommercial_net_zscore": -1.5377,
      "commercial_net": 40577,
      "release_datetime": "2026-10-02T19:30:00+00:00"
    }
  ]
}

noncommercial_net (speculative longs minus shorts) is the most cited positioning gauge. In the report for 29 September 2026, speculators were net short 63,256 euro contracts, about 1.5 standard deviations below their average and close to the 72,447-contract short of 28 July. The CFTC published that report at 19:30 UTC on Friday 2 October, three days after the positions were measured, which is why announcement_datetime rather than date belongs in a backtest. The EUR COT dashboard charts the same series.

Step 6 — Commodities: energy and precious metals

The commodities endpoint returns daily and weekly series for oil_brent, oil_wti, natural_gas, natural_gas_storage, crude_oil_inventories, gold, silver and platinum. These are useful cross-asset inputs for commodity currencies and safe-haven flows. A plan key is always required.

# Brent crude daily prices
curl -H "X-API-Key: YOUR_API_KEY" "https://api.fxmacrodata.com/v1/commodities/oil_brent"

# Latest value of every commodity series in one call
curl -H "X-API-Key: YOUR_API_KEY" "https://api.fxmacrodata.com/v1/commodities/latest"

The newest Brent rows, trimmed:

{
  "currency": "COMM",
  "indicator": "oil_brent",
  "source": "U.S. Energy Information Administration (EIA)",
  "latest_available_date": "2026-09-29",
  "data": [
    { "date": "2026-09-29", "val": 113.96 },
    { "date": "2026-09-28", "val": 119.97 }
  ]
}

The shape matches the announcements endpoint, so the same parsing code works. The /v1/commodities/latest response adds the previous value and percentage change per series, which is handy for a cross-asset dashboard tile. See the commodities dashboard for the charted view.

Step 7 — FX Rates: daily spot series and reference rates

The forex endpoint returns daily rates for any pair across the 22 supported currencies, built from official central-bank reference rates. Use it to line up macro releases with the contemporaneous exchange rate. Pass base and quote as separate path segments, for example /forex/eur/usd for EUR/USD, and add technical overlays with the indicators parameter. A plan key is required.

# EUR/USD daily rates
curl -H "X-API-Key: YOUR_API_KEY" "https://api.fxmacrodata.com/v1/forex/eur/usd"

# GBP/USD with technical indicators overlaid
curl -H "X-API-Key: YOUR_API_KEY" "https://api.fxmacrodata.com/v1/forex/gbp/usd?indicators=sma_20,rsi_14"

The newest EUR/USD row, trimmed:

{
  "base": "EUR",
  "quote": "USD",
  "source": "Official central-bank reference rates",
  "data": [
    {
      "date": "2026-10-02",
      "val": 1.1224996047886688,
      "observation_datetime": 1790899200,
      "observation_datetime_precision": "date"
    }
  ]
}

Round val to four or five decimals for display (1.1225 here). When you need more than one daily print, /v1/fx/reference-rates/{base}/{quote} and /v1/fx/intraday-reference-rates/{base}/{quote} expose the individual official fixings, and the free /v1/fx/sources route lists which publishers feed them.

Step 8 — Curves and rate differentials: the rates channel

FX pairs usually trade on relative rates. The curves endpoint returns government-curve nodes, slopes or derived forward segments for a currency through its view parameter, and the rate-differentials endpoint aligns two currencies on matching dates and returns the spread in percentage points and basis points. Both need a plan key.

curl -H "X-API-Key: YOUR_API_KEY" "https://api.fxmacrodata.com/v1/curves/gbp?view=forwards"
curl -H "X-API-Key: YOUR_API_KEY" "https://api.fxmacrodata.com/v1/rate_differentials/eur/usd?measure=auto"

On 1 October 2026 the EUR/USD differential on risk-free rates (euro short-term rate against SOFR) was −142.8 basis points: 2.442% against 3.87%. The measure parameter also accepts gov_bond_2y, gov_bond_10y and policy_rate. For worked examples, see Introducing the Forward Curve and Pair Differential Endpoints.

Step 9 — Market sessions and risk sentiment

Two free context endpoints help with timing and regime. Market sessions returns the open/close state of the Sydney, Tokyo, London and New York sessions plus the overlap windows. Pass at with an ISO-8601 UTC timestamp to see the timetable for another moment. Risk sentiment returns a daily composite score and regime label.

curl "https://api.fxmacrodata.com/v1/market_sessions"
curl "https://api.fxmacrodata.com/v1/market_sessions?at=2026-10-05T13:00:00Z"
curl "https://api.fxmacrodata.com/v1/risk_sentiment"

One session and the main overlap from a market-sessions response, trimmed:

{
  "now_utc": "2026-10-05T22:22:26Z",
  "is_market_day": true,
  "sessions": [
    {
      "name": "Sydney",
      "currencies": ["AUD", "NZD"],
      "open_utc": "2026-10-05T21:00:00Z",
      "close_utc": "2026-10-06T06:00:00Z",
      "is_open": true,
      "seconds_to_close": 27453
    }
  ],
  "overlaps": [
    {
      "name": "London / New York",
      "priority": "high",
      "start_utc": "2026-10-05T12:00:00Z",
      "end_utc": "2026-10-05T16:00:00Z",
      "is_active": false,
      "duration_hours": 4.0
    }
  ]
}

The London and New York overlap is the highest-liquidity window of the day and is when US releases at 08:30 New York time land. Use is_market_day to skip automation at weekends. For risk sentiment, the 2 October 2026 reading was a score of 0.0636 with a neutral regime. The FX sessions dashboard shows the same timetable.

Step 10 — Central-bank press releases and factors

The press-releases endpoint returns recent central-bank statements with a summary, category and a rate-path tag, so you can watch the Federal Reserve or any other covered bank without scraping its website. The factors endpoint returns derived scores. The current factor is monetary_stance, which blends policy level, recent impulse and rate repricing into one score per currency.

curl "https://api.fxmacrodata.com/v1/press-releases/usd?limit=5"
curl "https://api.fxmacrodata.com/v1/factors/usd/monetary_stance"

On 1 September 2026, the latest observation, the USD monetary_stance score was 0.155, labelled neutral.

Step 11 — Real-time delivery: change polling and the SSE stream

Fetching at the scheduled time works, but a release can land seconds before or after its slot. Two endpoints tell you when new data has actually arrived. /v1/announcements/changes is a cursor-based poll: pass back the next_cursor from each response as since, and you only receive releases you have not seen. /v1/stream/events is a Server-Sent Events stream that pushes each release as it is captured.

# Poll recent USD release changes (free tier is delayed 15 minutes)
curl -H "X-API-Key: YOUR_API_KEY" "https://api.fxmacrodata.com/v1/announcements/changes?currencies=usd&payload=full"

# Listen for USD and EUR releases as they happen
curl -N -H "X-API-Key: YOUR_API_KEY" "https://api.fxmacrodata.com/v1/stream/events?currencies=usd,eur&payload=full"

Server processes should send the key in the header. A browser EventSource cannot set headers, so keep stream consumers on your server rather than putting a key in front-end code. Releases are typically delivered within seconds of official publication; the release-speed page publishes the measured timings.

Step 12 — End-to-end Python workflow

The first snippet sets up a small helper and uses the free routes: discover AUD indicators, then find the next scheduled US payrolls release.

import requests
from datetime import datetime, timezone

BASE = "https://api.fxmacrodata.com/v1"
HEADERS = {"X-API-Key": "YOUR_API_KEY"}


def get(path: str, **params) -> dict:
    resp = requests.get(f"{BASE}{path}", headers=HEADERS, params=params, timeout=15)
    resp.raise_for_status()
    return resp.json()


catalogue = get("/data_catalogue/aud")
print("AUD indicators:", sorted(catalogue)[:5])

events = get("/calendar/usd", indicator="non_farm_payrolls")["data"]
if events:
    ts = events[0]["announcement_datetime"]
    print("Next NFP:", datetime.fromtimestamp(ts, tz=timezone.utc).isoformat())

The second snippet pulls two plan-key series and checks whether the high-liquidity overlap is open before raising an alert. Rows are newest first, so index 0 is the latest print.

eur_cpi = get("/announcements/eur/inflation", limit=1)["data"][0]
aud_rate = get("/announcements/aud/policy_rate", limit=1)["data"][0]
print(f"EUR HICP {eur_cpi['date']}: {eur_cpi['val']}%")
print(f"AUD cash rate {aud_rate['date']}: {aud_rate['val']}%")

sessions = get("/market_sessions")
if not sessions["is_market_day"]:
    print("Market closed: skipping alert")
else:
    for overlap in sessions.get("overlaps", []):
        if overlap["is_active"] and overlap["priority"] == "high":
            print(f"High-liquidity window active: {overlap['name']}")

What you can build next

You now have a working example for each endpoint family. A few natural next steps:

• Build a surprise series. Store the pre-release forecast from the predictions endpoint next to each realised val and measure how far every print lands from expectations.
• Layer COT positioning over rate differentials. Combine the speculative net from the COT endpoint with the pair spread from the rate-differentials endpoint to see when positioning and carry disagree.
• Move AI workflows to MCP. The same data is available to Claude, ChatGPT and other assistants through the FXMacroData MCP server, which wraps these endpoints as tools.

The API reference embeds the full OpenAPI schema with every parameter. Check it before wiring a new integration.