fxmacrodata – Other skill for AI agents

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 and USD COT data work. Catalogue discovery is described separately below; verify live access rules before concluding another currency requires a key.
• 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.
• D

… (full content is in the download package)