{
  "markdown": "# FXMacroData Python SDK 🐍📊\n\n![PyPI Version](https://img.shields.io/pypi/v/fxmacrodata?color=blue&logo=python&style=flat-square)\n![Python Versions](https://img.shields.io/pypi/pyversions/fxmacrodata?style=flat-square)\n![License](https://img.shields.io/github/license/fxmacrodata/fxmacrodata?style=flat-square)\n![Build](https://img.shields.io/github/actions/workflow/status/fxmacrodata/fxmacrodata/ci-cd.yml?style=flat-square&logo=github)\n\nThe **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).  \n\nIt includes both synchronous and asynchronous clients, and USD macro endpoints work without an API key.\n\n---\n\n## 🌟 Features\n\n- Fetch:\n  - **Macroeconomic indicators** — policy rates, inflation, GDP, unemployment, bond yields, and more: 97 distinct indicators across 656 endpoints\n  - **FX spot rates** with optional technical indicators (SMA, RSI, MACD, Bollinger Bands)\n  - **Release calendars** — upcoming economic data release dates\n  - **Data catalogue** — discover available indicators per currency\n  - **COT data** — CFTC Commitment of Traders positioning\n  - **Commodity prices** — gold, silver, platinum\n- Free access to **USD** macro data, covering the most recent 90 days. An API key lifts the window to full history.\n- FX spot-rate history through `get_fx_price`.\n- API key required for protected datasets, including non-USD indicators, FX spot-rate history, COT, and commodities.\n- Full support for:\n  - **Synchronous client**\n  - **Asynchronous client**\n- Lightweight: depends only on `requests` and `aiohttp`.\n\n---\n\n## 📦 Installation\n\nInstall from PyPI:\n\n```bash\npip install fxmacrodata\n```\n\nOr install the latest version from GitHub:\n\n```bash\npip install git+https://github.com/fxmacrodata/fxmacrodata.git\n```\n\n---\n\n## 🔧 Usage\n\n### Synchronous\n\n```python\nfrom fxmacrodata import Client\n\nclient = Client(api_key=\"YOUR_API_KEY\")\n\n# Fetch macroeconomic indicators\ndata = client.get_indicator(\n    \"aud\", \"policy_rate\",\n    start_date=\"2023-01-01\",\n    end_date=\"2023-11-01\"\n)\nprint(data)\n\n# Forex price endpoint\nfx = client.get_fx_price(\"usd\", \"gbp\", start_date=\"2025-01-01\")\nprint(fx)\n\n# Forex with technical indicators\nfx = client.get_fx_price(\"eur\", \"usd\", indicators=\"sma_20,rsi_14,macd\")\nprint(fx)\n\n# Release calendar\ncalendar = client.get_calendar(\"usd\")\nprint(calendar)\n\n# Data catalogue — discover available indicators\ncatalogue = client.get_data_catalogue(\"usd\")\nprint(catalogue)\n\n# COT positioning data\ncot = client.get_cot(\"eur\", start_date=\"2025-01-01\")\nprint(cot)\n\n# Commodity prices\ngold = client.get_commodities(\"gold\", start_date=\"2026-01-01\")\nprint(gold)\n```\n\n---\n\n### Asynchronous\n\n```python\nimport asyncio\nfrom fxmacrodata import AsyncClient\n\nasync def main():\n    async with AsyncClient(api_key=\"YOUR_API_KEY\") as client:\n        # Fetch macroeconomic indicators\n        data = await client.get_indicator(\"eur\", \"inflation\")\n        print(data)\n\n        # Forex price endpoint\n        fx = await client.get_fx_price(\"usd\", \"jpy\")\n        print(fx)\n\n        # Release calendar\n        calendar = await client.get_calendar(\"usd\")\n        print(calendar)\n\n        # Data catalogue\n        catalogue = await client.get_data_catalogue(\"usd\")\n        print(catalogue)\n\n        # COT positioning\n        cot = await client.get_cot(\"jpy\")\n        print(cot)\n\n        # Commodity prices\n        gold = await client.get_commodities(\"gold\")\n        print(gold)\n\nasyncio.run(main())\n```\n\n---\n\n## OpenBB Integration\n\nFXMacroData supports all practical OpenBB integration paths from this package:\n\n- OpenBB Python: installable provider/router extension for `obb.fxmacrodata.*`.\n- OpenBB REST API: `/api/v1/fxmacrodata/*` routes through `openbb-api`.\n- OpenBB Workspace, generated: widgets generated by `openbb-api` from inline metadata.\n- OpenBB Workspace, custom: standalone backend serving `widgets.json`, `apps.json`, and data endpoints.\n- OpenBB MCP: tools exposed through `openbb-mcp`.\n- OpenBB CLI: commands available after `openbb-build`.\n\nOpenBB packages require Python 3.10+. Install the OpenBB Python extra:\n\n```bash\npip install \"fxmacrodata[openbb]\"\nopenbb-build\n```\n\nThen use FXMacroData from the OpenBB Python interface:\n\n```python\nfrom openbb import obb\n\nobb.user.credentials.fxmacrodata_api_key = \"YOUR_API_KEY\"\n\ncatalogue = obb.fxmacrodata.data_catalogue(\n    currency=\"USD\",\n    provider=\"fxmacrodata\",\n).to_df()\n\ninflation = obb.fxmacrodata.macro_indicators(\n    currency=\"USD\",\n    indicator=\"inflation\",\n    start_date=\"2020-01-01\",\n    provider=\"fxmacrodata\",\n).to_df()\n\neurusd = obb.fxmacrodata.fx_historical(\n    base=\"EUR\",\n    quote=\"USD\",\n    start_date=\"2024-01-01\",\n    provider=\"fxmacrodata\",\n).to_df()\n```\n\nRun the OpenBB REST API and generated Workspace backend:\n\n```bash\npip install \"fxmacrodata[openbb-api]\"\nopenbb-build\nfxmacrodata-openbb-api --host 127.0.0.1 --port 6900\n```\n\nWorkspace can be connected to `http://127.0.0.1:6900`. The generated\n`/widgets.json` uses FXMacroData's inline OpenBB widget metadata.\n\nRun the OpenBB Workspace custom backend:\n\n```bash\npip install \"fxmacrodata[workspace]\"\nfxmacrodata-openbb-backend\n```\n\nDefault backend URL:\n\n```text\nhttp://127.0.0.1:7779\n```\n\nWorkspace exposes `/widgets.json`, `/apps.json`, `/catalogue`,\n`/release_calendar`, `/macro_indicator`, `/forex`, `/cot`, and `/commodity`.\nSwagger/OpenAPI docs are disabled by default for this backend. For local\ndebugging only, set `FXMACRODATA_OPENBB_ENABLE_DOCS=1` before starting it.\n\nRun OpenBB MCP:\n\n```bash\npip install \"fxmacrodata[mcp]\"\nopenbb-build\nfxmacrodata-openbb-mcp --default-categories fxmacrodata --host 127.0.0.1 --port 8001\n```\n\nRun OpenBB CLI:\n\n```bash\npip install \"fxmacrodata[openbb-cli]\"\nopenbb-build\nopenbb\n```\n\nSee `docs/openbb-integration.md` for the full integration matrix and the\nseparate upstream OpenBB repository contribution path.\n\n---\n\n## 📘 API Overview\n\n### `get_indicator(currency, indicator, start_date=None, end_date=None)`\nFetches macroeconomic indicator time series data.\n\n- `currency`: `\"usd\"`, `\"aud\"`, `\"eur\"`, `\"gbp\"`, `\"cad\"`, `\"nok\"`, `\"nzd\"`, `\"jpy\"`, `\"brl\"`, `\"cny\"`, `\"dkk\"`, `\"pln\"`, `\"sek\"`, `\"sgd\"`, etc.\n- `indicator`: `\"policy_rate\"`, `\"inflation\"`, `\"gdp\"`, `\"unemployment\"`, `\"trade_balance\"`, `\"current_account_balance\"`, `\"gov_bond_10y\"`, etc.\n- **API key required for non-USD.**\n\n### `get_fx_price(base, quote, start_date=None, end_date=None, indicators=None)`\nFetches daily FX spot rates between two currencies.\n\n- `indicators`: Optional comma-separated technical indicators — `\"sma_20\"`, `\"sma_50\"`, `\"sma_200\"`, `\"rsi_14\"`, `\"macd\"`, `\"ema_12\"`, `\"ema_26\"`, `\"bollinger_bands\"`, or `\"all\"`.\n- **API key required.**\n\n### `get_calendar(currency, indicator=None)`\nFetches upcoming economic data release dates for a currency.\n\n- `indicator`: Optional filter to a specific indicator slug.\n- Returns `announcement_datetime` (Unix timestamp) and `release` (indicator slug).\n\n### `get_data_catalogue(currency, include_capabilities=False, include_coverage=False, indicator=None)`\nDiscovers available macroeconomic indicators for a given currency.\n\n- Returns a dict keyed by indicator slug with `name`, `unit`, `frequency`, and `has_official_forecast`.\n- **API key required for non-USD.**\n\n### `get_cot(currency, start_date=None, end_date=None)`\nFetches CFTC Commitment of Traders (COT) positioning data.\n\n- Supported currencies: `AUD`, `CAD`, `CHF`, `EUR`, `GBP`, `JPY`, `NZD`, `USD`.\n- **API key required for non-USD.**\n\n### `get_commodities(indicator, start_date=None, end_date=None)`\nFetches commodity price time series.\n\n- `indicator`: `\"gold\"`, `\"silver\"`, or `\"platinum\"`.\n- **API key required.**\n\n---\n\n## 💹 Supported Currencies & Indicators\n\n**18 currencies supported:** AUD, BRL, CAD, CHF, CNH, CNY, DKK, EUR, GBP, ILS, JPY, NGN, NOK, NZD, PEN, SEK, THB, USD.\n\nThe table below shows a sample of indicator coverage across four major currencies. Use `get_data_catalogue()` to discover the full list for any currency.\n\n| Category | Metric | USD | EUR | AUD | GBP |\n|---------|--------|-----|-----|-----|-----|\n| **Economy** | GDP Growth | ✓ | ✓ | ✓ | ✓ |\n|  | Inflation Rate | ✓ | ✓ | ✓ | ✓ |\n|  | Trade Balance | ✓ | ✓ | ✓ | ✓ |\n|  | Current Account Balance | ✓ | ✓ | ✓ | ✓ |\n|  | Retail Sales | ✓ | ✓ | ✓ | ✓ |\n|  | Industrial Production | ✓ | — | — | — |\n| **Labor Market** | Unemployment Rate | ✓ | ✓ | ✓ | ✓ |\n|  | Employment Level | ✓ | ✓ | ✓ | ✓ |\n|  | Full-Time Employment | ✓ | ✓ | ✓ | — |\n|  | Part-Time Employment | ✓ | ✓ | ✓ | ✓ |\n|  | Participation Rate | ✓ | ✓ | ✓ | ✓ |\n|  | Non-Farm Payrolls | ✓ | — | — | — |\n| **Monetary Policy** | Policy Rate | ✓ | ✓ | ✓ | ✓ |\n|  | Risk-Free Rate | ✓ | ✓ | ✓ | ✓ |\n|  | Central Bank Assets | ✓ | — | ✓ | — |\n| **Government Bond Yields** | 2-Year Govt Bond | ✓ | ✓ | ✓ | ✓ |\n|  | 5-Year Govt Bond | ✓ | ✓ | ✓ | ✓ |\n|  | 10-Year Govt Bond | ✓ | ✓ | ✓ | ✓ |\n|  | Inflation-Linked Bond | ✓ | ✓ | ✓ | ✓ |\n\n---\n\n## 📄 License\n\nMIT License © FXMacroData\n\n---\n\n## 🌐 Links\n\n- Website: https://fxmacrodata.com\n- API Docs: https://fxmacrodata.com/docs\n- GitHub: https://github.com/fxmacrodata/fxmacrodata\n- PyPI: https://pypi.org/project/fxmacrodata/\n- Readthedocs: https://fxmacrodata.readthedocs.io/en/latest/\n- Zenodo: https://zenodo.org/records/18280968\n",
  "bytes": 9459,
  "sha": "a739dbc82f94d32743713b252f0f00e345a440753f4f40c1622b268983ee7805",
  "repo_slug": "fxmacrodata/fxmacrodata",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_fxmacrodata_fxmacrodata_d8f6b455/readme"
}