# FxFeed.io > FxFeed.io is a foreign exchange rate API for developers: mid-market rates for 160+ currencies, latest and historical back to 1999, as JSON over HTTPS. It is a hosted API; call it with an API key rather than scraping the website. - API base URL: `https://api.fxfeed.io/v2` - Authentication: pass your API key in the `api_key` query parameter, e.g. `https://api.fxfeed.io/v2/latest?base=USD¤cies=EUR,GBP&api_key=YOUR_API_KEY` - Endpoints: `GET /latest`, `GET /historical?date=YYYY-MM-DD`, `GET /convert?from=USD&to=EUR&amount=100`, `GET /timeseries?start_date=…&end_date=…` - Get a free API key: https://fxfeed.io/signup - Remote MCP server for AI assistants (Streamable HTTP, `Authorization: Bearer YOUR_API_KEY`): https://fxfeed.io/mcp ## Pricing - **Free** ($0 per month): 5,000 requests / month, Daily data - **Pro** ($10 per month or $59 per year): Unlimited requests / month, Hourly data access ## Docs - [API reference](https://fxfeed.io/docs): every endpoint, parameter, response and error code, with code examples - [OpenAPI 3.1 spec](https://fxfeed.io/openapi.json): machine-readable description of the API - [Full reference as Markdown](https://fxfeed.io/llms-full.txt): this file followed by the complete API reference - [Pricing](https://fxfeed.io/pricing): plans and what they include - [Currencies](https://fxfeed.io/currencies): every supported currency, with current and historical rates - [Data methodology](https://fxfeed.io/methodology): where the rates come from and how often they update ## Optional - [Use cases](https://fxfeed.io/use-cases): what teams build with the API - [Blog](https://fxfeed.io/blog): guides on exchange rates and building with currency data - [Terms of Service](https://fxfeed.io/terms) --- # Documentation This document provides detailed information about the FXFeed API, including the available endpoints, query parameters, data format, error handling, and code examples in various programming languages. You can use the FXFeed API to access real-time and historical currency exchange rate data, convert between currencies, and retrieve time series data for currency pairs. We also have an API Playground where you can test the API endpoints and see the responses in real-time. The Playground is available here: [API Playground](/dashboard/playground). ## Base URL The base URL for the API is: ``` https://api.fxfeed.io/v2 ``` ## Authentication To authenticate, provide an `api_key` in the query parameters for all requests. The api_key is required for all requests and can be found in your account settings after signing up. Example: ``` https://api.fxfeed.io/v2/latest?base=EUR&api_key=YOUR_API_KEY ``` ## Data Format The API uses standard JSON for all responses. ## OpenAPI Documentation The API provides OpenAPI 3.0.3 specification for interactive documentation: - **OpenAPI Spec (YAML):** `https://api.fxfeed.io/v2/openapi.yaml` - **OpenAPI Spec (JSON):** `https://api.fxfeed.io/v2/openapi.json` - **Swagger UI:** `https://api.fxfeed.io/v2/docs` An OpenAPI 3.1 description of this reference, for code generators, API clients and AI tools, is published at [https://fxfeed.io/openapi.json](https://fxfeed.io/openapi.json). A plain-text overview for language models is at [https://fxfeed.io/llms.txt](https://fxfeed.io/llms.txt). ## Endpoints ### Latest Currency Data **Endpoint:** `/latest` Provides the latest currency exchange rate data. Free plan users receive rates from the most recent available historical date. **Query Parameters:** - `base` (optional): The base currency symbol (e.g., USD, EUR). Defaults to USD. Also accepts `from` as an alias. - `currencies` (optional): A comma-separated list of currency symbols to retrieve rates for **Example Request:** ``` GET /latest?api_key=YOUR_API_KEY&base=USD¤cies=EUR,GBP,JPY ``` **Example Response:** ```json { "success": true, "base": "USD", "date": "2024-09-02", "rates": { "EUR": 0.85, "GBP": 0.73, "JPY": 110.22 } } ``` ### Historical Currency Data **Endpoint:** `/historical` Provides historical currency exchange rate data for a specific date. **Query Parameters:** - `base` (optional): The base currency symbol (e.g., USD, EUR). Defaults to USD. Also accepts `from` as an alias. - `currencies` (optional): A comma-separated list of currency symbols to retrieve rates for - `date` (optional): The date for historical data in ISO format (YYYY-MM-DD). Defaults to current date if not provided. **Example Request:** ``` GET /historical?api_key=YOUR_API_KEY&base=USD¤cies=EUR,GBP,JPY&date=2023-12-31 ``` **Example Response:** ```json { "success": true, "historical": true, "base": "USD", "date": "2023-12-31", "rates": { "EUR": 0.84, "GBP": 0.74, "JPY": 108.95 } } ``` ### Currency Conversion **Endpoint:** `/convert` Converts an amount from one currency to another, optionally using historical rates. If no date is specified, the latest available rate is used. **Query Parameters:** - `from` (optional): The three-letter currency code to convert from. Defaults to USD. Also accepts `base` as an alias. - `to` (required): The three-letter currency code to convert to - `amount` (required): The amount to be converted (must be greater than 0) - `date` (optional): Specify a date (format YYYY-MM-DD) to use historical rates for this conversion **Example Request:** ``` GET /convert?api_key=YOUR_API_KEY&from=USD&to=EUR&amount=100&date=2024-09-02 ``` **Example Response:** ```json { "success": true, "query": { "from": "USD", "to": "EUR", "amount": 100 }, "info": { "timestamp": 1630540800, "rate": 0.85 }, "date": "2024-09-02", "result": 85.0 } ``` ### Time Series Data **Endpoint:** `/timeseries` Provides exchange rates for each day within a specified date range. **Query Parameters:** - `start_date` (required): The start date of your preferred timeframe (YYYY-MM-DD) - `end_date` (required): The end date of your preferred timeframe (YYYY-MM-DD) - `base` (optional): The three-letter currency code of your preferred base currency. Defaults to USD. Also accepts `from` as an alias. - `currencies` (optional): A comma-separated list of currency codes to limit output currencies **Example Request:** ``` GET /timeseries?api_key=YOUR_API_KEY&start_date=2024-09-01&end_date=2024-09-03&base=USD&symbols=EUR,GBP ``` **Example Response:** ```json { "success": true, "timeseries": true, "start_date": "2024-09-01", "end_date": "2024-09-03", "base": "USD", "rates": { "2024-09-01": { "EUR": 0.85, "GBP": 0.73 }, "2024-09-02": { "EUR": 0.86, "GBP": 0.74 }, "2024-09-03": { "EUR": 0.84, "GBP": 0.72 } } } ``` ## Error Handling The API uses HTTP status codes to indicate the success or failure of a request. Error responses include a JSON object with `success: false` and an `error` object containing a `code` and `info` message. ### List of Possible Errors | HTTP Status | Description | Affected Endpoints | | ----------- | ---------------------------------------------------------------------------------------------- | ------------------ | | 400 | Bad Request: An invalid base currency has been entered | All | | 400 | Bad Request: One or more invalid symbols have been specified | All | | 400 | Bad Request: No date or invalid data has been specified | `historical` | | 400 | Bad Request: No or an invalid amount has been specified | `convert` | | 400 | Bad Request: No or an invalid timeframe has been specified | `timeseries` | | 401 | Authentication failed: Missing or invalid API key | All | | 402 | Payment Required: You have exceeded your monthly limit or your subscription plan is not active | All | | 403 | Access denied: Your plan doesn't include this feature | All | | 404 | Resource or API endpoint not found | All | | 429 | Rate limit exceeded: Please wait a few seconds until retrying | All | ### Example Error Response When you exceed your monthly API request limit: ```json { "success": false, "error": { "code": 402, "info": "Monthly API request limit reached. Please upgrade your plan." } } ``` ## Rate Limiting Please note that API calls may be subject to rate limiting depending on your subscription plan. Consult the API provider for specific details on rate limits for your plan. ## Support For additional support or questions about the API, please contact our support team. ## Use FxFeed from AI assistants FxFeed runs a remote [MCP](https://modelcontextprotocol.io) server, so AI assistants such as Claude, Cursor or VS Code can look up exchange rates for you: ``` https://fxfeed.io/mcp ``` It offers three tools, which mirror the endpoints above: `get_latest_rates` (`base`, `currencies`), `get_historical_rates` (`date`, `base`, `currencies`) and `convert` (`from`, `to`, `amount`, optional `date`). Every call is made with your own API key, sent as `Authorization: Bearer YOUR_API_KEY`, and counts towards your plan like any other request. **Claude Code:** ```bash claude mcp add --transport http fxfeed https://fxfeed.io/mcp --header "Authorization: Bearer YOUR_API_KEY" ``` **Other MCP clients** (Streamable HTTP transport), for example in `.cursor/mcp.json` or your client's MCP configuration: ```json { "mcpServers": { "fxfeed": { "type": "http", "url": "https://fxfeed.io/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` To have an assistant write code against the API instead, point it at the [OpenAPI spec](https://fxfeed.io/openapi.json) or [llms-full.txt](https://fxfeed.io/llms-full.txt). ## Code Examples Here are examples of how to connect to and parse data from the historical endpoint using various programming languages: Note: Replace `YOUR_API_KEY` with your actual API key in all examples. ### JavaScript (using fetch) ```javascript const apiKey = "YOUR_API_KEY" const base = "USD" const currencies = "EUR,GBP,JPY" const date = "2023-12-31" fetch( `https://api.fxfeed.io/v2/historical?api_key=${apiKey}&base=${base}¤cies=${currencies}&date=${date}`, ) .then((response) => response.json()) .then((data) => { if (data.success) { console.log(`Exchange rates for ${data.date}:`) Object.entries(data.rates).forEach(([currency, rate]) => { console.log(`${currency}: ${rate}`) }) } else { console.error("Error:", data.error.info) } }) .catch((error) => console.error("Fetch error:", error)) ``` ### TypeScript (using axios) ```typescript import axios from "axios" interface HistoricalResponse { success: boolean historical: boolean base: string date: string rates: { [key: string]: number } } const apiKey = "YOUR_API_KEY" const base = "USD" const currencies = "EUR,GBP,JPY" const date = "2023-12-31" axios .get("https://api.fxfeed.io/v2/historical", { params: { api_key: apiKey, base, currencies, date }, }) .then((response) => { const data = response.data if (data.success) { console.log(`Exchange rates for ${data.date}:`) Object.entries(data.rates).forEach(([currency, rate]) => { console.log(`${currency}: ${rate}`) }) } }) .catch((error) => console.error("Error:", error.response?.data?.error?.info || error.message), ) ``` ### Go ```go package main import ( "encoding/json" "fmt" "io/ioutil" "net/http" ) type HistoricalResponse struct { Success bool `json:"success"` Historical bool `json:"historical"` Base string `json:"base"` Date string `json:"date"` Rates map[string]float64 `json:"rates"` } func main() { apiKey := "YOUR_API_KEY" base := "USD" currencies := "EUR,GBP,JPY" date := "2023-12-31" url := fmt.Sprintf("https://api.fxfeed.io/v2/historical?api_key=%s&base=%s¤cies=%s&date=%s", apiKey, base, currencies, date) resp, err := http.Get(url) if err != nil { fmt.Println("Error:", err) return } defer resp.Body.Close() body, err := ioutil.ReadAll(resp.Body) if err != nil { fmt.Println("Error reading response:", err) return } var data HistoricalResponse err = json.Unmarshal(body, &data) if err != nil { fmt.Println("Error parsing JSON:", err) return } if data.Success { fmt.Printf("Exchange rates for %s:\n", data.Date) for currency, rate := range data.Rates { fmt.Printf("%s: %.2f\n", currency, rate) } } else { fmt.Println("Error: Unable to fetch exchange rates") } } ``` ### Python (using requests) ```python import requests api_key = 'YOUR_API_KEY' base = 'USD' currencies = 'EUR,GBP,JPY' date = '2023-12-31' url = f'https://api.fxfeed.io/v2/historical?api_key={api_key}&base={base}¤cies={currencies}&date={date}' response = requests.get(url) data = response.json() if data['success']: print(f"Exchange rates for {data['date']}:") for currency, rate in data['rates'].items(): print(f"{currency}: {rate}") else: print("Error:", data['error']['info']) ``` ### Java (using java.net.HttpClient) ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import org.json.JSONObject; public class HistoricalRates { public static void main(String[] args) { String apiKey = "YOUR_API_KEY"; String base = "USD"; String currencies = "EUR,GBP,JPY"; String date = "2023-12-31"; String url = String.format("https://api.fxfeed.io/v2/historical?api_key=%s&base=%s¤cies=%s&date=%s", apiKey, base, currencies, date); HttpClient client = HttpClient.newHttpClient(); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create(url)) .build(); try { HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString()); JSONObject data = new JSONObject(response.body()); if (data.getBoolean("success")) { System.out.println("Exchange rates for " + data.getString("date") + ":"); JSONObject rates = data.getJSONObject("rates"); for (String currency : rates.keySet()) { System.out.println(currency + ": " + rates.getDouble(currency)); } } else { System.out.println("Error: " + data.getJSONObject("error").getString("info")); } } catch (Exception e) { System.out.println("Error: " + e.getMessage()); } } } ``` ### C# (using System.Net.Http) ```csharp using System; using System.Net.Http; using System.Threading.Tasks; using Newtonsoft.Json.Linq; class Program { static async Task Main(string[] args) { string apiKey = "YOUR_API_KEY"; string baseC = "USD"; string currencies = "EUR,GBP,JPY"; string date = "2023-12-31"; string url = $"https://api.fxfeed.io/v2/historical?api_key={apiKey}&base={baseC}¤cies={currencies}&date={date}"; using (var client = new HttpClient()) { try { string response = await client.GetStringAsync(url); var data = JObject.Parse(response); if (data["success"].Value()) { Console.WriteLine($"Exchange rates for {data["date"]}:"); foreach (var rate in data["rates"]) { Console.WriteLine($"{rate.Path}: {rate.Value()}"); } } else { Console.WriteLine($"Error: {data["error"]["info"]}"); } } catch (Exception e) { Console.WriteLine($"Error: {e.Message}"); } } } } ``` ### cURL ```bash curl -X GET "https://api.fxfeed.io/v2/historical?api_key=YOUR_API_KEY&base=USD¤cies=EUR,GBP,JPY&date=2023-12-31" ``` Note: Replace `YOUR_API_KEY` with your actual API key in all examples.