{ "openapi": "3.1.1", "info": { "title": "Currency Converter API", "version": "1.0.0", "summary": "Convert an amount into several currencies at ECB euro reference rates, with rate date and source.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://currencyconverter.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Convert an amount into several currencies at ECB euro reference rates, with rate date and source.", "description": "Converts an amount between the 30 currencies of the European Central Bank’s daily euro foreign exchange reference rates – into several target currencies at once, at the latest rates or those of a past date. Cross rates are calculated via the euro; every result shows the rate, the inverse rate, the reference date and the source.\n\nMethodology:\n- Rates come from the ECB’s daily reference-rate file (eurofxref-daily.xml) or, for past dates, from the ECB Data Portal (dataset EXR, daily series D..EUR.SP00.A). They are cached per day; the daily file is re-checked at most hourly until the day’s rates (around 16:00 CET) are available.\n- All ECB rates are quoted as units of currency per 1 euro, so a cross rate is rate(to) ÷ rate(from); converting X from A to B = X × rate(B) ÷ rate(A). Rates are shown with 6 significant digits; amounts are rounded half away from zero to the currency’s minor units (0 for JPY, KRW and ISK).\n- For a date without a publication (weekends, TARGET holidays) the last earlier publication is used and named.\n- Reference rates are published for information only. Card schemes, banks and exchange offices use their own rates and add fees, so the amount you actually pay or receive will differ.\n\nECB reference rates are not transaction rates. For a real payment, check your provider’s rate and fees.", "tags": [ "money" ], "x-mcp-tool": "currency_converter", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrencyConverterInput" }, "examples": { "example1": { "summary": "100 EUR into USD, GBP, CHF and JPY (latest)", "value": { "amount": 100, "from": "EUR", "to": "USD, GBP, CHF, JPY" } }, "example2": { "summary": "250 USD into EUR and GBP on 2024-01-02", "value": { "amount": 250, "from": "USD", "to": "EUR, GBP", "date": "2024-01-02" } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrencyConverterResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "CurrencyConverterInput": { "type": "object", "additionalProperties": false, "properties": { "amount": { "title": "Amount", "type": "number", "minimum": 0, "maximum": 1000000000000000, "default": 100 }, "from": { "title": "From currency", "description": "ISO code, e.g. EUR, USD, GBP, CHF, JPY.", "type": "string", "maxLength": 3, "default": "EUR" }, "to": { "title": "To currencies", "description": "One or more ISO codes, comma-separated, or \"all\".", "type": "string", "maxLength": 200, "default": "USD, GBP, CHF, JPY" }, "date": { "title": "Rate date", "description": "Optional: use the reference rates of this date (the last publication on or before it). Empty: latest rates.", "type": "string", "format": "date" } }, "required": [ "amount", "from", "to" ] }, "CurrencyConverterResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "additionalProperties": false, "required": [ "amount", "from", "rates", "conversions" ], "properties": { "amount": { "type": "number" }, "from": { "type": "string" }, "rates": { "type": "object", "additionalProperties": false, "required": [ "date", "source", "url", "fetchedAt", "stale" ], "properties": { "date": { "type": "string", "description": "Reference date of the rates." }, "requestedDate": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "ecb-daily", "ecb-sdmx", "manual" ] }, "url": { "type": [ "string", "null" ] }, "fetchedAt": { "type": [ "string", "null" ] }, "stale": { "type": "boolean" } } }, "conversions": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "currency", "name", "rate", "inverseRate", "amount", "rounded" ], "properties": { "currency": { "type": "string" }, "name": { "type": "string" }, "rate": { "type": "number", "description": "Units of the target currency per 1 unit of the source currency." }, "inverseRate": { "type": "number" }, "amount": { "type": "number" }, "rounded": { "type": "number", "description": "Rounded to the currency’s minor units." } } } } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }