# How to Use All FXMacroData API Endpoints: A Complete Guide

Canonical: https://fxmacrodata.com/articles/how-to-use-all-fxmacrodata-api-endpoints
Author: FXMacroData
Published: 2026-03-30T08:55:00Z

A step-by-step guide to every FXMacroData API endpoint family, from macro announcements, release calendars and forecasts to COT, commodities, FX rates, curves, market sessions and real-time release delivery, with real sample responses.

**Quick answer:**every FXMacroData REST endpoint lives under`https://api.fxmacrodata.com/v1/`and takes your key in the`X-API-Key`header.[USD](/united-states) macro releases, calendars, the data catalogue, USD COT, market sessions, risk sentiment and press releases work without a key on the free tier. Other currencies and the FX, curve, commodity and forecast families need an Individual or Business plan key.

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](/articles/cot-report-guide-fx-traders) , 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.

### Prerequisites

- For USD-only exploration, nothing: the free tier serves USD data with no key, delayed 15 minutes after each release, for up to 100 requests a day.

- For the other 21 currencies and the protected families, an Individual (USD 50/month) or Business (USD 250/month) plan key. The Individual plan starts with a 14-day trial. See[plans and pricing](/subscribe) .

- `curl`for the command-line examples, or Python 3.9+ with the`requests`library.

- Basic familiarity with REST APIs and JSON responses.

## Endpoint map at a glance

The production API covers 22 currencies:[AUD](/australia) ,[BRL](/brazil) ,[CAD](/canada) ,[CHF](/switzerland) , CNH,[CNY](/china) ,[DKK](/denmark) ,[EUR](/eurozone) ,[GBP](/united-kingdom) ,[HUF](/hungary) ,[ILS](/israel) ,[JPY](/japan) ,[KRW](/south-korea) ,[MYR](/malaysia) ,[NGN](/nigeria) ,[NOK](/norway) , NZD, PEN, SEK, THB, TWD and USD. The table groups the paths in the public[API reference](/documentation/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.

Endpoint family Route Access Announcements /v1/announcements/{currency}/{indicator} USD free Latest announcements /v1/announcements/{currency}/latest USD free Release calendar /v1/calendar/{currency} USD free Data catalogue /v1/data_catalogue/{currency} Free Forecasts and predictions /v1/predictions/{currency}/{indicator} Plan key COT positioning /v1/cot/{currency} USD free Commodities /v1/commodities/{indicator} Plan key FX rates /v1/forex/{base}/{quote} Plan key FX reference and intraday rates /v1/fx/reference-rates/{base}/{quote} Plan key Curves and rate differentials /v1/curves/{currency}
/v1/rate_differentials/{base}/{quote} Plan key Market sessions /v1/market_sessions Free Risk sentiment /v1/risk_sentiment Free Central-bank press releases /v1/press-releases/{currency} USD free Factors /v1/factors/{currency}/{factor} USD free Release changes and SSE stream /v1/announcements/changes
/v1/stream/events USD free (delayed); live with a 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](/api-data-docs/usd/inflation) .

## 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](/articles/how-to-schedule-with-release-calendar) , or browse the[release calendar dashboard](/dashboard/release-calendar) .

## 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"
    }
  ]
}
```

### EUR speculative net positioning, July to September 2026

Weekly`noncommercial_net`from the EUR COT endpoint, by CFTC report date

Source: CFTC Commitments of Traders, served by FXMacroData. Fixed historical values.

`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](/dashboard/cot/eur) 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](/dashboard/commodities) 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](/dashboard/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](/articles/introducing-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](/dashboard/fx-sessions) 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](/dashboard/press-releases/usd) 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](/release-speed) 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 accomplished

- ✓ Fetched indicator series with exact release timestamps from the**Announcements**endpoint

- ✓ Read upcoming release times from the**Release Calendar**

- ✓ Discovered indicator slugs per currency with the**Data Catalogue**

- ✓ Joined forecasts to releases with**Predictions**

- ✓ Retrieved speculative futures positioning from**COT**

- ✓ Pulled energy and metals series from**Commodities**

- ✓ Aligned macro data with**FX rates**,**curves**and**rate differentials**

- ✓ Added timing and regime context from**Market Sessions**and**Risk Sentiment**

- ✓ Switched from scheduled pulls to**change polling**and the**SSE stream**

## 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](/documentation/mcp-server) , which wraps these endpoints as tools.

The[API reference](/documentation/reference) embeds the full OpenAPI schema with every parameter. Check it before wiring a new integration.

Source: FXMacroData
