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 Playgound 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

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.

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.

Introduction

API Endpoints

Code Examples

Documentation

Base URL

Authentication

Data Format

OpenAPI Documentation

Endpoints

Latest Currency Data

Historical Currency Data

Currency Conversion

Time Series Data

Error Handling

List of Possible Errors

Example Error Response

Rate Limiting

Support

Code Examples

JavaScript (using fetch)

TypeScript (using axios)

Go

Python (using requests)

Java (using java.net.HttpClient)

C# (using System.Net.Http)

cURL