---

name: fxmacrodata description: "Query FXMacroData for official-source macro indicators, release calendars, central-bank policy rates, FX rates and CFTC positioning across 22 currencies." category: finance risk: safe source: self source_type: self date_added: "2026-10-04" author: fxmacrodata tags: [macroeconomics, forex, central-banks, economic-calendar, cot, rest-api] tools: [claude, cursor, gemini]

FXMacroData: Macro and FX Data

Overview

FXMacroData is a REST API for macroeconomic data taken from official publishers (statistics offices, central banks, the CFTC). It 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. Each series carries its publisher, source URL and the time the number was released, so answers can cite where a figure came from and when it became public.

This skill covers discovering indicator slugs, pulling release history, reading the release calendar, comparing policy rates between two currencies, and the access limits that apply without an API key.

When to Use

• Use when the user asks for an official macro figure for a country or currency: CPI, core inflation, GDP, unemployment, payrolls, retail sales, business and consumer confidence, trade balance, bond yields.
• Use when the user asks when the next CPI, payrolls, GDP or central-bank decision is due, or wants the release calendar for a week.
• Use when comparing central-bank policy rates or yield differentials between two currencies (for example USD vs JPY carry).
• Use when the user wants daily FX reference rates or CFTC Commitments of Traders positioning for a currency future.
• Do not use for intraday tick data, equities, crypto, or order execution. This is read-only reference data.

Access and Authentication

• Base URL: https://api.fxmacrodata.com/v1
• Authentication is optional. If the user has a key, read it from the FXMACRODATA_API_KEY environment variable and send it in the X-API-Key header. Never put the key in the URL or print it in output.
• Without a key:
  • USD indicators, the USD release calendar, the USD data catalogue and USD COT data work.
  • USD announcement data is delayed by 15 minutes. Each response includes a freemium_delay object with the cutoff time and withheld_count, the number of releases newer than the cutoff.
  • History is limited to the most recent 90 days. The freemium_window object shows the applied cutoff date, and requested_start_date in the response shows the start date actually used.
• Every other currency, /forex, /rate_differentials and /commodities need a key. Without one they return HTTP 401 with "code": "api_key_required". That means the data exists but needs a subscription; do not report it as missing.

# Keyless (USD only)
curl -s "https://api.fxmacrodata.com/v1/announcements/usd/policy_rate?limit=3"

# With a key, from the environment
curl -s -H "X-API-Key: $FXMACRODATA_API_KEY" \
  "https://api.fxmacrodata.com/v1/announcements/eur/policy_rate?limit=3"

Endpoints

Endpoint	Purpose	Keyless
GET /data_catalogue/{currency}	Every indicator slug for a currency, with name, unit, frequency, source and coverage	Yes (all currencies)
GET /announcements/{currency}/{indicator}	Release history for one indicator, most recent first	USD only
GET /announcements/{currency}/latest	Latest value of every indicator for a currency	USD only
GET /calendar/{currency}	Upcoming scheduled releases with UTC timestamps	USD only
GET /cot/{currency}	Weekly CFTC COT positioning (AUD, CAD, CHF, EUR, GBP, JPY, MXN, NZD, USD, XAU)	USD only
GET /forex/{base}/{quote}	Daily FX reference rates	No
GET /rate_differentials/{base}/{quote}	Aligned rate spread between two currencies in percentage points and basis points	No

Currency codes and indicator slugs are lowercase in paths (usd, policy_rate).

Common query parameters

Parameter	Endpoints	Notes
start_date, end_date	announcements, calendar, cot, forex, rate_differentials	YYYY-MM-DD, inclusive
limit, offset, page	announcements, cot, forex, rate_differentials	Rows are most recent first. Default limit is 20
timezone	calendar	IANA name such as Europe/London; adds an announcement_datetime_requested_timezone field
indicator	calendar	Filter the calendar to one slug
revisions	announcements	latest, first, final or all, where supported
measure	rate_differentials	auto, policy_rate, risk_free_rate, gov_bond_2y, gov_bond_10y

Response shape

Announcement responses carry metadata (source, source_url, source_series_name, seasonal_adjustment, pagination) and a data array. Each row has:

• date: the reference period the value belongs to.
• val: the value, plus previous_value and change_from_previous when the prior observation is in range.
• announcement_datetime: Unix seconds (UTC) when the figure was published; announcement_datetime_local gives the publisher's local time.
• revisions: earlier vintages of the same observation, where available.

How It Works

Step 1: Find the indicator slug

Slugs differ from common names. US CPI is inflation, not cpi, and payrolls is non_farm_payrolls. Check the catalogue before the first query for a currency:

curl -s "https://api.fxmacrodata.com/v1/data_catalogue/usd" | jq 'keys'
curl -s "https://api.fxmacrodata.com/v1/data_catalogue/usd" | jq '.inflation | {name, unit, frequency, source}'

An unknown slug returns HTTP 404 with a suggestion, for example Did you mean: ppi?.

Step 2: Pull the history

curl -s "https://api.fxmacrodata.com/v1/announcements/usd/unemployment?limit=6" \
  | jq '.data[] | {date, val, announcement_datetime}'

Report the reference period (date) and the publication time (announcement_datetime) separately. A March figure is usually released in April.

Step 3: Check freshness before calling a value "latest"

curl -s "https://api.fxmacrodata.com/v1/announcements/usd/non_farm_payrolls?limit=1" \
  | jq '{latest: .data[0].date, val: .data[0].val, delay: .freemium_delay}'

If freemium_delay.withheld_count is greater than 0, a newer release has been published but is not yet visible to keyless requests. Say so, and do not present the older value as current.

Step 4: Check the next release

curl -s "https://api.fxmacrodata.com/v1/calendar/usd?indicator=non_farm_payrolls&timezone=UTC" \
  | jq '.data[0] | {name, reference_period, announcement_datetime_utc, release_date_confirmed}'

Use announcement_datetime_utc and convert to the user's timezone only when presenting the answer.

Examples

Example 1: What did the Fed do at its last meeting?

curl -s "https://api.fxmacrodata.com/v1/announcements/usd/policy_rate?limit=2" \
  | jq '{name, source, rows: [.data[] | {date, val, previous_value, change_from_previous, source_url}]}'

policy_rate for USD is the upper bound of the federal funds target range; policy_rate_target_lower and policy_rate_midpoint are separate slugs. Cite source_url, which links the Federal Reserve statement for that decision.

Example 2: US release calendar for a given week

curl -s "https://api.fxmacrodata.com/v1/calendar/usd?start_date=2026-10-05&end_date=2026-10-09" \
  | jq '.data[] | {release, name, announcement_datetime_utc, event_importance}'

Example 3: Policy-rate differential for a carry question (key required)

curl -s -H "X-API-Key: $FXMACRODATA_API_KEY" \
  "https://api.fxmacrodata.com/v1/rate_differentials/usd/jpy?measure=policy_rate&limit=5"

Without a key you can still answer the USD side from /announcements/usd/policy_rate, and then state that the JPY leg needs an API key.

Example 4: CFTC positioning in US dollar index futures

curl -s "https://api.fxmacrodata.com/v1/cot/usd?limit=4" \
  | jq '.data[] | {date, noncommercial_net, noncommercial_net_zscore, open_interest}'

date is the Tuesday position date; the report is published later that week (announcement_datetime).

Example 5: Python helper

import os
import requests

BASE_URL = "https://api.fxmacrodata.com/v1"

def fxmd_get(path, **params):
    headers = {}
    key = os.environ.get("FXMACRODATA_API_KEY")
    if key:
        headers["X-API-Key"] = key
    resp = requests.get(f"{BASE_URL}{path}", params=params, headers=headers, timeout=30)
    if resp.status_code == 401:
        raise PermissionError(resp.json().get("detail", "API key required"))
    resp.raise_for_status()
    return resp.json()

cpi = fxmd_get("/announcements/usd/inflation", limit=12)
for row in cpi["data"]:
    print(row["date"], row["val"])

MCP Server

FXMacroData also runs a hosted MCP server at https://fxmacrodata.com/mcp (Streamable HTTP), listed in the MCP registry as io.github.fxmacrodata/fxmacrodata. If the client already has it connected, prefer its tools over raw HTTP calls. The same access rules apply.

Best Practices

• Do look up slugs in /data_catalogue/{currency} instead of guessing them.
• Do quote the publisher (source) and the release time with each figure.
• Do keep times in UTC internally and state the timezone when you present them.
• Do send the key only through the X-API-Key header from FXMACRODATA_API_KEY.
• Don't present keyless USD data as real time; it is 15 minutes behind.
• Don't treat a 401 api_key_required response as missing data.
• Don't compare series with different seasonal_adjustment or units without saying so.

Limitations

• Without a key, only USD data is returned, with a 15-minute release delay and 90 days of history. A request for older data is clipped to the last 90 days rather than rejected, so check requested_start_date and freemium_window.
• All timestamps are UTC (Unix seconds or ISO 8601 with offset). Calendar times are scheduled times and can move; check release_date_confirmed.
• FX rates are daily official reference rates, not live dealing quotes.
• COT data is weekly and covers only the contracts listed above.
• Indicator coverage differs by currency; a slug that exists for USD may not exist for another currency.
• This skill reads data only. It does not give investment advice, and figures should be checked against the publisher's own release for anything consequential.

Security & Safety Notes

• All calls are read-only HTTPS GET requests to api.fxmacrodata.com.
• The API key is a secret. Read it from the environment, never hard-code it, never pass it as a query parameter, and never echo it back to the user.

Common Pitfalls

• Problem: {"detail": "Unsupported currency (USD) or indicator (cpi)..."} Solution: Use the slug from the catalogue (inflation).
• Problem: A request with start_date=2020-01-01 returns only a few rows. Solution: Keyless history is limited to 90 days. Use a key for full history.
• Problem: non_farm_payrolls returns a value around 159 million. Solution: That slug is the employment level. The monthly change is the difference between consecutive rows.
• Problem: The latest row is older than a release you know has happened. Solution: Check freemium_delay.withheld_count; the release may be inside the 15-minute delay window.

Additional Resources

• FXMacroData