FXMacroData
Macroeconomic and FX time-series data for AI agents: indicators, calendars, COT, forex, commodities.
Open source Repository Open in the app JSON README (API)
About
Macroeconomic and FX time-series data for AI agents: indicators, calendars, COT, forex, commodities.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- fxmacrodata
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 1.0.1
- Stars
- 9
- Forks
- 1
- Open pull requests
- 1
- Last push
- 2026-08-31T05:01:53Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 03:02:48
- Updated
- 2026-08-29 03:02:48
- Origin id
io.github.fxmacrodata/fxmacrodata
README
# FXMacroData Python SDK 🐍📊
The **FXMacroData Python SDK** provides a simple and efficient interface for fetching **macroeconomic indicators**, **forex prices**, **release calendars**, **COT positioning**, and **commodity prices** from [FXMacroData](https://fxmacrodata.com/?utm_source=github&utm_medium=readme&utm_campaign=python_sdk).
It includes both synchronous and asynchronous clients, and USD macro endpoints work without an API key.
---
## 🌟 Features
- Fetch:
- **Macroeconomic indicators** — policy rates, inflation, GDP, unemployment, bond yields, and more: 97 distinct indicators across 656 endpoints
- **FX spot rates** with optional technical indicators (SMA, RSI, MACD, Bollinger Bands)
- **Release calendars** — upcoming economic data release dates
- **Data catalogue** — discover available indicators per currency
- **COT data** — CFTC Commitment of Traders positioning
- **Commodity prices** — gold, silver, platinum
- Free access to **USD** macro data, covering the most recent 90 days. An API key lifts the window to full history.
- FX spot-rate history through `get_fx_price`.
- API key required for protected datasets, including non-USD indicators, FX spot-rate history, COT, and commodities.
- Full support for:
- **Synchronous client**
- **Asynchronous client**
- Lightweight: depends only on `requests` and `aiohttp`.
---
## 📦 Installation
Install from PyPI:
```bash
pip install fxmacrodata
```
Or install the latest version from GitHub:
```bash
pip install git+https://github.com/fxmacrodata/fxmacrodata.git
```
---
## 🔧 Usage
### Synchronous
```python
from fxmacrodata import Client
client = Client(api_key="YOUR_API_KEY")
# Fetch macroeconomic indicators
data = client.get_indicator(
"aud", "policy_rate",
start_date="2023-01-01",
end_date="2023-11-01"
)
print(data)
# Forex price endpoint
fx = client.get_fx_price("usd", "gbp", start_date="2025-01-01")
print(fx)
# Forex with technical indicators
fx = client.get_fx_price("eur", "usd", indicators="sma_20,rsi_14,macd")
print(fx)
# Release calendar
calendar = client.get_calendar("usd")
print(calendar)
# Data catalogue — discover available indicators
catalogue = client.get_data_catalogue("usd")
print(catalogue)
# COT positioning data
cot = client.get_cot("eur", start_date="2025-01-01")
print(cot)
# Commodity prices
gold = client.get_commodities("gold", start_date="2026-01-01")
print(gold)
```
---
### Asynchronous
```python
import asyncio
from fxmacrodata import AsyncClient
async def main():
async with AsyncClient(api_key="YOUR_API_KEY") as client:
# Fetch macroeconomic indicators
data = await client.get_indicator("eur", "inflation")
print(data)
# Forex price endpoint
fx = await client.get_fx_price("usd", "jpy")
print(fx)
# Release calendar
calendar = await client.get_calendar("usd")
print(calendar)
# Data catalogue
catalogue = await client.get_data_catalogue("usd")
print(catalogue)
# COT positioning
cot = await client.get_cot("jpy")
print(cot)
# Commodity prices
gold = await client.get_commodities("gold")
print(gold)
asyncio.run(main())
```
---
## OpenBB Integration
FXMacroData supports all practical OpenBB integration paths from this package:
- OpenBB Python: installable provider/router extension for `obb.fxmacrodata.*`.
- OpenBB REST API: `/api/v1/fxmacrodata/*` routes through `openbb-api`.
- OpenBB Workspace, generated: widgets generated by `openbb-api` from inline metadata.
- OpenBB Workspace, custom: standalone backend serving `widgets.json`, `apps.json`, and data endpoints.
- OpenBB MCP: tools exposed through `openbb-mcp`.
- OpenBB CLI: commands available after `openbb-build`.
OpenBB packages require Python 3.10+. Install the OpenBB Python extra:
```bash
pip install "fxmacrodata[openbb]"
openbb-build
```
Then use FXMacroData from the OpenBB Python interface:
```python
from openbb import obb
obb.user.credentials.fxmacrodata_api_key = "YOUR_API_KEY"
catalogue = obb.fxmacrodata.data_catalogue(
currency="USD",
provider="fxmacrodata",
).to_df()
inflation = obb.fxmacrodata.macro_indicators(
currency="USD",
indicator="inflation",
start_date="2020-01-01",
provider="fxmacrodata",
).to_df()
eurusd = obb.fxmacrodata.fx_historical(
base="EUR",
quote="USD",
start_date="2024-01-01",
provider="fxmacrodata",
).to_df()
```
Run the OpenBB REST API and generated Workspace backend:
```bash
pip install "fxmacrodata[openbb-api]"
openbb-build
fxmacrodata-openbb-api --host 127.0.0.1 --port 6900
```
Workspace can be connected to `http://127.0.0.1:6900`. The generated
`/widgets.json` uses FXMacroData's inline OpenBB widget metadata.
Run the OpenBB Workspace custom backend:
```bash
pip install "fxmacrodata[workspace]"
fxmacrodata-openbb-backend
```
Default backend URL:
```text
http://127.0.0.1:7779
```
Workspace exposes `/widgets.json`, `/apps.json`, `/catalogue`,
`/release_calendar`, `/macro_indicator`, `/forex`, `/cot`, and `/commodity`.
Swagger/OpenAPI docs are disabled by default for this backend. For local
debugging only, set `FXMACRODATA_OPENBB_ENABLE_DOCS=1` before starting it.
Run OpenBB MCP:
```bash
pip install "fxmacrodata[mcp]"
openbb-build
fxmacrodata-openbb-mcp --default-categories fxmacrodata --host 127.0.0.1 --port 8001
```
Run OpenBB CLI:
```bash
pip install "fxmacrodata[openbb-cli]"
openbb-build
openbb
```
See `docs/openbb-integration.md` for the full integration matrix and the
separate upstream OpenBB repository contribution path.
---
## 📘 API Overview
### `get_indicator(currency, indicator, start_date=None, end_date=None)`
Fetches macroeconomic indicator time series data.
- `currency`: `"usd"`, `"aud"`, `"eur"`, `"gbp"`, `"cad"`, `"nok"`, `"nzd"`, `"jpy"`, `"brl"`, `"cny"`, `"dkk"`, `"pln"`, `"sek"`, `"sgd"`, etc.
- `indicator`: `"policy_rate"`, `"inflation"`, `"gdp"`, `"unemployment"`, `"trade_balance"`, `"current_account_balance"`, `"gov_bond_10y"`, etc.
- **API key required for non-USD.**
### `get_fx_price(base, quote, start_date=None, end_date=None, indicators=None)`
Fetches daily FX spot rates between two currencies.
- `indicators`: Optional comma-separated technical indicators — `"sma_20"`, `"sma_50"`, `"sma_200"`, `"rsi_14"`, `"macd"`, `"ema_12"`, `"ema_26"`, `"bollinger_bands"`, or `"all"`.
- **API key required.**
### `get_calendar(currency, indicator=None)`
Fetches upcoming economic data release dates for a currency.
- `indicator`: Optional filter to a specific indicator slug.
- Returns `announcement_datetime` (Unix timestamp) and `release` (indicator slug).
### `get_data_catalogue(currency, include_capabilities=False, include_coverage=False, indicator=None)`
Discovers available macroeconomic indicators for a given currency.
- Returns a dict keyed by indicator slug with `name`, `unit`, `frequency`, and `has_official_forecast`.
- **API key required for non-USD.**
### `get_cot(currency, start_date=None, end_date=None)`
Fetches CFTC Commitment of Traders (COT) positioning data.
- Supported currencies: `AUD`, `CAD`, `CHF`, `EUR`, `GBP`, `JPY`, `NZD`, `USD`.
- **API key required for non-USD.**
### `get_commodities(indicator, start_date=None, end_date=None)`
Fetches commodity price time series.
- `indicator`: `"gold"`, `"silver"`, or `"platinum"`.
- **API key required.**
---
## 💹 Supported Currencies & Indicators
**18 currencies supported:** AUD, BRL, CAD, CHF, CNH, CNY, DKK, EUR, GBP, ILS, JPY, NGN, NOK, NZD, PEN, SEK, THB, USD.
The table below shows a sample of indicator coverage across four major currencies. Use `get_data_catalogue()` to discover the full list for any currency.
| Category | Metric | USD | EUR | AUD | GBP |
|---------|--------|-----|-----|-----|-----|
| **Economy** | GDP Growth | ✓ | ✓ | ✓ | ✓ |
| | Inflation Rate | ✓ | ✓ | ✓ | ✓ |
| | Trade Balance | ✓ | ✓ | ✓ | ✓ |
| | Current Account Balance | ✓ | ✓ | ✓ | ✓ |
| | Retail Sales | ✓ | ✓ | ✓ | ✓ |
| | Industrial Production | ✓ | — | — | — |
| **Labor Market** | Unemployment Rate | ✓ | ✓ | ✓ | ✓ |
| | Employment Level | ✓ | ✓ | ✓ | ✓ |
| | Full-Time Employment | ✓ | ✓ | ✓ | — |
| | Part-Time Employment | ✓ | ✓ | ✓ | ✓ |
| | Participation Rate | ✓ | ✓ | ✓ | ✓ |
| | Non-Farm Payrolls | ✓ | — | — | — |
| **Monetary Policy** | Policy Rate | ✓ | ✓ | ✓ | ✓ |
| | Risk-Free Rate | ✓ | ✓ | ✓ | ✓ |
| | Central Bank Assets | ✓ | — | ✓ | — |
| **Government Bond Yields** | 2-Year Govt Bond | ✓ | ✓ | ✓ | ✓ |
| | 5-Year Govt Bond | ✓ | ✓ | ✓ | ✓ |
| | 10-Year Govt Bond | ✓ | ✓ | ✓ | ✓ |
| | Inflation-Linked Bond | ✓ | ✓ | ✓ | ✓ |
---
## 📄 License
MIT License © FXMacroData
---
## 🌐 Links
- Website: https://fxmacrodata.com
- API Docs: https://fxmacrodata.com/docs
- GitHub: https://github.com/fxmacrodata/fxmacrodata
- PyPI: https://pypi.org/project/fxmacrodata/
- Readthedocs: https://fxmacrodata.readthedocs.io/en/latest/
- Zenodo: https://zenodo.org/records/18280968