Skip to content
Production API

FXMacroData API endpoints and reference

FXMacroData currently exposes 30 production API paths across 13 endpoint groups. Use the inventory below to choose the right family, then open the interactive OpenAPI reference for parameters, schemas, and response examples. The inventory and the Scalar reference are generated from the same production OpenAPI schema.

30 Production endpoint paths
13 Endpoint groups
OpenAPI 3.1 Production schema
Build in 4 calls

Start with one release, then add calendar, FX, and AI context.

These production examples cover the most common first workflow: inspect a USD macro release, plan the next event window, join FX context, and hand the same data to an agent or automation layer.

Choose a workflow Try USD inflation GraphQL API RapidAPI access Forecasts and consensus Point-in-time backtesting Free access Pagination
No-key USD Latest announcement row

Anonymous USD evaluation works for recent data and discovery before checkout.

GET https://api.fxmacrodata.com/v1/announcements/usd/inflation?limit=1
Calendar Upcoming release plan

Use release-calendar rows to plan reviews, alerts, and model update windows.

GET https://api.fxmacrodata.com/v1/calendar/usd
FX context Pair history around the event

Join macro records to FX history for event studies and dashboard checks.

GET https://api.fxmacrodata.com/v1/forex/eur/usd?start_date=2026-01-01
Protected Use your API key

Send your key in the X-API-Key header. Authorization: Bearer is also accepted.

GET https://api.fxmacrodata.com/v1/announcements/eur/policy_rate
X-API-Key: YOUR_API_KEY
Pagination

List endpoints return 20 rows unless you page.

History endpoints such as /v1/announcements/{currency}/{indicator}, /v1/forex/{base}/{quote}, /v1/cot/{currency}, and /v1/commodities/{indicator} return the 20 most recent rows by default. limit accepts up to 100. To collect a complete range, keep requesting with offset until pagination.has_more is false; each response's pagination object also carries next_offset and total_count. A few endpoints use different page sizes, listed on each operation in the reference below. See the Python paging loop.

Without a key, USD history is limited to the most recent 90 days, and other currencies need a key. See free access and authentication. The API is for server-side use and does not send CORS headers to browser origins.

Reference guides

Field definitions, delivery, clients and the rules the contract follows.

Response fields defines every field on an announcement row, its revisions and release timing. Low-latency reads covers the /v1/latest and /v1/recent routes for reading a release the moment it lands, and webhooks, SSE, WebSocket and release alerts deliver the event itself. SDKs and client libraries lists the published Python, JavaScript, R, Go, Julia and local MCP packages.

The deprecation policy states which changes arrive without notice and the six-month minimum before anything is removed; the changelog records every contract change and is also an Atom feed. Current service health is on the status page. Agents can read this documentation as Markdown: /documentation/llms.txt indexes every page, each served at its own path with a .md suffix, alongside the site-wide /llms.txt and /llms-full.txt.

Always free 12 paths

Health, data catalogue discovery, forecast coverage, market-session status, risk sentiment, and source-discovery routes require no API key.

Individual (USD: no-key 100/day) 5 paths

Announcements, the release calendar, factors, press releases, and COT use mixed access: USD is public without a key, up to 100 no-key requests per day, with announcements in the freemium window on a 15-minute release delay, while real-time delivery, non-USD access, deeper history, or higher-volume use requires an Individual API key.

Mixed access 2 paths

Release-event streams are public for USD events and require an Individual API key for non-USD event streams.

Individual API key required 11 paths

Forecast values (predictions, USD included), FX rates, reference-rate history, curves, rate differentials, and commodities require an Individual API key.

Health & Infrastructure

Health checks and low-friction API availability probes.

2 paths
GET
https://api.fxmacrodata.com/v1/health Ping the API Returns a simple OK status to verify the API is running.
Always free
GET
https://api.fxmacrodata.com/v1/ping Ping the API Use as a lightweight connectivity probe for scripts, status pages, and uptime checks.
Always free

Data Catalogue

Discovery and metadata for available indicators by currency.

1 path
GET
https://api.fxmacrodata.com/v1/data_catalogue/{currency} Get Currently Available Macroeconomic Indicators Use first in integrations to discover available indicator slugs, labels, units, and coverage for a currency.
Always free

Announcements

Macroeconomic announcement time series with official release timestamps.

3 paths
GET
https://api.fxmacrodata.com/v1/announcements/{currency}/latest Get latest values for all indicators in a currency Use to retrieve the latest stored value for every available indicator in one currency.
Always free
GET
https://api.fxmacrodata.com/v1/announcements/{currency}/{indicator} Get macroeconomic indicator data Use for historical macroeconomic time series, release timestamps, pagination, and source metadata for one indicator.
Individual (USD: no-key 100/day)
POST
https://api.fxmacrodata.com/v1/research/panel Build a panel of values known at each decision time Build a panel of values known at each decision time
Individual API key required

Predictions

Forecasts, consensus, central-bank projections, and FXMacroData predictions.

4 paths
GET
https://api.fxmacrodata.com/v1/predictions/coverage Which forecast publishers cover which currency (no API key) Free, key-free catalogue of forecast coverage across every served currency: which publishers we carry, what class of forecast each produces, and which currencies carry a genuine consensus source. Returns no forecast values -- those require a plan. Use ``/v1/predictions/coverage/{currency}`` for per-indicator detail.
Always free
GET
https://api.fxmacrodata.com/v1/predictions/coverage/{currency} Per-indicator forecast coverage for one currency (no API key) Free, key-free per-indicator catalogue for one currency: the publishers covering each indicator, the ``prediction_class`` each produces, whether any of them is a genuine consensus, and the verified archive depth where it has been confirmed. Returns no forecast values -- those require a plan.
Always free
GET
https://api.fxmacrodata.com/v1/predictions/{currency} Page official forecast vintages from one publisher Read one explicitly named source; bare currency listings stay disabled.
Always free
GET
https://api.fxmacrodata.com/v1/predictions/{currency}/{indicator} List predictions for one indicator of a currency Use for forecasts, consensus, official projections, and FXMacroData predictions joined to the announcement they target.
Individual API key required

Release Calendar

Upcoming macro and policy release schedules.

1 path
GET
https://api.fxmacrodata.com/v1/calendar/{currency} Get upcoming economic data release dates Use for upcoming and recent scheduled economic-release dates by currency.
Individual (USD: no-key 100/day)

Release Events & Streaming

Polling, SSE, and WebSocket delivery for newly ingested economic releases.

2 paths
GET
https://api.fxmacrodata.com/v1/announcements/changes Poll recent live announcement release changes Use to poll recently ingested release changes when a streaming connection is not appropriate.
Mixed access
GET
https://api.fxmacrodata.com/v1/stream/events Subscribe to real-time announcement events (SSE) Use an SSE connection for low-latency release-event delivery to browser or server clients.
Mixed access

Factors

Precomputed macro factor scores for model inputs and cross-currency comparison.

1 path
GET
https://api.fxmacrodata.com/v1/factors/{currency}/{factor} Get a precomputed FX factor for one currency Use for precomputed macro factor scores such as monetary stance, with optional stored components and source links.
Individual (USD: no-key 100/day)

FX Rates & Reference Rates

Daily, intraday and session views of official FX reference rates.

6 paths
GET
https://api.fxmacrodata.com/v1/forex/{base}/{quote} Get FX spot rates Use for daily FX spot history between two currencies, including derived crosses where supported.
Individual API key required
GET
https://api.fxmacrodata.com/v1/fx/intraday-reference-rates/{base}/{quote} Get subscriber intraday FX reference rates Use for intraday official reference-rate observations ordered by source observation time.
Individual API key required
GET
https://api.fxmacrodata.com/v1/fx/reference-rates/{base}/{quote} Get timestamped official FX reference rates Get timestamped official FX reference rates
Individual API key required
GET
https://api.fxmacrodata.com/v1/fx/session-rates/{base}/{quote} Get official FX session-close reference rates Get official FX session-close reference rates
Individual API key required
GET
https://api.fxmacrodata.com/v1/fx/source-universe List public FX reference-rate pair universe Use to inspect the public pair/source universe before requesting a reference-rate series.
Always free
GET
https://api.fxmacrodata.com/v1/fx/sources List public FX reference-rate sources Use to list the official FX reference-rate sources available through FXMacroData.
Always free

Rates, Curves & Differentials

Yield-curve views and pair rate differentials for rates-aware FX analysis.

3 paths
GET
https://api.fxmacrodata.com/v1/curves/{currency} Get curve analytics by currency Use for curve nodes, slope analytics, or derived forward segments by currency.
Individual API key required
GET
https://api.fxmacrodata.com/v1/financial_prices/{currency} Official financial prices and yield curves Use for official government bond, bill, auction, overnight-rate and yield-curve observations published by each currency's treasury or central bank, filtered by source, instrument, measure and date.
Individual API key required
GET
https://api.fxmacrodata.com/v1/rate_differentials/{base}/{quote} Get pair rate differentials Use to compare spot-rate or derived forward-rate spreads between two currencies.
Individual API key required

Market Context

FX market-session status and broad risk-on/risk-off context for timing and regime filters.

3 paths
GET
https://api.fxmacrodata.com/v1/market_sessions FX market session timetable Use to determine which major FX sessions are open or closed.
Always free
GET
https://api.fxmacrodata.com/v1/risk_sentiment Global risk-on / risk-off indicator Use as a broad risk-on/risk-off indicator alongside macro and FX data.
Always free
GET
https://api.fxmacrodata.com/v1/risk_sentiment/changes Recorded risk-sentiment changes Returns retained additions, score revisions and input-metadata changes in increasing change_sequence order. Pass pagination.next_after_sequence as after_sequence on the next page or poll. The sequence remains stable when changes share a recording timestamp. recorded_at is the FXMacroData recording clock; earlier untracked revisions and publisher publication times are unavailable. An undated legacy baseline is retained but is not emitted as a newly recorded change.
Always free

COT Positioning

CFTC Commitment of Traders futures positioning by currency.

1 path
GET
https://api.fxmacrodata.com/v1/cot/{currency} Get CFTC Commitment of Traders (COT) data Use for weekly CFTC Commitment of Traders futures positioning, including commercial and non-commercial long/short/net exposure, or the Traders in Financial Futures breakdown (dealer, asset manager, leveraged funds) via report=tff_futures.
Individual (USD: no-key 100/day)

Commodities

Precious metals, OPEC, and commodity-related endpoints.

2 paths
GET
https://api.fxmacrodata.com/v1/commodities/latest Get latest values for all commodity indicators Use to fetch the latest stored value for every available commodity indicator in one call.
Individual API key required
GET
https://api.fxmacrodata.com/v1/commodities/{indicator} Get commodity indicator data Use for commodity time series such as precious metals where macro workflows need cross-asset context.
Individual API key required

Official Press Releases

Central-bank press releases and policy communications from official sources.

1 path
GET
https://api.fxmacrodata.com/v1/press-releases/{currency} Recent central bank press releases Use for central-bank press releases and policy communications by currency.
Individual (USD: no-key 100/day)

Interactive OpenAPI reference

Search the same production schema, inspect parameters, and view response models below.