REST API v1

API Documentation

Integrate real-time, reliable forex and cryptocurrency data into your applications.

Get your API key Code samples

Version 1.0.0 99.99% Uptime

Introduction

Welcome to the CurrencyBeacon API documentation. We provide a simple yet powerful RESTful interface for accessing real-time and historical exchange rates for over 160 world currencies and more than 2,000 cryptocurrencies.

Why use CurrencyBeacon?

Our API is built for developers who need accuracy and reliability. We aggregate data from multiple commercial sources and banks to ensure our rates are precise. Whether you are building a fintech application, an e-commerce store, or an investment dashboard, our API delivers the data you need in a lightweight JSON format.

Spot Exchange Rates: Real-time data updated every minute.
Historical Data: Access rates dating back to 1996.
Bank-Level Security: All endpoints are secured via 256-bit SSL encryption.

Authentication

CurrencyBeacon uses API keys to allow access to the API. You can register a new API key at our developer portal. Authentication is required for all API requests.

Security Best Practice. Your API key carries specific privileges. Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, or front-end JavaScript. If you believe your key has been compromised, rotate it immediately in your dashboard.

Passing the API Key

We support two methods for passing your API key. We recommend using the Query Parameter method for simplicity during development, but the HTTP Header method is cleaner for production applications.

1 Query Parameter Easiest

Simply append the api_key parameter to any request URL.

Request URL

https://api.currencybeacon.com/v1/latest?api_key=YOUR_ACCESS_KEY

2 Authorization Header Recommended

Pass the key as a Bearer token in the request header.

HTTP

GET /v1/latest HTTP/1.1
Host: api.currencybeacon.com
Authorization: Bearer YOUR_ACCESS_KEY

Base URL

All API requests should be made to this base URL:

Base URL

https://api.currencybeacon.com/v1

HTTPS is required for all requests.

API Endpoints

Five endpoints cover latest and historical rates, conversion, time-series data, and the list of supported currencies. Every request needs your API key.

GET/latest

Latest Exchange Rates

Returns real-time exchange rate data for all available currencies. The data is updated based on your subscription plan frequency (e.g., every 60 seconds).

Request Parameters

Key	Type	Description
`base`	Required	The three-letter currency code of your preferred base currency (e.g., `USD`, `EUR`, `GBP`). Defaults to USD if not specified.
`symbols`	Optional	Limit results to specific currencies. Enter codes separated by commas (e.g., `GBP,JPY,EUR`).

Example Request

curl -X GET "https://api.currencybeacon.com/v1/latest?api_key=YOUR_KEY&base=USD&symbols=EUR,GBP"

const res = await fetch("https://api.currencybeacon.com/v1/latest?api_key=YOUR_KEY&base=USD&symbols=EUR,GBP");
const data = await res.json();
console.log(data.response.rates);

import requests

r = requests.get(
    "https://api.currencybeacon.com/v1/latest",
    params={"api_key": "YOUR_KEY", "base": "USD", "symbols": "EUR,GBP"},
)
print(r.json()["response"]["rates"])

$json = file_get_contents("https://api.currencybeacon.com/v1/latest?api_key=YOUR_KEY&base=USD&symbols=EUR,GBP");
$data = json_decode($json, true);
print_r($data["response"]["rates"]);

Example Response

JSON200 OK

{
    "meta": {
        "code": 200,
        "disclaimer": "Usage subject to terms: https://currencybeacon.com/terms"
    },
    "response": {
        "date": "2024-03-15T14:30:00Z",
        "base": "USD",
        "rates": {
            "EUR": 0.9184,
            "GBP": 0.7842
        }
    }
}

GET/historical

Historical Rates

Retrieve historical exchange rates for any specific date in the past. Our database goes back to January 1, 1996. This is useful for auditing, accounting, and trend analysis.

Request Parameters

Key	Type	Description
`date`	Required	The date to retrieve rates for, in `YYYY-MM-DD` format.
`base`	Optional	The base currency code. Defaults to USD.
`symbols`	Optional	Filter results to specific currencies (comma-separated).

Example Request

curl -X GET "https://api.currencybeacon.com/v1/historical?api_key=YOUR_KEY&base=USD&date=2023-12-25"

const res = await fetch("https://api.currencybeacon.com/v1/historical?api_key=YOUR_KEY&base=USD&date=2023-12-25");
const data = await res.json();
console.log(data.response.rates);

import requests

r = requests.get(
    "https://api.currencybeacon.com/v1/historical",
    params={"api_key": "YOUR_KEY", "base": "USD", "date": "2023-12-25"},
)
print(r.json()["response"]["rates"])

$json = file_get_contents("https://api.currencybeacon.com/v1/historical?api_key=YOUR_KEY&base=USD&date=2023-12-25");
$data = json_decode($json, true);
print_r($data["response"]["rates"]);

GET/convert

Currency Conversion

The convert endpoint allows you to convert any amount from one currency to another using real-time mid-market exchange rates. This endpoint performs the calculation for you on the server side.

Request Parameters

Key	Type	Description
`from`	Required	The three-letter currency code to convert from (e.g., USD).
`to`	Required	The three-letter currency code to convert to (e.g., JPY).
`amount`	Required	The numeric amount to convert.
`date`	Optional	Perform the conversion using historical rates from this date (YYYY-MM-DD).

Example Request

curl -X GET "https://api.currencybeacon.com/v1/convert?api_key=YOUR_KEY&from=USD&to=GBP&amount=100"

const res = await fetch("https://api.currencybeacon.com/v1/convert?api_key=YOUR_KEY&from=USD&to=GBP&amount=100");
const data = await res.json();
console.log(data.response.value);

import requests

r = requests.get(
    "https://api.currencybeacon.com/v1/convert",
    params={"api_key": "YOUR_KEY", "from": "USD", "to": "GBP", "amount": 100},
)
print(r.json()["response"]["value"])

$json = file_get_contents("https://api.currencybeacon.com/v1/convert?api_key=YOUR_KEY&from=USD&to=GBP&amount=100");
$data = json_decode($json, true);
echo $data["response"]["value"];

Example Response

JSON200 OK

{
    "meta": { "code": 200, "disclaimer": "..." },
    "response": {
        "timestamp": 1710515400,
        "date": "2024-03-15",
        "from": "USD",
        "to": "GBP",
        "amount": 100,
        "value": 78.42
    }
}

GET/timeseries

*Available on Startup and Professional plans only.

Time-Series Data

The time-series endpoint returns daily historical exchange rates between two specified dates. This is designed for plotting charts or analyzing volatility over time.

Request Parameters

Key	Type	Description
`start_date`	Required	The beginning date of the range (YYYY-MM-DD).
`end_date`	Required	The end date of the range (YYYY-MM-DD). The maximum range depends on your plan (typically 365 days).
`base`	Optional	The base currency. Defaults to USD.

Example Request

curl -X GET "https://api.currencybeacon.com/v1/timeseries?api_key=YOUR_KEY&base=USD&start_date=2024-01-01&end_date=2024-03-15"

const res = await fetch("https://api.currencybeacon.com/v1/timeseries?api_key=YOUR_KEY&base=USD&start_date=2024-01-01&end_date=2024-03-15");
const data = await res.json();
console.log(data.response);

import requests

r = requests.get(
    "https://api.currencybeacon.com/v1/timeseries",
    params={"api_key": "YOUR_KEY", "base": "USD", "start_date": "2024-01-01", "end_date": "2024-03-15"},
)
print(r.json()["response"])

$json = file_get_contents("https://api.currencybeacon.com/v1/timeseries?api_key=YOUR_KEY&base=USD&start_date=2024-01-01&end_date=2024-03-15");
$data = json_decode($json, true);
print_r($data["response"]);

GET/currencies

Supported Currencies

Returns a list of all supported currencies, including their full names, symbols, and ISO codes. Use this to dynamically populate dropdowns in your UI. The same list is published on the Supported Currencies page.

Example Request

curl -X GET "https://api.currencybeacon.com/v1/currencies?api_key=YOUR_KEY"

const res = await fetch("https://api.currencybeacon.com/v1/currencies?api_key=YOUR_KEY");
const data = await res.json();
console.log(data.response);

import requests

r = requests.get("https://api.currencybeacon.com/v1/currencies", params={"api_key": "YOUR_KEY"})
print(r.json()["response"])

$json = file_get_contents("https://api.currencybeacon.com/v1/currencies?api_key=YOUR_KEY");
$data = json_decode($json, true);
print_r($data["response"]);

Errors & Status Codes

The API uses standard HTTP response codes to indicate the success or failure of an API request. In general: codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, or the API key is invalid). Codes in the 5xx range indicate an error with our servers.

Code	Status	Description & Troubleshooting
401	Unauthorized	Your API key is invalid, missing, or has not been activated. Check your dashboard to ensure your key is correct.
403	Forbidden	Your API key is valid, but the requested resource is restricted. This commonly happens if your plan does not include specific endpoints (such as timeseries).
404	Not Found	The requested endpoint or resource does not exist. Check for typos in the URL.
429	Too Many Requests	You have exceeded your request volume limit. Please upgrade your plan or slow down your request rate.
500	Internal Server Error	Something went wrong on our end. Please contact support if this issue persists.