Building AI agents, atomically
FXMacroData Tool
Overview
Queries the FXMacroData API for official-source macroeconomic data: release history with publication timestamps where available (CPI, GDP, unemployment, payrolls, policy rates, bond yields and more), the latest value of every indicator for a currency, upcoming release dates, the indicator catalogue, FX spot history, CFTC Commitments of Traders positioning, and commodity prices.
USD releases, the USD release calendar and the indicator catalogue work without an API key. Other currencies, FX rates, COT and commodities need a key from fxmacrodata.com/subscribe.
Prerequisites and Dependencies
- Python 3.12 or later
atomic-agentspydanticrequests- Optional: an FXMacroData API key
Installation
- Use the Atomic Assembler CLI: run
atomicand pickfxmacrodata. - Or copy the
tool/folder directly into your project.
Configuration
api_key(secret str): FXMacroData API key, hidden from the config repr, sent in theX-API-Keyheader. Falls back to theFXMACRODATA_API_KEYenvironment variable; surrounding whitespace is ignored. Leave empty for keyless USD access. The key never appears inurl,erroror any other output field, even if the API echoes it.base_url(str): API base URL (defaulthttps://api.fxmacrodata.com/v1). Must be anhttps://URL with a host and a valid port when specified, checked when the config is created; redirects are not followed, so the key is only ever sent to this origin.timeout(float): HTTP timeout in seconds (default 30).
Input & Output Structure
Input Schema
endpoint(str): one ofannouncements: release history for one indicator (currencyandindicatorrequired)latest: the most recent value of every indicator for a currencycalendar: upcoming release dates for a currency, optionally filtered byindicatorcatalogue: indicator slugs, units and coverage available for a currencyforex: FX spot history (currencyis the base,quoterequired)cot: CFTC positioning for a currencycommodities: price history for a commodity (indicator, e.g.gold)
currency(str, optional): three-letter code such asusd,eur,jpy.indicator(str, optional): indicator slug such asinflation,policy_rate,gdp.quote(str, optional): quote currency forforex.start_date,end_date(str, optional): real dates asYYYY-MM-DD;start_datemust not be afterend_date.limit(int, optional): rows per page, 1-100. History endpoints return 20 rows by default.offset(int, optional): row offset for paging.
Output Schema
endpoint(str): the endpoint that was called.url(str): the request URL (the key is never included).data: the rows returned by the API, with the API's own field names. Announcement rows includedate(reference period),val, and anannouncement_datetimetimestamp field (Unix seconds when available; the timestamp can be unavailable). Forcataloguethis is a mapping of indicator slug to metadata.pagination(dict, optional):has_more,next_offsetandtotal_countfor paged endpoints.metadata(dict): the remaining top-level response fields, such as source, provenance and data quality.error(str, optional): set instead of raising when the input is invalid, the request fails, or the response is not the documented shape, so an agent can read the reason (for example a missing API key for a non-USD currency) and adjust.
Response structure is validated before credential redaction. Names that collide after redaction receive unique, redacted suffixes; all values are retained.
Usage
from tool.fxmacrodata import FXMacroDataTool, FXMacroDataToolInputSchema
tool = FXMacroDataTool() # reads FXMACRODATA_API_KEY if set
cpi = tool.run(FXMacroDataToolInputSchema(endpoint="announcements", currency="usd", indicator="inflation", limit=3))
for row in cpi.data:
print(row["date"], row["val"], row["announcement_datetime"])
upcoming = tool.run(FXMacroDataToolInputSchema(endpoint="calendar", currency="usd"))
for row in upcoming.data[:5]:
print(row["announcement_datetime_utc"], row["name"])
To page through a long history, repeat the call with offset=output.pagination["next_offset"] until has_more is false.
The full list of endpoints and response fields is in the API reference.
Contributing
PRs welcome. See the main repo CONTRIBUTING.md.
License
Same as the main Atomic Agents project.