io.github.fxmacrodata/fxmacrodata

Official34 tools

by fxmacrodata · Python

FXMacroData

Macroeconomic and FX time-series data for AI agents: indicators, calendars, COT, forex, commodities.

Supplies macroeconomic and forex time-series data including indicators and commodities pricing.

Topics

dataforexmacroeconomicstrading

Captured live from the server via tools/list.

ping

Quick health check that confirms the FXMacroData API and MCP server are reachable. Use this only if other tools fail unexpectedly — it is not needed before normal calls.

No parameters.

mcp_capabilities

Explain what the FXMacroData MCP server can do, which tools render MCP Apps, which tools return plain rows, what is public versus subscriber-only, and how to choose tools across ChatGPT, Claude, Cursor, Codex, and plain MCP clients. Use this when a user asks what is available, why visuals are not showing, or how to get the same result in a different interface.

No parameters.

mcp_auth_guide

Explain which authentication mode to use for FXMacroData MCP across major clients and platforms. Use this when the user asks whether to use OAuth, an API key, a bearer token, ChatGPT/OpenAI Apps, Claude/Anthropic, Microsoft/VS Code/Copilot-style clients, Cursor, Codex, local scripts, or CI.

No parameters.

subscribe_for_mcp_access

Open subscription options when a user needs to unlock MCP app visuals, charts, and advanced analytical tools. Returns a direct checkout path.

No parameters.

data_catalogue

List every macroeconomic indicator FXMacroData publishes for a currency, with units, frequency, and coverage/freshness metadata. ALWAYS call this first when the user asks about a country's macro data — it returns the exact `indicator` slug strings to pass to indicator_query, release_calendar, and indicator_visual_artifact. Check `coverage` before calling indicator_query; stale, partial, or unavailable rows are not suitable for real-time carry or inflation analysis. Supported currencies (lowercase 3-letter codes): AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD.

Parameters (4)

currencystringrequired
3-letter ISO currency code (case-insensitive). Supported: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD.
include_coverageboolean
Include coverage/freshness rows with latest_available_date, coverage_quality, has_recent_data, and recent_observation_count. Leave true when deciding whether an indicator is usable before calling indicator_query.
include_capabilitiesboolean
Include machine-readable indicator capabilities when the API supports them, such as supported transformations, history availability, and release-calendar linkage.
indicatorany
Optional indicator slug to limit coverage calculation, for example `core_inflation`. Use this when you already know the candidate series.

risk_sentiment

Return the global risk-on/risk-off sentiment series used for FX regime analysis. The result includes a derived composite score, regime label, component contributions, pagination, and data_quality metadata. Use this for cross-asset regime context before classifying high-beta, safe-haven, commodity, or USD-defensive FX conditions.

Parameters (2)

start_dateany
Optional inclusive start date in YYYY-MM-DD format.
end_dateany
Optional inclusive end date in YYYY-MM-DD format.

release_calendar

Get upcoming scheduled macroeconomic release timestamps for a currency. Use this when the user asks 'when is the next CPI/GDP/payrolls/policy decision', or to plan a trade around a known release. Returns ISO-8601 announcement_datetime values in UTC plus market-local timestamps. Pass `timezone` for an additional `announcement_datetime_requested_timezone` field. Each row has a `release` string with the indicator name and a `currency` code. Unbounded calls return future releases only; do not show stale past rows unless the user explicitly asks for historical/past calendar data. Consumer-facing clients should present the returned markdown agenda or render the Release Calendar App resource; do not summarize this tool as only a row count. Pass an optional `indicator` filter to narrow to a single series. Pass optional `start_date` and `end_date` bounds when the user mentions a month, week, day, or explicit date range. Supported currencies: AED, ARS, AUD, BOB, BRL, CAD, CHF, CLP, CNH, CNY, COMM, COP, CZK, DKK, DZD, EGP, EUR, GBP, HKD, HUF, IDR, ILS, INR, JPY, KRW, MAD, MXN, MYR, NGN, NOK, NZD, PEN, PHP, PKR, PLN, RUB, SAR, SEK, SGD, THB, TRY, TWD, USD, UYU, VND, ZAR. Supported indicators: average_hourly_earnings, balance_on_goods, balance_on_services, boc_business_outlook, breakeven_inflation_rate, broad_money, building_approvals, building_permits, business_confidence, cb_assets, commodity_price_energy, commodity_price_ex_energy, commodity_price_index, commodity_prices, consumer_confidence, consumer_expectations, core_inflation, core_inflation_median, core_inflation_mom, core_inflation_trim, core_pce, credit_growth, current_account_balance, dairy_exports, deposit_rates, domestic_credit, durable_goods_orders, employment, exports, foreign_reserves, full_time_employment, fx_reserves, gdp, gdp_growth_q4_yoy, gdp_growth_qoq_saar, gdp_quarterly, gold_reserves, gov_bond_10y, gov_bond_1y, gov_bond_20y, gov_bond_2y, gov_bond_30y, gov_bond_3y, gov_bond_40y, gov_bond_4y, gov_bond_5y, gov_bond_7y, government_debt, house_price_index, house_prices, household_credit, housing_starts, imports, industrial_production, inflation, inflation_expectations, inflation_linked_bond, inflation_mom, initial_jobless_claims, job_openings, kof_barometer, m1, m2, m3, money_supply_currency, money_supply_savings_deposits, money_supply_term_deposits, money_supply_transaction_deposits, monthly_cpi, mortgage_rate, nairu, nmi, non_farm_payrolls, part_time_employment, participation_rate, pce, pce_mom, pmi, policy_rate, policy_rate_mlf, policy_rate_mro, policy_rate_target_lower, ppi, ppi_mom, private_sector_credit, real_exchange_rate, retail_sales, risk_free_rate, sight_deposits, snb_balance_sheet, tankan_capex, terms_of_trade, trade_balance, trade_weighted_index, trimmed_mean_inflation, unemployment, wage_price_index, wages.

Parameters (5)

currencystringrequired
3-letter ISO currency code (case-insensitive). Supported: AED, ARS, AUD, BOB, BRL, CAD, CHF, CLP, CNH, CNY, COMM, COP, CZK, DKK, DZD, EGP, EUR, GBP, HKD, HUF, IDR, ILS, INR, JPY, KRW, MAD, MXN, MYR, NGN, NOK, NZD, PEN, PHP, PKR, PLN, RUB, SAR, SEK, SGD, THB, TRY, TWD, USD, UYU, VND, ZAR.
indicatorany
Optional indicator slug to narrow results. Supported: average_hourly_earnings, balance_on_goods, balance_on_services, boc_business_outlook, breakeven_inflation_rate, broad_money, building_approvals, building_permits, business_confidence, cb_assets, commodity_price_energy, commodity_price_ex_energy, commodity_price_index, commodity_prices, consumer_confidence, consumer_expectations, core_inflation, core_inflation_median, core_inflation_mom, core_inflation_trim, core_pce, credit_growth, current_account_balance, dairy_exports, deposit_rates, domestic_credit, durable_goods_orders, employment, exports, foreign_reserves, full_time_employment, fx_reserves, gdp, gdp_growth_q4_yoy, gdp_growth_qoq_saar, gdp_quarterly, gold_reserves, gov_bond_10y, gov_bond_1y, gov_bond_20y, gov_bond_2y, gov_bond_30y, gov_bond_3y, gov_bond_40y, gov_bond_4y, gov_bond_5y, gov_bond_7y, government_debt, house_price_index, house_prices, household_credit, housing_starts, imports, industrial_production, inflation, inflation_expectations, inflation_linked_bond, inflation_mom, initial_jobless_claims, job_openings, kof_barometer, m1, m2, m3, money_supply_currency, money_supply_savings_deposits, money_supply_term_deposits, money_supply_transaction_deposits, monthly_cpi, mortgage_rate, nairu, nmi, non_farm_payrolls, part_time_employment, participation_rate, pce, pce_mom, pmi, policy_rate, policy_rate_mlf, policy_rate_mro, policy_rate_target_lower, ppi, ppi_mom, private_sector_credit, real_exchange_rate, retail_sales, risk_free_rate, sight_deposits, snb_balance_sheet, tankan_capex, terms_of_trade, trade_balance, trade_weighted_index, trimmed_mean_inflation, unemployment, wage_price_index, wages.
start_dateany
Optional inclusive lower bound, YYYY-MM-DD.
end_dateany
Optional inclusive upper bound, YYYY-MM-DD.
timezoneany
Optional IANA timezone for an additional converted timestamp, for example America/Sao_Paulo.

release_calendar_visual_artifact

Same payload as release_calendar, but named as an explicit visual artifact tool so compatible MCP Apps clients render the interactive Release Calendar App inline. Prefer this by default when the user asks to show, display, visualize, or render a macro release calendar, especially for prompts like 'show me the AUD release calendar'. Only prefer plain release_calendar when the user explicitly asks for a raw table, JSON, exact rows, or text-only output. Pass optional `indicator`, `start_date`, and `end_date` filters when the user names a specific series, month, week, day, or date range. Pass `timezone` when the user asks for local times in a specific city or region. Supported currencies: AED, ARS, AUD, BOB, BRL, CAD, CHF, CLP, CNH, CNY, COMM, COP, CZK, DKK, DZD, EGP, EUR, GBP, HKD, HUF, IDR, ILS, INR, JPY, KRW, MAD, MXN, MYR, NGN, NOK, NZD, PEN, PHP, PKR, PLN, RUB, SAR, SEK, SGD, THB, TRY, TWD, USD, UYU, VND, ZAR. Supported indicators: average_hourly_earnings, balance_on_goods, balance_on_services, boc_business_outlook, breakeven_inflation_rate, broad_money, building_approvals, building_permits, business_confidence, cb_assets, commodity_price_energy, commodity_price_ex_energy, commodity_price_index, commodity_prices, consumer_confidence, consumer_expectations, core_inflation, core_inflation_median, core_inflation_mom, core_inflation_trim, core_pce, credit_growth, current_account_balance, dairy_exports, deposit_rates, domestic_credit, durable_goods_orders, employment, exports, foreign_reserves, full_time_employment, fx_reserves, gdp, gdp_growth_q4_yoy, gdp_growth_qoq_saar, gdp_quarterly, gold_reserves, gov_bond_10y, gov_bond_1y, gov_bond_20y, gov_bond_2y, gov_bond_30y, gov_bond_3y, gov_bond_40y, gov_bond_4y, gov_bond_5y, gov_bond_7y, government_debt, house_price_index, house_prices, household_credit, housing_starts, imports, industrial_production, inflation, inflation_expectations, inflation_linked_bond, inflation_mom, initial_jobless_claims, job_openings, kof_barometer, m1, m2, m3, money_supply_currency, money_supply_savings_deposits, money_supply_term_deposits, money_supply_transaction_deposits, monthly_cpi, mortgage_rate, nairu, nmi, non_farm_payrolls, part_time_employment, participation_rate, pce, pce_mom, pmi, policy_rate, policy_rate_mlf, policy_rate_mro, policy_rate_target_lower, ppi, ppi_mom, private_sector_credit, real_exchange_rate, retail_sales, risk_free_rate, sight_deposits, snb_balance_sheet, tankan_capex, terms_of_trade, trade_balance, trade_weighted_index, trimmed_mean_inflation, unemployment, wage_price_index, wages.

Parameters (5)

currencystringrequired
3-letter ISO currency code (case-insensitive). Supported: AED, ARS, AUD, BOB, BRL, CAD, CHF, CLP, CNH, CNY, COMM, COP, CZK, DKK, DZD, EGP, EUR, GBP, HKD, HUF, IDR, ILS, INR, JPY, KRW, MAD, MXN, MYR, NGN, NOK, NZD, PEN, PHP, PKR, PLN, RUB, SAR, SEK, SGD, THB, TRY, TWD, USD, UYU, VND, ZAR.
indicatorany
Optional indicator slug to narrow results. Supported: average_hourly_earnings, balance_on_goods, balance_on_services, boc_business_outlook, breakeven_inflation_rate, broad_money, building_approvals, building_permits, business_confidence, cb_assets, commodity_price_energy, commodity_price_ex_energy, commodity_price_index, commodity_prices, consumer_confidence, consumer_expectations, core_inflation, core_inflation_median, core_inflation_mom, core_inflation_trim, core_pce, credit_growth, current_account_balance, dairy_exports, deposit_rates, domestic_credit, durable_goods_orders, employment, exports, foreign_reserves, full_time_employment, fx_reserves, gdp, gdp_growth_q4_yoy, gdp_growth_qoq_saar, gdp_quarterly, gold_reserves, gov_bond_10y, gov_bond_1y, gov_bond_20y, gov_bond_2y, gov_bond_30y, gov_bond_3y, gov_bond_40y, gov_bond_4y, gov_bond_5y, gov_bond_7y, government_debt, house_price_index, house_prices, household_credit, housing_starts, imports, industrial_production, inflation, inflation_expectations, inflation_linked_bond, inflation_mom, initial_jobless_claims, job_openings, kof_barometer, m1, m2, m3, money_supply_currency, money_supply_savings_deposits, money_supply_term_deposits, money_supply_transaction_deposits, monthly_cpi, mortgage_rate, nairu, nmi, non_farm_payrolls, part_time_employment, participation_rate, pce, pce_mom, pmi, policy_rate, policy_rate_mlf, policy_rate_mro, policy_rate_target_lower, ppi, ppi_mom, private_sector_credit, real_exchange_rate, retail_sales, risk_free_rate, sight_deposits, snb_balance_sheet, tankan_capex, terms_of_trade, trade_balance, trade_weighted_index, trimmed_mean_inflation, unemployment, wage_price_index, wages.
start_dateany
Optional inclusive lower bound, YYYY-MM-DD.
end_dateany
Optional inclusive upper bound, YYYY-MM-DD.
timezoneany
Optional IANA timezone for an additional converted timestamp, for example America/Sao_Paulo.

forex

Get raw historical FX spot-rate rows for a currency pair (e.g. EUR/USD, USD/JPY). Prefer this tool when the user explicitly wants a plain-text table, raw rows, exact values, JSON-like data, or technical-indicator series (SMA, EMA, RSI, MACD, Bollinger Bands, etc.) computed from spot without a chart. If the user asks more generally to show/tell/explain the last few weeks or months of a pair, prefer forex_visual_artifact instead so the client can render a chart. Daily granularity from official central-bank reference rates with full multi-year history. Supported currencies (use lowercase 3-letter codes): AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD. Optional `indicators` parameter accepts a comma-separated list of technical indicator slugs to attach to each row. Supported indicator values: bollinger_bands, ema_12, ema_26, macd, rsi_14, sma_20, sma_200, sma_50, all.

Parameters (5)

basestringrequired
Base currency, 3-letter ISO code (case-insensitive). Supported: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD.
quotestringrequired
Quote currency, 3-letter ISO code (case-insensitive). Supported: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD.
start_dateany
Inclusive lower bound, YYYY-MM-DD. Defaults to ~5 years ago.
end_dateany
Inclusive upper bound, YYYY-MM-DD. Defaults to today.
indicatorsany
Comma-separated technical-indicator slugs to attach to each row. Supported: bollinger_bands, ema_12, ema_26, macd, rsi_14, sma_20, sma_200, sma_50, all.

indicator_query

Get a paginated historical time series of a single macroeconomic indicator for a currency, sourced directly from the official central bank or statistical agency. Use this for CPI/inflation, GDP, unemployment, policy rates, bond yields, payrolls, retail sales, PCE, PPI, trade balance, current account, money supply, and similar series. Each row returns `date` (value-as-of), `val` (numeric), and `announcement_datetime` (when the value was first published — useful for backtest point-in-time integrity). Successful responses are chart-ready by default for MCP Apps hosts while preserving the full raw result envelope for data workflows. Use `limit`, `offset`, or `page` to page through broad histories; check `pagination.next_offset` and `pagination.page_includes_latest_available` in the result. Responses default to official-source rows only; prohibited private aggregator rows are always removed. Always call data_catalogue(currency) first to get the exact indicator slug. USD indicators are free; non-USD requires API key. Supported currencies: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD. Supported indicators: average_hourly_earnings, balance_on_goods, balance_on_services, boc_business_outlook, breakeven_inflation_rate, broad_money, building_approvals, building_permits, business_confidence, cb_assets, commodity_price_energy, commodity_price_ex_energy, commodity_price_index, commodity_prices, consumer_confidence, consumer_expectations, core_inflation, core_inflation_median, core_inflation_mom, core_inflation_trim, core_pce, credit_growth, current_account_balance, dairy_exports, deposit_rates, domestic_credit, durable_goods_orders, employment, exports, foreign_reserves, full_time_employment, fx_reserves, gdp, gdp_growth_q4_yoy, gdp_growth_qoq_saar, gdp_quarterly, gold_reserves, gov_bond_10y, gov_bond_1y, gov_bond_20y, gov_bond_2y, gov_bond_30y, gov_bond_3y, gov_bond_40y, gov_bond_4y, gov_bond_5y, gov_bond_7y, government_debt, house_price_index, house_prices, household_credit, housing_starts, imports, industrial_production, inflation, inflation_expectations, inflation_linked_bond, inflation_mom, initial_jobless_claims, job_openings, kof_barometer, m1, m2, m3, money_supply_currency, money_supply_savings_deposits, money_supply_term_deposits, money_supply_transaction_deposits, monthly_cpi, mortgage_rate, nairu, nmi, non_farm_payrolls, part_time_employment, participation_rate, pce, pce_mom, pmi, policy_rate, policy_rate_mlf, policy_rate_mro, policy_rate_target_lower, ppi, ppi_mom, private_sector_credit, real_exchange_rate, retail_sales, risk_free_rate, sight_deposits, snb_balance_sheet, tankan_capex, terms_of_trade, trade_balance, trade_weighted_index, trimmed_mean_inflation, unemployment, wage_price_index, wages.

Parameters (9)

currencyany
3-letter ISO currency code (case-insensitive). Optional if `slug` is provided as a `"usd:cpi"`-style compound. Supported: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD.
indicatorany
Indicator slug for the given currency. Optional if `slug` is provided as a `"usd:cpi"`-style compound. Supported: average_hourly_earnings, balance_on_goods, balance_on_services, boc_business_outlook, breakeven_inflation_rate, broad_money, building_approvals, building_permits, business_confidence, cb_assets, commodity_price_energy, commodity_price_ex_energy, commodity_price_index, commodity_prices, consumer_confidence, consumer_expectations, core_inflation, core_inflation_median, core_inflation_mom, core_inflation_trim, core_pce, credit_growth, current_account_balance, dairy_exports, deposit_rates, domestic_credit, durable_goods_orders, employment, exports, foreign_reserves, full_time_employment, fx_reserves, gdp, gdp_growth_q4_yoy, gdp_growth_qoq_saar, gdp_quarterly, gold_reserves, gov_bond_10y, gov_bond_1y, gov_bond_20y, gov_bond_2y, gov_bond_30y, gov_bond_3y, gov_bond_40y, gov_bond_4y, gov_bond_5y, gov_bond_7y, government_debt, house_price_index, house_prices, household_credit, housing_starts, imports, industrial_production, inflation, inflation_expectations, inflation_linked_bond, inflation_mom, initial_jobless_claims, job_openings, kof_barometer, m1, m2, m3, money_supply_currency, money_supply_savings_deposits, money_supply_term_deposits, money_supply_transaction_deposits, monthly_cpi, mortgage_rate, nairu, nmi, non_farm_payrolls, part_time_employment, participation_rate, pce, pce_mom, pmi, policy_rate, policy_rate_mlf, policy_rate_mro, policy_rate_target_lower, ppi, ppi_mom, private_sector_credit, real_exchange_rate, retail_sales, risk_free_rate, sight_deposits, snb_balance_sheet, tankan_capex, terms_of_trade, trade_balance, trade_weighted_index, trimmed_mean_inflation, unemployment, wage_price_index, wages.
start_dateany
Inclusive lower bound, YYYY-MM-DD.
end_dateany
Inclusive upper bound, YYYY-MM-DD.
limitinteger
Maximum rows to return from the existing REST pagination path. Defaults to 20; maximum 100.
offsetinteger
Zero-based row offset after most-recent-first ordering.
pageany
One-based page number. When supplied, the REST endpoint derives offset as `(page - 1) * limit`.
slugany
Optional compound `"<currency>:<indicator>"` slug (e.g. `"usd:cpi"`, `"jpy:policy_rate"`). Many small / open tool-calling models concatenate the two parts anyway. When supplied, overrides `currency` and `indicator`.
official_onlyboolean
When true, return only official-source rows and remove explicit fallback observations. Prohibited private aggregator rows are always removed.

indicator_visual_artifact

Same payload as indicator_query, but also returns MCP Apps metadata so compatible clients (Claude Desktop, ChatGPT, Codex, etc.) render an interactive line chart instead of a JSON dump. Prefer this by default for indicator time-series requests, especially when the user asks to show, tell, explain, compare, inspect a trend, or review a recent window. For broad histories, use the existing `limit`, `offset`, or `page` controls and inspect `pagination.next_offset` rather than retrying with arbitrary shorter windows. Only fall back to indicator_query when the user explicitly wants a raw table, plain text list, JSON, exact rows, or minimal structured data. Supported currencies: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD. Supported indicators: average_hourly_earnings, balance_on_goods, balance_on_services, boc_business_outlook, breakeven_inflation_rate, broad_money, building_approvals, building_permits, business_confidence, cb_assets, commodity_price_energy, commodity_price_ex_energy, commodity_price_index, commodity_prices, consumer_confidence, consumer_expectations, core_inflation, core_inflation_median, core_inflation_mom, core_inflation_trim, core_pce, credit_growth, current_account_balance, dairy_exports, deposit_rates, domestic_credit, durable_goods_orders, employment, exports, foreign_reserves, full_time_employment, fx_reserves, gdp, gdp_growth_q4_yoy, gdp_growth_qoq_saar, gdp_quarterly, gold_reserves, gov_bond_10y, gov_bond_1y, gov_bond_20y, gov_bond_2y, gov_bond_30y, gov_bond_3y, gov_bond_40y, gov_bond_4y, gov_bond_5y, gov_bond_7y, government_debt, house_price_index, house_prices, household_credit, housing_starts, imports, industrial_production, inflation, inflation_expectations, inflation_linked_bond, inflation_mom, initial_jobless_claims, job_openings, kof_barometer, m1, m2, m3, money_supply_currency, money_supply_savings_deposits, money_supply_term_deposits, money_supply_transaction_deposits, monthly_cpi, mortgage_rate, nairu, nmi, non_farm_payrolls, part_time_employment, participation_rate, pce, pce_mom, pmi, policy_rate, policy_rate_mlf, policy_rate_mro, policy_rate_target_lower, ppi, ppi_mom, private_sector_credit, real_exchange_rate, retail_sales, risk_free_rate, sight_deposits, snb_balance_sheet, tankan_capex, terms_of_trade, trade_balance, trade_weighted_index, trimmed_mean_inflation, unemployment, wage_price_index, wages.

Parameters (7)

currencystringrequired
3-letter ISO currency code (case-insensitive). Supported: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD.
indicatorstringrequired
Indicator slug. Supported: average_hourly_earnings, balance_on_goods, balance_on_services, boc_business_outlook, breakeven_inflation_rate, broad_money, building_approvals, building_permits, business_confidence, cb_assets, commodity_price_energy, commodity_price_ex_energy, commodity_price_index, commodity_prices, consumer_confidence, consumer_expectations, core_inflation, core_inflation_median, core_inflation_mom, core_inflation_trim, core_pce, credit_growth, current_account_balance, dairy_exports, deposit_rates, domestic_credit, durable_goods_orders, employment, exports, foreign_reserves, full_time_employment, fx_reserves, gdp, gdp_growth_q4_yoy, gdp_growth_qoq_saar, gdp_quarterly, gold_reserves, gov_bond_10y, gov_bond_1y, gov_bond_20y, gov_bond_2y, gov_bond_30y, gov_bond_3y, gov_bond_40y, gov_bond_4y, gov_bond_5y, gov_bond_7y, government_debt, house_price_index, house_prices, household_credit, housing_starts, imports, industrial_production, inflation, inflation_expectations, inflation_linked_bond, inflation_mom, initial_jobless_claims, job_openings, kof_barometer, m1, m2, m3, money_supply_currency, money_supply_savings_deposits, money_supply_term_deposits, money_supply_transaction_deposits, monthly_cpi, mortgage_rate, nairu, nmi, non_farm_payrolls, part_time_employment, participation_rate, pce, pce_mom, pmi, policy_rate, policy_rate_mlf, policy_rate_mro, policy_rate_target_lower, ppi, ppi_mom, private_sector_credit, real_exchange_rate, retail_sales, risk_free_rate, sight_deposits, snb_balance_sheet, tankan_capex, terms_of_trade, trade_balance, trade_weighted_index, trimmed_mean_inflation, unemployment, wage_price_index, wages.
start_dateany
Inclusive lower bound, YYYY-MM-DD.
end_dateany
Inclusive upper bound, YYYY-MM-DD.
limitinteger
Maximum rows to render from the existing REST pagination path. Defaults to 20; maximum 100.
offsetinteger
Zero-based row offset after most-recent-first ordering.
pageany
One-based page number. When supplied, the REST endpoint derives offset as `(page - 1) * limit`.

forex_visual_artifact

Same payload as forex, but packaged with MCP Apps chart metadata so compatible clients render an interactive spot-rate chart inline. Prefer this by default for FX pair time-series requests, especially for prompts like 'show me AUD/USD', 'tell me the last 30 days', 'how has EUR/USD moved recently', or any request where a trend view is more useful than raw rows. Only prefer plain forex when the user explicitly asks for a table, raw values, JSON, CSV-style output, or exact row-by-row data.

Parameters (5)

basestringrequired
Base currency, 3-letter ISO code (case-insensitive). Supported: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD.
quotestringrequired
Quote currency, 3-letter ISO code (case-insensitive). Supported: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD.
start_dateany
Inclusive lower bound, YYYY-MM-DD.
end_dateany
Inclusive upper bound, YYYY-MM-DD.
indicatorsany
Optional technical indicators to include in the raw payload. Supported: bollinger_bands, ema_12, ema_26, macd, rsi_14, sma_20, sma_200, sma_50, all.

commodities_visual_artifact

Same payload as commodities, but packaged with MCP Apps chart metadata so compatible clients render an interactive commodity chart inline.

Parameters (3)

indicatorstringrequired
Commodity indicator slug. Supported: gold, natural_gas, oil_brent, oil_wti, platinum, silver.
start_dateany
Inclusive lower bound, YYYY-MM-DD.
end_dateany
Inclusive upper bound, YYYY-MM-DD.

cot_visual_artifact

Same payload as cot_data, but with MCP Apps chart metadata. By default it charts noncommercial net positioning; pass `metric` to chart another COT field.

Parameters (4)

currencystringrequired
3-letter ISO currency code for the FX futures contract (case-insensitive). Supported: AUD, CAD, CHF, EUR, GBP, HUF, JPY, MXN, NZD, TRY, USD.
start_dateany
Inclusive lower bound, YYYY-MM-DD.
end_dateany
Inclusive upper bound, YYYY-MM-DD.
metricany
Field to plot from each COT row. Typical values: noncommercial_net, noncommercial_net_zscore, noncommercial_long, noncommercial_short, open_interest.

policy_rate_differential_visual_artifact

Build a two-series chart comparing base and quote policy-rate history to visualize the rate differential setup for an FX pair.

Parameters (4)

basestringrequired
Base currency, 3-letter ISO code (case-insensitive). Supported: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD.
quotestringrequired
Quote currency, 3-letter ISO code (case-insensitive). Supported: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD.
start_dateany
Inclusive lower bound, YYYY-MM-DD.
end_dateany
Inclusive upper bound, YYYY-MM-DD.

macro_briefing_task

Build a compact macro briefing for a currency by combining catalogue, policy rate, GDP, and release-calendar data. Supports MCP Tasks for async execution when clients send a task-augmented request.

Parameters (1)

currencystringrequired
3-letter ISO currency code (case-insensitive). Supported: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD.

indicator_intel_task

Build an intelligence pack for one indicator by combining chart-ready series data, derived analytics, and nearest release timing context. Supports MCP Tasks for async execution when clients send task-augmented requests.

Parameters (4)

currencystringrequired
3-letter ISO currency code (case-insensitive). Supported: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD.
indicatorstringrequired
Indicator slug for the given currency. Supported: average_hourly_earnings, balance_on_goods, balance_on_services, boc_business_outlook, breakeven_inflation_rate, broad_money, building_approvals, building_permits, business_confidence, cb_assets, commodity_price_energy, commodity_price_ex_energy, commodity_price_index, commodity_prices, consumer_confidence, consumer_expectations, core_inflation, core_inflation_median, core_inflation_mom, core_inflation_trim, core_pce, credit_growth, current_account_balance, dairy_exports, deposit_rates, domestic_credit, durable_goods_orders, employment, exports, foreign_reserves, full_time_employment, fx_reserves, gdp, gdp_growth_q4_yoy, gdp_growth_qoq_saar, gdp_quarterly, gold_reserves, gov_bond_10y, gov_bond_1y, gov_bond_20y, gov_bond_2y, gov_bond_30y, gov_bond_3y, gov_bond_40y, gov_bond_4y, gov_bond_5y, gov_bond_7y, government_debt, house_price_index, house_prices, household_credit, housing_starts, imports, industrial_production, inflation, inflation_expectations, inflation_linked_bond, inflation_mom, initial_jobless_claims, job_openings, kof_barometer, m1, m2, m3, money_supply_currency, money_supply_savings_deposits, money_supply_term_deposits, money_supply_transaction_deposits, monthly_cpi, mortgage_rate, nairu, nmi, non_farm_payrolls, part_time_employment, participation_rate, pce, pce_mom, pmi, policy_rate, policy_rate_mlf, policy_rate_mro, policy_rate_target_lower, ppi, ppi_mom, private_sector_credit, real_exchange_rate, retail_sales, risk_free_rate, sight_deposits, snb_balance_sheet, tankan_capex, terms_of_trade, trade_balance, trade_weighted_index, trimmed_mean_inflation, unemployment, wage_price_index, wages.
start_dateany
Inclusive lower bound, YYYY-MM-DD.
end_dateany
Inclusive upper bound, YYYY-MM-DD.

pair_intel_task

Build an intelligence pack for an FX pair by combining policy-rate spread context, spot-rate context, and release-timing metadata. Supports MCP Tasks for async execution when clients send task-augmented requests.

Parameters (4)

basestringrequired
Base currency, 3-letter ISO code (case-insensitive). Supported: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD.
quotestringrequired
Quote currency, 3-letter ISO code (case-insensitive). Supported: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD.
start_dateany
Inclusive lower bound, YYYY-MM-DD.
end_dateany
Inclusive upper bound, YYYY-MM-DD.

macro_heatmap_task

Build a cross-currency macro heatmap from indicator time series and return a matrix with latest values, recent changes, and z-scores. Supports MCP Tasks for async execution when clients send task-augmented requests.

Parameters (4)

currenciesany
Comma-separated 3-letter currency codes (lowercase preferred). Supported values include: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD.
indicatorsany
Comma-separated indicator slugs to include in the matrix. Supported values include: average_hourly_earnings, balance_on_goods, balance_on_services, boc_business_outlook, breakeven_inflation_rate, broad_money, building_approvals, building_permits, business_confidence, cb_assets, commodity_price_energy, commodity_price_ex_energy, commodity_price_index, commodity_prices, consumer_confidence, consumer_expectations, core_inflation, core_inflation_median, core_inflation_mom, core_inflation_trim, core_pce, credit_growth, current_account_balance, dairy_exports, deposit_rates, domestic_credit, durable_goods_orders, employment, exports, foreign_reserves, full_time_employment, fx_reserves, gdp, gdp_growth_q4_yoy, gdp_growth_qoq_saar, gdp_quarterly, gold_reserves, gov_bond_10y, gov_bond_1y, gov_bond_20y, gov_bond_2y, gov_bond_30y, gov_bond_3y, gov_bond_40y, gov_bond_4y, gov_bond_5y, gov_bond_7y, government_debt, house_price_index, house_prices, household_credit, housing_starts, imports, industrial_production, inflation, inflation_expectations, inflation_linked_bond, inflation_mom, initial_jobless_claims, job_openings, kof_barometer, m1, m2, m3, money_supply_currency, money_supply_savings_deposits, money_supply_term_deposits, money_supply_transaction_deposits, monthly_cpi, mortgage_rate, nairu, nmi, non_farm_payrolls, part_time_employment, participation_rate, pce, pce_mom, pmi, policy_rate, policy_rate_mlf, policy_rate_mro, policy_rate_target_lower, ppi, ppi_mom, private_sector_credit, real_exchange_rate, retail_sales, risk_free_rate, sight_deposits, snb_balance_sheet, tankan_capex, terms_of_trade, trade_balance, trade_weighted_index, trimmed_mean_inflation, unemployment, wage_price_index, wages.
start_dateany
Optional inclusive lower bound, YYYY-MM-DD.
end_dateany
Optional inclusive upper bound, YYYY-MM-DD.

policy_scenario_modeler_task

Run a policy-rate spread what-if scenario for an FX pair and estimate directional spot impact using an explicit heuristic elasticity assumption. Supports MCP Tasks for async execution when clients send task-augmented requests.

Parameters (8)

basestringrequired
Base currency, 3-letter ISO code (case-insensitive). Supported: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD.
quotestringrequired
Quote currency, 3-letter ISO code (case-insensitive). Supported: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD.
shock_legany
Which leg receives the policy shock: base or quote.
shock_bpsany
Policy shock size in basis points (100 bps = 1.00 percentage point).
policy_shock_bpsany
Optional alias for shock_bps for compatibility with host-side app payloads.
elasticity_per_100bpsany
Heuristic percent change in FX spot for a 100 bps spread change. Used as a scenario assumption, not a forecast guarantee.
start_dateany
Optional inclusive lower bound, YYYY-MM-DD.
end_dateany
Optional inclusive upper bound, YYYY-MM-DD.

macro_war_room_task

Build a multi-panel macro market cockpit that combines FX sessions, upcoming release queue, pair context, and generated risk alerts. Supports MCP Tasks for async execution when clients send task-augmented requests.

Parameters (6)

baseany
Base currency for pair context, 3-letter ISO code (case-insensitive). Defaults to the release currency when omitted. Supported: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD.
quoteany
Quote currency for pair context, 3-letter ISO code (case-insensitive). Supported: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD.
currencyany
Release currency used for queue and spotlight indicator. Supported: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD.
indicatorany
Spotlight indicator slug for release context. Supported examples: average_hourly_earnings, balance_on_goods, balance_on_services, boc_business_outlook, breakeven_inflation_rate, broad_money, building_approvals, building_permits, business_confidence, cb_assets, commodity_price_energy, commodity_price_ex_energy, commodity_price_index, commodity_prices, consumer_confidence, consumer_expectations, core_inflation, core_inflation_median, core_inflation_mom, core_inflation_trim, core_pce, credit_growth, current_account_balance, dairy_exports, deposit_rates, domestic_credit, durable_goods_orders, employment, exports, foreign_reserves, full_time_employment, fx_reserves, gdp, gdp_growth_q4_yoy, gdp_growth_qoq_saar, gdp_quarterly, gold_reserves, gov_bond_10y, gov_bond_1y, gov_bond_20y, gov_bond_2y, gov_bond_30y, gov_bond_3y, gov_bond_40y, gov_bond_4y, gov_bond_5y, gov_bond_7y, government_debt, house_price_index, house_prices, household_credit, housing_starts, imports, industrial_production, inflation, inflation_expectations, inflation_linked_bond, inflation_mom, initial_jobless_claims, job_openings, kof_barometer, m1, m2, m3, money_supply_currency, money_supply_savings_deposits, money_supply_term_deposits, money_supply_transaction_deposits, monthly_cpi, mortgage_rate, nairu, nmi, non_farm_payrolls, part_time_employment, participation_rate, pce, pce_mom, pmi, policy_rate, policy_rate_mlf, policy_rate_mro, policy_rate_target_lower, ppi, ppi_mom, private_sector_credit, real_exchange_rate, retail_sales, risk_free_rate, sight_deposits, snb_balance_sheet, tankan_capex, terms_of_trade, trade_balance, trade_weighted_index, trimmed_mean_inflation, unemployment, wage_price_index, wages.
start_dateany
Optional inclusive lower bound, YYYY-MM-DD.
end_dateany
Optional inclusive upper bound, YYYY-MM-DD.

event_impact_replay_task

Create a point-in-time replay timeline mapping macro announcements to FX context and heuristic impact markers. Supports MCP Tasks for async execution when clients send task-augmented requests.

Parameters (7)

currencystringrequired
Currency for macro event series, 3-letter ISO code (case-insensitive). Supported: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD.
indicatorstringrequired
Indicator slug for event replay. Supported examples: average_hourly_earnings, balance_on_goods, balance_on_services, boc_business_outlook, breakeven_inflation_rate, broad_money, building_approvals, building_permits, business_confidence, cb_assets, commodity_price_energy, commodity_price_ex_energy, commodity_price_index, commodity_prices, consumer_confidence, consumer_expectations, core_inflation, core_inflation_median, core_inflation_mom, core_inflation_trim, core_pce, credit_growth, current_account_balance, dairy_exports, deposit_rates, domestic_credit, durable_goods_orders, employment, exports, foreign_reserves, full_time_employment, fx_reserves, gdp, gdp_growth_q4_yoy, gdp_growth_qoq_saar, gdp_quarterly, gold_reserves, gov_bond_10y, gov_bond_1y, gov_bond_20y, gov_bond_2y, gov_bond_30y, gov_bond_3y, gov_bond_40y, gov_bond_4y, gov_bond_5y, gov_bond_7y, government_debt, house_price_index, house_prices, household_credit, housing_starts, imports, industrial_production, inflation, inflation_expectations, inflation_linked_bond, inflation_mom, initial_jobless_claims, job_openings, kof_barometer, m1, m2, m3, money_supply_currency, money_supply_savings_deposits, money_supply_term_deposits, money_supply_transaction_deposits, monthly_cpi, mortgage_rate, nairu, nmi, non_farm_payrolls, part_time_employment, participation_rate, pce, pce_mom, pmi, policy_rate, policy_rate_mlf, policy_rate_mro, policy_rate_target_lower, ppi, ppi_mom, private_sector_credit, real_exchange_rate, retail_sales, risk_free_rate, sight_deposits, snb_balance_sheet, tankan_capex, terms_of_trade, trade_balance, trade_weighted_index, trimmed_mean_inflation, unemployment, wage_price_index, wages.
baseany
FX base currency for market context, 3-letter ISO code (case-insensitive). Supported: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD.
quoteany
FX quote currency for market context, 3-letter ISO code (case-insensitive). Supported: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD.
lookback_eventsany
Maximum number of recent events to include in replay.
start_dateany
Optional inclusive lower bound, YYYY-MM-DD.
end_dateany
Optional inclusive upper bound, YYYY-MM-DD.

quant_scenario_lab_task

Run an expanded quant-style policy scenario for an FX pair with deterministic projection, stress percentiles, and horizon assumptions. Supports MCP Tasks for async execution when clients send task-augmented requests.

Parameters (9)

basestringrequired
Base currency, 3-letter ISO code (case-insensitive). Supported: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD.
quotestringrequired
Quote currency, 3-letter ISO code (case-insensitive). Supported: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD.
shock_legany
Which leg receives the policy shock: base or quote.
shock_bpsany
Policy shock size in basis points (100 bps = 1.00 percentage point).
elasticity_per_100bpsany
Heuristic percent FX move per 100 bps spread change.
annualized_volatility_pctany
Annualized volatility assumption (percent) for stress-band construction.
horizon_daysany
Scenario horizon in calendar days.
start_dateany
Optional inclusive lower bound, YYYY-MM-DD.
end_dateany
Optional inclusive upper bound, YYYY-MM-DD.

known_at_time_task

Return the slice of a macro series that would have been known at a specific timestamp, using announcement_datetime as the point-in-time integrity boundary. Supports MCP Tasks for async execution when clients send task-augmented requests.

Parameters (5)

currencystringrequired
3-letter ISO currency code (case-insensitive). Supported: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD.
indicatorstringrequired
Indicator slug for the given currency. Supported: average_hourly_earnings, balance_on_goods, balance_on_services, boc_business_outlook, breakeven_inflation_rate, broad_money, building_approvals, building_permits, business_confidence, cb_assets, commodity_price_energy, commodity_price_ex_energy, commodity_price_index, commodity_prices, consumer_confidence, consumer_expectations, core_inflation, core_inflation_median, core_inflation_mom, core_inflation_trim, core_pce, credit_growth, current_account_balance, dairy_exports, deposit_rates, domestic_credit, durable_goods_orders, employment, exports, foreign_reserves, full_time_employment, fx_reserves, gdp, gdp_growth_q4_yoy, gdp_growth_qoq_saar, gdp_quarterly, gold_reserves, gov_bond_10y, gov_bond_1y, gov_bond_20y, gov_bond_2y, gov_bond_30y, gov_bond_3y, gov_bond_40y, gov_bond_4y, gov_bond_5y, gov_bond_7y, government_debt, house_price_index, house_prices, household_credit, housing_starts, imports, industrial_production, inflation, inflation_expectations, inflation_linked_bond, inflation_mom, initial_jobless_claims, job_openings, kof_barometer, m1, m2, m3, money_supply_currency, money_supply_savings_deposits, money_supply_term_deposits, money_supply_transaction_deposits, monthly_cpi, mortgage_rate, nairu, nmi, non_farm_payrolls, part_time_employment, participation_rate, pce, pce_mom, pmi, policy_rate, policy_rate_mlf, policy_rate_mro, policy_rate_target_lower, ppi, ppi_mom, private_sector_credit, real_exchange_rate, retail_sales, risk_free_rate, sight_deposits, snb_balance_sheet, tankan_capex, terms_of_trade, trade_balance, trade_weighted_index, trimmed_mean_inflation, unemployment, wage_price_index, wages.
as_ofstringrequired
UTC ISO-8601 timestamp or YYYY-MM-DD cutoff. Only rows with announcement_datetime <= this moment are returned.
start_dateany
Optional inclusive lower bound, YYYY-MM-DD.
end_dateany
Optional inclusive upper bound, YYYY-MM-DD.

macro_regime_classifier_task

Classify a currency's macro regime using policy rate, inflation, GDP, and unemployment context, with explicit assumptions and confidence notes. Supports MCP Tasks for async execution when clients send task-augmented requests.

Parameters (3)

currencystringrequired
3-letter ISO currency code (case-insensitive). Supported: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD.
start_dateany
Optional inclusive lower bound, YYYY-MM-DD.
end_dateany
Optional inclusive upper bound, YYYY-MM-DD.

release_risk_score_task

Score upcoming releases for a currency pair using release-calendar proximity and indicator-level heuristics. Supports MCP Tasks for async execution when clients send task-augmented requests.

Parameters (3)

basestringrequired
Base currency, 3-letter ISO code. Supported: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD.
quotestringrequired
Quote currency, 3-letter ISO code. Supported: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD.
horizon_eventsany
Maximum release events per currency to score.

portfolio_risk_engine_task

Analyze a multi-position FX book for concentration, stress exposure, and event-driven catalyst risk. Supports MCP Tasks for async execution when clients send task-augmented requests.

Parameters (3)

positions_jsonstringrequired
JSON array of FX positions. Each item should include base, quote, side (long/short), and notional. Example: [{"base":"eur","quote":"usd","side":"long","notional":100000}]
stress_shock_pctany
Stress shock in percent applied to each pair.
horizon_eventsany
Maximum release events to consider per currency leg.

fx_trade_setup_task

Build a trader-oriented FX pair setup using spot context, macro differentials, upcoming catalyst risk, and optional COT positioning. Supports MCP Tasks for async execution when clients send task-augmented requests.

Parameters (4)

basestringrequired
Base currency, 3-letter ISO code. Supported: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD.
quotestringrequired
Quote currency, 3-letter ISO code. Supported: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD.
horizon_eventsany
Maximum upcoming catalysts per leg to rank.
include_cotany
When true, attempt to include COT positioning context for both legs.

fx_backtest_task

Run a transparent rule-based FX backtest on historical spot data using carry and/or momentum signals. Supports MCP Tasks for async execution when clients send task-augmented requests.

Parameters (10)

basestringrequired
Base currency, 3-letter ISO code. Supported: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD.
quotestringrequired
Quote currency, 3-letter ISO code. Supported: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD.
start_dateany
Inclusive lower bound, YYYY-MM-DD.
end_dateany
Inclusive upper bound, YYYY-MM-DD.
strategyany
Signal mode: carry, momentum, or carry_momentum.
momentum_lookbackany
Momentum lookback in observations for the momentum signal.
transaction_cost_bpsany
Per-side transaction cost in basis points applied on position changes.
initial_capitalany
Starting capital for equity-curve calculations.
event_gatedany
When true, only allow positions during release-event windows derived from announcement_datetime on base and quote calendars.
event_window_daysany
Event gate window in days around each release date (0 means release-date only).

macro_research_pack_task

Bundle catalogue, indicator history, next release timing, and optional FX pair context into one persistent-host-friendly research payload. Supports MCP Tasks for async execution when clients send task-augmented requests.

Parameters (6)

currencystringrequired
3-letter ISO currency code. Supported: AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, IDR, ILS, JPY, NZD, PEN, SEK, THB, USD.
indicatorstringrequired
Indicator slug. Supported: average_hourly_earnings, balance_on_goods, balance_on_services, boc_business_outlook, breakeven_inflation_rate, broad_money, building_approvals, building_permits, business_confidence, cb_assets, commodity_price_energy, commodity_price_ex_energy, commodity_price_index, commodity_prices, consumer_confidence, consumer_expectations, core_inflation, core_inflation_median, core_inflation_mom, core_inflation_trim, core_pce, credit_growth, current_account_balance, dairy_exports, deposit_rates, domestic_credit, durable_goods_orders, employment, exports, foreign_reserves, full_time_employment, fx_reserves, gdp, gdp_growth_q4_yoy, gdp_growth_qoq_saar, gdp_quarterly, gold_reserves, gov_bond_10y, gov_bond_1y, gov_bond_20y, gov_bond_2y, gov_bond_30y, gov_bond_3y, gov_bond_40y, gov_bond_4y, gov_bond_5y, gov_bond_7y, government_debt, house_price_index, house_prices, household_credit, housing_starts, imports, industrial_production, inflation, inflation_expectations, inflation_linked_bond, inflation_mom, initial_jobless_claims, job_openings, kof_barometer, m1, m2, m3, money_supply_currency, money_supply_savings_deposits, money_supply_term_deposits, money_supply_transaction_deposits, monthly_cpi, mortgage_rate, nairu, nmi, non_farm_payrolls, part_time_employment, participation_rate, pce, pce_mom, pmi, policy_rate, policy_rate_mlf, policy_rate_mro, policy_rate_target_lower, ppi, ppi_mom, private_sector_credit, real_exchange_rate, retail_sales, risk_free_rate, sight_deposits, snb_balance_sheet, tankan_capex, terms_of_trade, trade_balance, trade_weighted_index, trimmed_mean_inflation, unemployment, wage_price_index, wages.
baseany
Optional FX base currency for pair context.
quoteany
Optional FX quote currency for pair context.
start_dateany
Optional inclusive lower bound, YYYY-MM-DD.
end_dateany
Optional inclusive upper bound, YYYY-MM-DD.

market_sessions

Tell the user which FX trading sessions are currently open (Sydney, Tokyo, London, New York) and when the next session opens/closes. Use this when the user asks 'is the market open?', 'when does London open?', or 'which sessions overlap right now?'. Pass an ISO-8601 UTC timestamp via `at` to get the snapshot for a specific moment instead of now. Accounts for weekends and major banking holidays.

Parameters (1)

atany
Optional ISO-8601 UTC timestamp; defaults to now. Use to snapshot session state at a specific moment.

cot_data

Get weekly CFTC Commitment of Traders (COT) positioning data for a currency's FX futures contract on the CME. Use this when the user asks about speculator positioning, non-commercial longs vs shorts, hedge-fund FX positioning, or wants to gauge sentiment extremes. Returns weekly snapshots with long/short open interest by trader category. Updated every Friday at 15:30 ET reflecting the Tuesday cutoff. Requires an API key. Supported currencies: AUD, CAD, CHF, EUR, GBP, HUF, JPY, MXN, NZD, TRY, USD.

Parameters (3)

currencystringrequired
3-letter ISO currency code for the FX futures contract (case-insensitive). Supported: AUD, CAD, CHF, EUR, GBP, HUF, JPY, MXN, NZD, TRY, USD.
start_dateany
Inclusive lower bound, YYYY-MM-DD.
end_dateany
Inclusive upper bound, YYYY-MM-DD.

commodities

Get historical price series for supported commodity indicators using the exact slugs advertised by this schema. Requires an API key. Supported indicators: gold, natural_gas, oil_brent, oil_wti, platinum, silver.

Parameters (4)

indicatorany
Commodity indicator slug. Supported: gold, natural_gas, oil_brent, oil_wti, platinum, silver.
symbolany
Backward-compatible alias for `indicator`. Prefer `indicator` in new calls.
start_dateany
Inclusive lower bound, YYYY-MM-DD.
end_dateany
Inclusive upper bound, YYYY-MM-DD.

official_dataset_family

Get metadata-first official dataset payloads grouped by API endpoint type. Use endpoint_type to pick the API taxonomy group and dataset to choose the specific series family. Supported endpoint types: monetary_policy, fiscal_policy, international_trade, statistics_releases. Supported datasets: auction_metrics, bop, capital_flows, cb_liquidity, credit_conditions, external_debt, fx_intervention, iip, services_trade, treasury_cash, wage_settlements.

Parameters (4)

endpoint_typestringrequired
Endpoint taxonomy group from the API structure. Supported: monetary_policy, fiscal_policy, international_trade, statistics_releases.
datasetstringrequired
Dataset slug within the selected endpoint_type. Supported: auction_metrics, bop, capital_flows, cb_liquidity, credit_conditions, external_debt, fx_intervention, iip, services_trade, treasury_cash, wage_settlements.
currencystringrequired
3-letter ISO currency code (case-insensitive).
componentany
Required only when dataset='bop'. Supported bop components: goods_balance, services_balance, primary_income, secondary_income, current_account, capital_account, financial_account.

README.md7 KBView on GitHub

FXMacroData Python SDK 🐍📊

Python Versions License

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.

It includes both synchronous and asynchronous clients, supports free USD endpoints, and offers a free Forex Price API for exchange rate data.

🌟 Features

Fetch:
- Macroeconomic indicators — policy rates, inflation, GDP, unemployment, bond yields, and 100+ more
- 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.
Free Forex Price API (get_fx_price).
API key required only for non-USD indicators.
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)

# Free 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)

        # Free 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())

📘 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 (ECB reference 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".
No API key needed.

`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: USD, EUR, GBP, JPY, AUD, CAD, CHF, NZD, HKD, SGD, NOK, PLN, SEK, DKK, BRL, CNY, KRW, MXN.

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

🌐 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

Install

claude_desktop_config.json

{
  "mcpServers": {
    "fxmacrodata": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://fxmacrodata.com/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.