FXMacroData: Macro and FX Data

FXMacroData is a REST API for macroeconomic data taken from official publishers: statistics offices, central banks and 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 an answer can cite where a figure came from and when it became public.

This skill teaches an assistant to discover indicator slugs, pull release history, read the release calendar, compare policy rates between two currencies, and handle the access limits that apply without an API key. It reads data only and does not give investment advice.

Use it when someone 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 or bond yields. Use it when the question is when the next CPI, payrolls, GDP or central-bank decision is due, or when a week's release calendar is needed. It also fits comparisons of central-bank policy rates or yield differentials, such as USD against JPY for a carry question, plus daily FX reference rates and weekly CFTC Commitments of Traders positioning.

Do not use it for intraday tick data, equities, crypto or order execution. This is read-only reference data, and FX rates are daily official reference rates, not live dealing quotes.

Requests are HTTPS GET calls to the base URL https://api.fxmacrodata.com/v1. Currency codes and indicator slugs are lowercase in paths, for example usd and policy_rate. The main routes are the data catalogue per currency, announcements for an indicator's release history (most recent first), the latest value of every indicator, the upcoming release calendar with UTC timestamps, weekly COT positioning, daily FX rates and rate differentials between two currencies. Common parameters include start_date, end_date, limit, offset, timezone for the calendar, revisions for earlier vintages and measure for rate differentials (policy rate, risk-free rate, 2-year or 10-year government bond).

Announcement responses carry metadata such as source, source_url, source_series_name and seasonal_adjustment, plus a data array. Each row has the reference period in date, the value in val, previous_value and change_from_previous when available, and announcement_datetime in Unix seconds UTC. The skill reports the reference period and the publication time separately, since a March figure is usually released in April.

A typical first call looks up the slugs for a currency:

curl -s "https://api.fxmacrodata.com/v1/data_catalogue/usd" | jq 'keys'

Slugs differ from common names. US CPI is inflation, not cpi, and an unknown slug returns HTTP 404 with a suggestion. The non_farm_payrolls slug is the employment level, so the monthly change is the difference between consecutive rows.

Authentication is optional. A key is read from the FXMACRODATA_API_KEY environment variable and sent in the X-API-Key header, never in the URL and never printed. Without a key, USD indicators, the USD release calendar, the USD data catalogue and USD COT data work. USD announcements are delayed by 15 minutes, and a freemium_delay object shows the cutoff and withheld_count, the number of newer releases not yet visible. History is limited to the most recent 90 days, and older requests are clipped rather than rejected, so requested_start_date and freemium_window show what was applied.

Every other currency, plus forex, rate differentials and commodities, needs a key. Without one the API returns HTTP 401 with api_key_required, which means the data exists but needs a subscription, not that it is missing. For a USD against JPY carry question without a key, the USD side can be answered and the JPY leg flagged as needing a key.

FXMacroData also runs a hosted MCP server at https://fxmacrodata.com/mcp, listed in the MCP registry as io.github.fxmacrodata/fxmacrodata. If a client already has it connected, its tools are preferred over raw HTTP calls, and the same access rules apply. The skill is written for Claude, Cursor and Gemini style clients and uses curl with jq, with a short Python requests helper as an alternative.

It suits analysts and builders who need official macro figures with citations: answering what a central bank did at its last meeting, checking whether a release has landed, or preparing a weekly calendar. It is also for anyone comparing central-bank policy rates across currencies who must keep the publisher, source URL and publication time with each number. Figures should be checked against the publisher's own release for anything consequential.