CurrencyCore
Live FX rates, conversion, IMF PPP, and historical currency analytics.
Should I use this
Quality & Safety
Based on automated analysis of tool definitions and protocol compliance.
Context Cost
This is the approximate number of tokens consumed each time the server's tools are loaded into a model's context. Higher counts reduce the attention available for other tasks.
Install
One-Click Install
Add this to your `claude_desktop_config.json` file:
{
"mcpServers": {
"currency-core-mcp": {
"url": "https://mcp.currency-core.com/mcp"
}
}
}Remote endpoints
https://mcp.currency-core.com/mcpstreamable-httpWhat it can do
Tool inventory
Tools (14)
🟢list_countries
Return the supported countries and their official currencies as an array of `{ code, name, currencies }`. Use to resolve a country name to its ISO alpha-3 code before `get_ppp_factor` or `analyze_ppp`, or to check which countries are covered. Use `list_currencies` for currency codes. Returns the full list in one call and takes no parameters. Public tool: no sign-in and no API request billed.
Input Schema
{
"type": "object",
"properties": {},
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢list_currencies
Return the full ISO 4217 currency catalogue as an array of `{ code, numeric, name, symbol }`. Use to resolve a currency name or symbol to its code, or to confirm a currency is supported before calling another tool, so a typo fails at selection rather than silently. Use `list_countries` for country codes. Non-ISO codes CNH, GGP, IMP, and JEP have an empty `numeric`. Returns the full list in one call and takes no parameters. Public tool: no sign-in and no API request billed.
Input Schema
{
"type": "object",
"properties": {},
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢convert(from, to, amount, ppp, date)
Convert an amount from one currency to one or more targets at the reference rate for `date`, optionally PPP-adjusted. Use for any single-pair or amount conversion (for example "100 USD to EUR"). Use `get_rates`/`get_rates_by_base` for a full rate table, `get_history` for a series, and the `analyze_*` tools for statistics. `amount` defaults to 1 (each result then equals the rate); `ppp=true` applies purchasing-power parity and needs `CUR:COUNTRY` when a currency is used in more than one country; `date` must be today or earlier and defaults to the latest rate date. Returns `{ from, amount, date, results[] }`, each result carrying `result`, `rate`, and an optional `ppp` block. Invalid codes or dates return a 4xx error; no rate for the date is a 404. Requires a signed-in connection; each successful call bills 1 API request.
Input Schema
{
"type": "object",
"properties": {
"from": {
"type": "string",
"description": "Source currency (ISO 4217), e.g. USD. For PPP (ppp=true), pass CUR:COUNTRY (e.g. USD:USA) when the currency is used in more than one country; common currencies are resolved automatically."
},
"to": {
"type": "string",
"description": "One or more target currencies, comma-separated, e.g. EUR,INR (max 25). For PPP, pass CUR:COUNTRY pairs (e.g. EUR:DEU,INR:IND) when a currency is used in more than one country; common currencies are resolved automatically."
},
"amount": {
"type": "number",
"description": "Amount to convert. Optional, defaults to 1 (so each result equals the rate). When provided it must be a finite positive number."
},
"ppp": {
"type": "boolean",
"description": "When true, apply a PPP adjustment. Pass CUR:COUNTRY for currencies used in more than one country; common currencies (USD, EUR, INR and others) resolve automatically."
},
"date": {
"type": "string",
"description": "Rate date in YYYY-MM-DD (UTC). Must not be in the future. Defaults to latest."
}
},
"required": [
"from",
"to"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Output Schema
{
"type": "object",
"properties": {
"from": {
"type": "string"
},
"fromCountry": {
"type": "string"
},
"amount": {
"type": "number"
},
"date": {
"type": "string"
},
"requestedDate": {
"type": "string"
},
"asOf": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"to": {
"type": "string"
},
"toCountry": {
"type": "string"
},
"result": {
"type": "number"
},
"rate": {
"type": "number"
},
"ppp": {
"anyOf": [
{
"type": "object",
"properties": {
"fromFactor": {
"type": "number"
},
"toFactor": {
"type": "number"
},
"result": {
"type": "number"
},
"year": {
"type": "number"
},
"source": {
"type": "string"
}
},
"required": [
"fromFactor",
"toFactor",
"result",
"year",
"source"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"error": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
]
}
},
"required": [
"to",
"result",
"rate"
],
"additionalProperties": false
}
},
"message": {
"type": "string"
}
},
"required": [
"from",
"amount",
"date",
"results"
],
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false
}🟢get_rates(date)
Return the full USD-based exchange-rate snapshot for one date: `rates` maps every supported currency to units per 1 USD. Use when the user wants a multi-currency table in USD (for example "today's rates"). Use `get_rates_by_base` for a non-USD base, `convert` for one pair or amount, and `get_history` for a time series. Omitting `date` returns the latest available snapshot, which is not necessarily today. Returns `{ base: "USD", date, rates }`; a date with no snapshot is a 404. Requires a signed-in connection; each successful call bills 1 API request.
Input Schema
{
"type": "object",
"properties": {
"date": {
"type": "string",
"description": "YYYY-MM-DD. Defaults to the latest available date."
}
},
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Output Schema
{
"type": "object",
"properties": {
"date": {
"type": "string"
},
"base": {
"type": "string",
"const": "USD"
},
"rates": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
},
"requestedDate": {
"type": "string"
},
"asOf": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
"required": [
"date",
"base",
"rates"
],
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false
}🟢get_rates_by_base(base, date)
Return the daily FX snapshot re-based to `base`: every supported currency quoted as units per 1 unit of `base`, with `base` itself at 1. Use when the user wants a multi-currency table in a non-USD base (for example "rates in EUR"). Use `get_rates` for the USD table, `convert` for one pair or amount, and `get_history` for a time series. Omitting `date` returns the latest available snapshot, which is not necessarily today. Returns `{ base, date, rates }`; an unsupported base or a date with no snapshot is a 404. Requires a signed-in connection; each successful call bills 1 API request.
Input Schema
{
"type": "object",
"properties": {
"base": {
"type": "string",
"description": "Base currency (3-letter ISO 4217), e.g. EUR."
},
"date": {
"type": "string",
"description": "YYYY-MM-DD. Defaults to the latest available date."
}
},
"required": [
"base"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Output Schema
{
"type": "object",
"properties": {
"base": {
"type": "string"
},
"date": {
"type": "string"
},
"requestedDate": {
"type": "string"
},
"asOf": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"rates": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
},
"ppp": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"year": {
"type": "number"
},
"values": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
}
},
"required": [
"base",
"year",
"values"
],
"additionalProperties": false
}
},
"required": [
"base",
"date",
"rates"
],
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false
}🟢get_history(currency, from, to, base, interval)
Return one currency's rate series over a date range, expressed against `base`: `rates` maps each date (or aggregated period) to units of `currency` per 1 `base`. Use for a line chart or raw daily/weekly/monthly/yearly points for one currency. Use `analyze_history` for computed change, trend, and movers; use `convert` or `get_rates` for a single value or snapshot. Defaults: `to` today, `from` 7 days earlier, `base` USD, `interval` daily; coarser intervals average the daily rates per bucket. Returns `{ currency, base, interval, from, to, rates }`. Free plans are limited to the last 30 days; an invalid code or missing history is a 404. Requires a signed-in connection; each successful call bills 1 API request.
Input Schema
{
"type": "object",
"properties": {
"currency": {
"type": "string",
"description": "The currency whose history to fetch (3-letter ISO 4217), e.g. INR. One currency per call."
},
"from": {
"type": "string",
"description": "Start date YYYY-MM-DD (UTC). Defaults to 7 days before `to`."
},
"to": {
"type": "string",
"description": "End date YYYY-MM-DD (UTC). Defaults to today; a future date clamps to today."
},
"base": {
"type": "string",
"description": "Base currency the rates are expressed against (3-letter ISO 4217). Defaults to USD."
},
"interval": {
"type": "string",
"enum": [
"daily",
"weekly",
"monthly",
"yearly"
],
"description": "Aggregation: daily (default), weekly, monthly, or yearly. Coarser intervals average the daily rates per bucket (weekly key = the week's Monday, monthly = YYYY-MM, yearly = YYYY)."
}
},
"required": [
"currency"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Output Schema
{
"type": "object",
"properties": {
"currency": {
"type": "string"
},
"base": {
"type": "string"
},
"interval": {
"type": "string",
"enum": [
"daily",
"weekly",
"monthly",
"yearly"
]
},
"from": {
"type": "string"
},
"to": {
"type": "string"
},
"rates": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
}
},
"required": [
"currency",
"base",
"interval",
"from",
"to",
"rates"
],
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false
}🟢analyze_history(base, currencies, from, to, period, ...)
Summarise how currencies moved against `base` over a window: start/end rate, change %, strengthened % (positive = stronger vs base), and optional min/max/avg. Use for questions like "how did EUR do over 10 years" and for movers rankings. Omit `currencies` to rank the universe (movers mode); provide them to compare specific ones. Use `get_history` for raw points, and the other `analyze_*` tools for volatility, correlation, drawdown, safe-haven, or mean-reversion questions. Defaults: 20-year window, `base` USD, `sort` strengthened, `assetClass` fiat, `limit` 10, `stats` true. Returns `{ base, from, to, mode, sort?, assetClass?, stats, results[] }`. A 404 means no rate data at the window edges. Requires a signed-in connection and the Growth plan or higher; each successful call bills 1 API request.
Input Schema
{
"type": "object",
"properties": {
"base": {
"type": "string",
"description": "Currency everything is measured against (3-letter ISO 4217). Defaults to USD."
},
"currencies": {
"type": "string",
"description": "Comma-separated currencies to compare, e.g. GBP,EUR,AED. OMIT to rank ALL currencies vs base ('movers' mode)."
},
"from": {
"type": "string",
"description": "Window start YYYY-MM-DD (UTC). Defaults to 20 years (2 decades) before `to`. See `period` for a shorthand."
},
"to": {
"type": "string",
"description": "Window end YYYY-MM-DD (UTC). Defaults to today; a future date clamps to today."
},
"period": {
"type": "string",
"description": "Relative window shorthand for `from`: e.g. 10y, 6m, 30d, ytd, max. Ignored if `from` is given."
},
"sort": {
"type": "string",
"enum": [
"strengthened",
"weakened"
],
"description": "Movers ranking: strengthened (default) or weakened."
},
"assetClass": {
"type": "string",
"enum": [
"fiat",
"metals",
"all",
"crypto"
],
"description": "Movers universe: fiat (default, liquid tradeable currencies), metals (XAU/XAG/XPT/XPD), all (every currency including illiquid/frontier), or crypto (accepted, but this FX dataset has no crypto data, so results are empty). Redenomination artifacts are always dropped."
},
"limit": {
"type": "number",
"description": "Movers: how many top results to return (default 10, max 200)."
},
"interval": {
"type": "string",
"enum": [
"daily",
"weekly",
"monthly",
"yearly"
],
"description": "Attach a trend series per named currency: weekly, monthly, or yearly (compare mode only)."
},
"stats": {
"type": "boolean",
"description": "Include min/max/avg over the window per currency. Defaults to true; pass false to skip."
}
},
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Output Schema
{
"type": "object",
"properties": {
"base": {
"type": "string"
},
"from": {
"type": "string"
},
"to": {
"type": "string"
},
"mode": {
"type": "string",
"enum": [
"compare",
"movers"
]
},
"sort": {
"type": "string",
"enum": [
"strengthened",
"weakened"
]
},
"assetClass": {
"type": "string",
"enum": [
"fiat",
"metals",
"all",
"crypto"
]
},
"interval": {
"type": "string",
"enum": [
"daily",
"weekly",
"monthly",
"yearly"
]
},
"stats": {
"type": "boolean"
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"currency": {
"type": "string"
},
"startDate": {
"type": "string"
},
"endDate": {
"type": "string"
},
"startRate": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"endRate": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"changePct": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"strengthenedPct": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"stats": {
"type": "object",
"properties": {
"min": {
"type": "number"
},
"max": {
"type": "number"
},
"avg": {
"type": "number"
}
},
"required": [
"min",
"max",
"avg"
],
"additionalProperties": false
},
"series": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
},
"volatility": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"note": {
"type": "string"
}
},
"required": [
"currency",
"startDate",
"endDate",
"startRate",
"endRate",
"changePct",
"strengthenedPct"
],
"additionalProperties": false
}
}
},
"required": [
"base",
"from",
"to",
"mode",
"stats",
"results"
],
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false
}🟢get_ppp_factor(country, year)
Return the IMF World Economic Outlook PPP conversion factor for one country and year: local currency units per international dollar. Use when the user needs the raw multiplier for one country/year, for example a cost-of-living comparison. Use `convert` with `ppp=true` to price an amount, and `analyze_ppp` for change over time or a cross-country ranking. `year` defaults to the latest configured PPP year (2024). Returns `{ year, countryCode, pppFactor, projected }`; `projected: true` marks an IMF projection rather than observed data. An unknown country or year is a 404. Requires a signed-in connection; each successful call bills 1 API request.
Input Schema
{
"type": "object",
"properties": {
"country": {
"type": "string",
"description": "Country as an ISO 3166-1 alpha-3 code (e.g. IND)."
},
"year": {
"type": "number",
"description": "Four-digit year. Defaults to the configured current PPP year (2024)."
}
},
"required": [
"country"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Output Schema
{
"type": "object",
"properties": {
"year": {
"type": "number"
},
"countryCode": {
"type": "string"
},
"pppFactor": {
"type": "number"
},
"projected": {
"type": "boolean"
}
},
"required": [
"year",
"countryCode",
"pppFactor",
"projected"
],
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false
}🟢analyze_ppp(countries, from, to, period, sort, ...)
Measure how a country's IMF PPP conversion factor changed over a year window: start/end year and factor, % change, and optional min/max/avg. Use for purchasing-power trends and cross-country PPP rankings. Omit `countries` to rank all countries (movers); provide ISO alpha-3 codes to compare specific ones. Use `get_ppp_factor` for a single country/year value, and `convert` with `ppp=true` to price an amount. Defaults: 10-year window, `sort` increased, `limit` 10, `stats` true. Returns `{ from, to, mode, stats, results[] }`, with `projected: true` marking an IMF projection. Returns an error when no PPP data exists in the window. Requires a signed-in connection and the Growth plan or higher; each successful call bills 1 API request.
Input Schema
{
"type": "object",
"properties": {
"countries": {
"type": "string",
"description": "Comma-separated ISO 3166-1 alpha-3 country codes to compare, e.g. IND,DEU,USA. OMIT to rank ALL countries by PPP-factor change ('movers' mode)."
},
"from": {
"type": "string",
"description": "Window start YEAR (e.g. 2015). Defaults to 10 years before `to`. See `period` for a shorthand."
},
"to": {
"type": "string",
"description": "Window end YEAR (e.g. 2024). Defaults to the current year."
},
"period": {
"type": "string",
"description": "Relative window shorthand for `from`: e.g. 10y, 20y, max. Ignored if `from` is given."
},
"sort": {
"type": "string",
"enum": [
"increased",
"decreased"
],
"description": "Movers ranking: increased (PPP factor rose most, default) or decreased."
},
"limit": {
"type": "number",
"description": "Movers: how many top results to return (default 10, max 200)."
},
"stats": {
"type": "boolean",
"description": "Include min/max/avg of the PPP factor over the window per country. Defaults to true; pass false to skip."
}
},
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Output Schema
{
"type": "object",
"properties": {
"from": {
"type": "number"
},
"to": {
"type": "number"
},
"mode": {
"type": "string",
"enum": [
"compare",
"movers"
]
},
"sort": {
"type": "string",
"enum": [
"increased",
"decreased"
]
},
"stats": {
"type": "boolean"
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"country": {
"type": "string"
},
"startYear": {
"type": "number"
},
"endYear": {
"type": "number"
},
"startFactor": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"endFactor": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"changePct": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"projected": {
"type": "boolean"
},
"stats": {
"type": "object",
"properties": {
"min": {
"type": "number"
},
"max": {
"type": "number"
},
"avg": {
"type": "number"
}
},
"required": [
"min",
"max",
"avg"
],
"additionalProperties": false
},
"series": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
},
"note": {
"type": "string"
}
},
"required": [
"country",
"startYear",
"endYear",
"startFactor",
"endFactor",
"changePct",
"projected"
],
"additionalProperties": false
}
}
},
"required": [
"from",
"to",
"mode",
"stats",
"results"
],
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false
}🟢analyze_volatility(currency, base, from, to, sort, ...)
Return annualized volatility (%) for each currency against `base`, with the number of daily returns used. Use to rank stability or find the most volatile currency or pair. Omit `currency` to rank the universe (`sort` stable or volatile); provide one currency or a comma-separated list to compare. Use `analyze_drawdown` for worst peak-to-trough loss and `analyze_safe_haven` for crisis resilience. Defaults: 365-day window, `base` USD, `sort` stable, `universe` liquid, `limit` 10. Returns `{ base, from, to, mode, basis, results[] }`; `volatility` is null when there is too little data. Requires a signed-in connection and the Growth plan or higher; each successful call bills 1 API request.
Input Schema
{
"type": "object",
"properties": {
"currency": {
"type": "string",
"description": "Currency to measure (3-letter ISO 4217), or a comma-separated list to compare. OMIT to RANK the liquid-currency set by stability."
},
"base": {
"type": "string",
"description": "Base currency to measure against (3-letter ISO 4217). Defaults to USD."
},
"from": {
"type": "string",
"description": "Window start YYYY-MM-DD (UTC). Defaults to 365 days before `to`."
},
"to": {
"type": "string",
"description": "Window end YYYY-MM-DD (UTC). Defaults to today; a future date clamps to today."
},
"sort": {
"type": "string",
"enum": [
"stable",
"volatile"
],
"description": "Ranking direction: stable (least volatile first, default) or volatile."
},
"universe": {
"type": "string",
"enum": [
"liquid",
"majors"
],
"description": "Ranking universe: liquid (default, broad set) or majors (USD/EUR/GBP/JPY/CHF/CAD/AUD/NZD). Use majors for 'most volatile major pair'."
},
"limit": {
"type": "number",
"description": "Ranking: how many to return (default 10, max 50)."
}
},
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Output Schema
{
"type": "object",
"properties": {
"base": {
"type": "string"
},
"from": {
"type": "string"
},
"to": {
"type": "string"
},
"mode": {
"type": "string",
"enum": [
"compare",
"ranking"
]
},
"sort": {
"type": "string",
"enum": [
"stable",
"volatile"
]
},
"universe": {
"type": "string",
"enum": [
"liquid",
"majors"
]
},
"basis": {
"type": "string",
"const": "annualized-daily"
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"currency": {
"type": "string"
},
"volatility": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"observations": {
"type": "number"
},
"note": {
"type": "string"
}
},
"required": [
"currency",
"volatility",
"observations"
],
"additionalProperties": false
}
}
},
"required": [
"base",
"from",
"to",
"mode",
"basis",
"results"
],
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false
}🟢analyze_correlation(base, currencies, from, to)
Return the Pearson correlation of each currency's daily returns with `base` over a window (−1..1), plus the number of overlapping observations. Use for diversification or co-movement questions such as "does CHF track EUR?". `currencies` is required and comma-separated; a non-USD `base` is usually more meaningful. Use `analyze_volatility` for dispersion and `analyze_history` for raw change. Defaults: 365-day window ending today. Returns `{ base, from, to, results[] }`; `correlation` is null when it is undefined for the window. Requires a signed-in connection and the Growth plan or higher; each successful call bills 1 API request.
Input Schema
{
"type": "object",
"properties": {
"base": {
"type": "string",
"description": "Reference currency to correlate against (3-letter ISO 4217). Defaults to USD (a non-USD base is more meaningful)."
},
"currencies": {
"type": "string",
"description": "Comma-separated currencies to correlate with `base`, e.g. GBP,CHF,SEK."
},
"from": {
"type": "string",
"description": "Window start YYYY-MM-DD (UTC). Defaults to 365 days before `to`."
},
"to": {
"type": "string",
"description": "Window end YYYY-MM-DD (UTC). Defaults to today."
}
},
"required": [
"currencies"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Output Schema
{
"type": "object",
"properties": {
"base": {
"type": "string"
},
"from": {
"type": "string"
},
"to": {
"type": "string"
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"currency": {
"type": "string"
},
"correlation": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"observations": {
"type": "number"
},
"note": {
"type": "string"
}
},
"required": [
"currency",
"correlation",
"observations"
],
"additionalProperties": false
}
}
},
"required": [
"base",
"from",
"to",
"results"
],
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false
}🟢analyze_drawdown(currency, base, from, to, sort, ...)
Return the worst peak-to-trough decline of each currency vs `base`, with peak, trough, and recovery dates/days. Use for "how far did it fall and did it recover" questions or to rank the deepest drawdowns. Omit `currency` to rank the universe (`sort` deepest or recovery); provide one currency or a list to compare. Use `analyze_volatility` for dispersion and `analyze_safe_haven` for crisis behaviour. Defaults: 365-day window, `base` USD, `sort` deepest, `universe` liquid, `limit` 10. Returns `{ base, from, to, mode, results[] }`; peak/trough dates are omitted and recovery fields are null when there is no drawdown or recovery in the window. Requires a signed-in connection and the Growth plan or higher; each successful call bills 1 API request.
Input Schema
{
"type": "object",
"properties": {
"currency": {
"type": "string",
"description": "Currency to measure (3-letter ISO 4217), or a comma-separated list. OMIT to RANK the liquid set by drawdown."
},
"base": {
"type": "string",
"description": "Base currency to measure against (3-letter ISO 4217). Defaults to USD."
},
"from": {
"type": "string",
"description": "Window start YYYY-MM-DD (UTC). Defaults to 365 days before `to`."
},
"to": {
"type": "string",
"description": "Window end YYYY-MM-DD (UTC). Defaults to today."
},
"sort": {
"type": "string",
"enum": [
"deepest",
"recovery"
],
"description": "Ranking direction: deepest (largest decline first, default) or recovery (fastest recovery first)."
},
"universe": {
"type": "string",
"enum": [
"liquid",
"majors"
],
"description": "Ranking universe: liquid (default) or majors."
},
"limit": {
"type": "number",
"description": "Ranking: how many to return (default 10, max 50)."
}
},
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Output Schema
{
"type": "object",
"properties": {
"base": {
"type": "string"
},
"from": {
"type": "string"
},
"to": {
"type": "string"
},
"mode": {
"type": "string",
"enum": [
"compare",
"ranking"
]
},
"sort": {
"type": "string",
"enum": [
"deepest",
"recovery"
]
},
"universe": {
"type": "string",
"enum": [
"liquid",
"majors"
]
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"currency": {
"type": "string"
},
"maxDrawdownPct": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"peakDate": {
"type": "string"
},
"troughDate": {
"type": "string"
},
"recoveryDate": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"recoveryDays": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"note": {
"type": "string"
}
},
"required": [
"currency",
"maxDrawdownPct"
],
"additionalProperties": false
}
}
},
"required": [
"base",
"from",
"to",
"mode",
"results"
],
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false
}🟢analyze_safe_haven(currencies, base, from, to, limit)
Rank currencies by a 0–100 safe-haven score that combines low volatility, shallow drawdown, and 2008-crisis resilience. Use for "which currency holds up in a crisis" questions. Provide `currencies` to score specific codes, or omit to rank the liquid-fiat pool. Precious metals are not supported. Use `analyze_volatility` for pure dispersion and `analyze_drawdown` for peak-to-trough loss. Defaults: window from 2007-01-01 (or 20 years before `to`), `base` USD, `limit` 10. Returns `{ base, from, to, crisis, results[] }`. Returns an error when no rate data is available for the window. Requires a signed-in connection and the Growth plan or higher; each successful call bills 1 API request.
Input Schema
{
"type": "object",
"properties": {
"currencies": {
"type": "string",
"description": "Comma-separated currencies to score, e.g. CHF,JPY. OMIT to rank the liquid-fiat safe-haven pool (precious metals are not supported)."
},
"base": {
"type": "string",
"description": "Base currency to measure against (3-letter ISO 4217). Defaults to USD."
},
"from": {
"type": "string",
"description": "Window start YYYY-MM-DD (UTC). Defaults to 2007-01-01 (spans the 2008 crisis + COVID), or to 20 years before `to` when that is later."
},
"to": {
"type": "string",
"description": "Window end YYYY-MM-DD (UTC). Defaults to today."
},
"limit": {
"type": "number",
"description": "How many to return (default 10, max 50)."
}
},
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Output Schema
{
"type": "object",
"properties": {
"base": {
"type": "string"
},
"from": {
"type": "string"
},
"to": {
"type": "string"
},
"crisis": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"from": {
"type": "string"
},
"to": {
"type": "string"
}
},
"required": [
"label",
"from",
"to"
],
"additionalProperties": false
},
"universe": {
"type": "string",
"enum": [
"liquid",
"majors"
]
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"currency": {
"type": "string"
},
"score": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"volatility": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"maxDrawdownPct": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"crisisReturnPct": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"note": {
"type": "string"
}
},
"required": [
"currency",
"score",
"volatility",
"maxDrawdownPct",
"crisisReturnPct"
],
"additionalProperties": false
}
}
},
"required": [
"base",
"from",
"to",
"crisis",
"results"
],
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false
}🟢analyze_mean_reversion(currencies, base, from, to, limit)
Rank currencies by how strongly they revert to their historical mean, using a composite 0–100 score (crossing frequency + reversion half-life), plus current deviation and half-life in days. Use for questions like "does EUR snap back to its average". Provide `currencies` to score specific codes, or omit to rank the liquid set. Use `analyze_history` for raw change and `analyze_volatility` for dispersion. Defaults: roughly a 2-year window, `base` USD, `limit` 10. Returns `{ base, from, to, results[] }`; `score` and `halfLifeDays` are null when there is not enough reverting data. Requires a signed-in connection and the Growth plan or higher; each successful call bills 1 API request.
Input Schema
{
"type": "object",
"properties": {
"currencies": {
"type": "string",
"description": "Comma-separated currencies to score, e.g. EUR,GBP. OMIT to rank the liquid set."
},
"base": {
"type": "string",
"description": "Base currency to measure against (3-letter ISO 4217). Defaults to USD."
},
"from": {
"type": "string",
"description": "Window start YYYY-MM-DD (UTC). Defaults to ~2 years before `to`."
},
"to": {
"type": "string",
"description": "Window end YYYY-MM-DD (UTC). Defaults to today."
},
"limit": {
"type": "number",
"description": "How many to return (default 10, max 50)."
}
},
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Output Schema
{
"type": "object",
"properties": {
"base": {
"type": "string"
},
"from": {
"type": "string"
},
"to": {
"type": "string"
},
"universe": {
"type": "string",
"enum": [
"liquid",
"majors"
]
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"currency": {
"type": "string"
},
"score": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"deviationPct": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"reversionFrequency": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"halfLifeDays": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"note": {
"type": "string"
}
},
"required": [
"currency",
"score",
"deviationPct",
"reversionFrequency",
"halfLifeDays"
],
"additionalProperties": false
}
}
},
"required": [
"base",
"from",
"to",
"results"
],
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false
}Community
Evidence