Skip to content

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.

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. A plain-text overview for language models is at 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&currencies=EUR,GBP,JPY

Example Response:

{
  "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&currencies=EUR,GBP,JPY&date=2023-12-31

Example Response:

{
  "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:

{
  "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:

{
  "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:

{
  "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 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:

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:

{
  "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 or 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)

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}&currencies=${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)

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<HistoricalResponse>("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

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&currencies=%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)

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}&currencies={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)

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&currencies=%s&date=%s",
                apiKey, base, currencies, date);

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .build();

        try {
            HttpResponse<String> 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)

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}&currencies={currencies}&date={date}";

        using (var client = new HttpClient())
        {
            try
            {
                string response = await client.GetStringAsync(url);
                var data = JObject.Parse(response);

                if (data["success"].Value<bool>())
                {
                    Console.WriteLine($"Exchange rates for {data["date"]}:");
                    foreach (var rate in data["rates"])
                    {
                        Console.WriteLine($"{rate.Path}: {rate.Value<double>()}");
                    }
                }
                else
                {
                    Console.WriteLine($"Error: {data["error"]["info"]}");
                }
            }
            catch (Exception e)
            {
                Console.WriteLine($"Error: {e.Message}");
            }
        }
    }
}

cURL

curl -X GET "https://api.fxfeed.io/v2/historical?api_key=YOUR_API_KEY&base=USD&currencies=EUR,GBP,JPY&date=2023-12-31"

Note: Replace YOUR_API_KEY with your actual API key in all examples.