# freecurrencyapi documentation

> freecurrencyapi provides free current and historical foreign exchange rates over a simple JSON REST API.

Authenticate every request with your API key via the `apikey` query parameter or request header. Base URL: https://api.freecurrencyapi.com

OpenAPI specification: https://freecurrencyapi.com/docs/openapi.yaml

---

Source: https://freecurrencyapi.com/docs

## Official libraries

Building with an AI assistant? The full API is available as a machine-readable [OpenAPI 3.1 specification](https://freecurrencyapi.com/docs/openapi.yaml), and the documentation is published as [llms.txt](https://freecurrencyapi.com/docs/llms.txt) / [llms-full.txt](https://freecurrencyapi.com/docs/llms-full.txt). There is also a hosted [MCP server](https://freecurrencyapi.com/docs/mcp) at `https://api.freecurrencyapi.com/mcp` that AI agents can connect to directly.

| Language               | Code                                                                                                       | Repository                                                                                                                               |
|------------------------|------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------|
| PHP                    | [https://github.com/everapihq/freecurrencyapi-php](https://github.com/everapihq/freecurrencyapi-php)       | [https://packagist.org/packages/everapi/freecurrencyapi-php](https://packagist.org/packages/everapi/freecurrencyapi-php)                 |
| Python                 | [https://github.com/everapihq/freecurrencyapi-python](https://github.com/everapihq/freecurrencyapi-python) | [https://pypi.org/project/freecurrencyapi/](https://pypi.org/project/freecurrencyapi/)                                                   |
| R                      | [https://github.com/everapihq/freecurrencyapi-r](https://github.com/everapihq/freecurrencyapi-r)           | [https://cran.r-project.org/web/packages/freecurrencyapi/index.html](https://cran.r-project.org/web/packages/freecurrencyapi/index.html) |
| Go                     | [github.com/everapihq/freecurrencyapi-go](github.com/everapihq/freecurrencyapi-go)                         | [https://pkg.go.dev/github.com/everapihq/freecurrencyapi-go](https://pkg.go.dev/github.com/everapihq/freecurrencyapi-go)                 |
| Ruby                   | [https://github.com/everapihq/freecurrencyapi-ruby](https://github.com/everapihq/freecurrencyapi-ruby)     | [https://rubygems.org/gems/freecurrencyapi-official](https://rubygems.org/gems/freecurrencyapi-official)                                 |
| JavaScript ES6 module	 | [https://github.com/everapihq/freecurrencyapi-js](https://github.com/everapihq/freecurrencyapi-js)         | [https://www.npmjs.com/package/@everapi/freecurrencyapi-js](https://www.npmjs.com/package/@everapi/freecurrencyapi-js)                   |
| Rust                   | [https://github.com/everapihq/freecurrencyapi-rs](https://github.com/everapihq/freecurrencyapi-rs)         | [https://crates.io/crates/freecurrencyapi-rs](https://crates.io/crates/freecurrencyapi-rs)                                               |
| C#                     | [https://github.com/everapihq/freecurrencyapi-dotnet](https://github.com/everapihq/freecurrencyapi-dotnet) | [https://www.nuget.org/packages/freecurrencyapi/](https://www.nuget.org/packages/freecurrencyapi/)                                       |

## Authentication & API key Information

freecurrencyapi.com uses API keys to allow access to the API.

## Authentication methods

To authorize, you can use the following ways:

### GET query parameter

You can pass your API key along with every request by adding it as a query parameter `apikey`

This method could expose your API key in access logs and such.
Sending the API key via a header parameter as specified below circumvents this problem.

```bash
curl "https://api.freecurrencyapi.com/v1/latest?apikey=YOUR-APIKEY"
```

```javascript
var oReq = new XMLHttpRequest();
oReq.addEventListener("load", function () { console.log(this.responseText); });
oReq.open("GET", "https://api.freecurrencyapi.com/v1/latest?apikey=YOUR-APIKEY");
oReq.send();
```

```php
$url = "https://api.freecurrencyapi.com/v1/latest?apikey=YOUR-APIKEY";

$curl = curl_init($url);

$resp = curl_exec($curl);
var_dump($resp);

````

```python
import requests
from requests.structures import CaseInsensitiveDict

url = "https://api.freecurrencyapi.com/v1/latest?apikey=YOUR-APIKEY"

resp = requests.get(url)

print(resp.status_code)
````

### HTTP Header

You can set a request header with the name `apikey`

```bash
curl "https://api.freecurrencyapi.com/v1/latest" \
    -H "apikey: YOUR-APIKEY" 
```

```javascript
var oReq = new XMLHttpRequest();
oReq.addEventListener("load", function () { console.log(this.responseText); });
oReq.open("GET", "https://api.freecurrencyapi.com/v1/latest");
oReq.setRequestHeader("apikey", "YOUR-APIKEY");
oReq.send();
```

```php
$url = "https://api.freecurrencyapi.com/v1/latest";

$curl = curl_init($url);
$headers = array(
"apikey: YOUR-APIKEY",
);

$resp = curl_exec($curl);
var_dump($resp);

````

```python
import requests
from requests.structures import CaseInsensitiveDict

url = "https://api.freecurrencyapi.com/v1/latest"

headers = CaseInsensitiveDict()
headers["apikey"] = "YOUR-APIKEY"

resp = requests.get(url, headers=headers)

print(resp.status_code)
````

## Rate limit and quotas

You can use a certain amount of requests per month.
Once you go over this quota you will be presented with a `429` HTTP status code, and you have to wait a month to do more
requests.

We enforce a minute rate limit for each plan. If you exceed this you will also be presented with a `429` HTTP status
code.
You then have to wait until the end of the minute to do more requests.

Only successful calls count against your quota. Any error on our side or any validation error (e.g. wrong parameter)
will NOT count against your quota or rate limit.

### Response Headers

We attach certain headers to tell you your current monthly/minute quota and how much you have remaining in the period.

```HTTP
X-RateLimit-Limit-Quota-Minute: 10
X-RateLimit-Limit-Quota-Month: 300

X-RateLimit-Remaining-Quota-Minute: 5
X-RateLimit-Remaining-Quota-Month: 199
```

---

Source: https://freecurrencyapi.com/docs/currencies

# Currencies Endpoint

Returns all our supported currencies

**Request Method:** `GET`  
**Request URL:** `https://api.freecurrencyapi.com/v1/currencies`

## Request Parameters

| Parameter    | Type     | Mandatory  | Description                                                                                                                       |
| ------------ | -------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `apikey`     | _string_ | ️ | Your API Key                                                                                                                      |
| `currencies` | _string_ |            | A list of comma seperated currency codes which you want to get (EUR,USD,CAD)By default all available currencies will be shown |

## Sample Response

```json
{
    "data": {
        "AED": {
            "symbol": "AED",
            "name": "United Arab Emirates Dirham",
            "symbol_native": "د.إ",
            "decimal_digits": 2,
            "rounding": 0,
            "code": "AED",
            "name_plural": "UAE dirhams"
        },
        "AFN": {
            "symbol": "Af",
            "name": "Afghan Afghani",
            "symbol_native": "؋",
            "decimal_digits": 0,
            "rounding": 0,
            "code": "AFN",
            "name_plural": "Afghan Afghanis"
        },
        "...": {}
    }
}
```

---

Source: https://freecurrencyapi.com/docs/currency-list

# Currency List

CodeNameEUREuroUSDUS DollarJPYJapanese YenBGNBulgarian LevCZKCzech Republic KorunaDKKDanish KroneGBPBritish Pound SterlingHUFHungarian ForintPLNPolish ZlotyRONRomanian LeuSEKSwedish KronaCHFSwiss FrancISKIcelandic KrónaNOKNorwegian KroneHRKCroatian KunaRUBRussian RubleTRYTurkish LiraAUDAustralian DollarBRLBrazilian RealCADCanadian DollarCNYChinese YuanHKDHong Kong DollarIDRIndonesian RupiahILSIsraeli New SheqelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoMYRMalaysian RinggitNZDNew Zealand DollarPHPPhilippine PesoSGDSingapore DollarTHBThai BahtZARSouth African Rand

---

Source: https://freecurrencyapi.com/docs/historical

# Historical Exchange Rates

Returns exchange rates for a given date. Generally, we provide data going back to 1999.
To get a range of historical data, please upgrade to currencyapi.com in your dashboard and use the /range endpoint (https://currencyapi.com/docs/range)

**Request Method:** `GET`  
**Request URL:** `https://api.freecurrencyapi.com/v1/historical`

## Request Parameters

| Parameter       | Type     | Mandatory  | Description                                                                                                                       |
| --------------- | -------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `apikey`        | _string_ | ️ | Your API Key                                                                                                                      |
| `date`          | _string_ | ️ | Start date to retrieve historical rates from (format: 2021-12-31)                                                                 |
| `base_currency` | _string_ |            | The base currency to which all results are behaving relative toBy default all values are based on USD                         |
| `currencies`    | _string_ |            | A list of comma seperated currency codes which you want to get (EUR,USD,CAD)By default all available currencies will be shown |

## Sample Response

The API response comes in easy-to-read JSON format and contains the end-of-day data for the provided `date` parameter
for all currencies.

```json
{
    "data": {
        "2022-01-01": {
            "AED": 3.67306,
            "AFN": 91.80254,
            "ALL": 108.22904,
            "AMD": 480.41659,
            "...": "150+ more currencies"
        }
    }
}
```

---

Source: https://freecurrencyapi.com/docs/latest

# Latest Exchange Rates

Returns the latest exchange rates. The default base currency is `USD`.

We update our date with end of day data.

**Request Method:** `GET`  
**Request URL:** `https://api.freecurrencyapi.com/v1/latest`

## Request Parameters

| Parameter       | Type     | Mandatory  | Description                                                                                                                       |
| --------------- | -------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `apikey`        | _string_ | ️ | Your API Key                                                                                                                      |
| `base_currency` | _string_ |            | The base currency to which all results are behaving relative toBy default all values are based on USD                         |
| `currencies`    | _string_ |            | A list of comma-separated currency codes which you want to get (EUR,USD,CAD)By default all available currencies will be shown |

## Sample Response

The API response comes as a JSON and consists of a `meta` and a `data` key.
The `meta` holds useful information like the `last_updated_at` datetime to let you know then this dataset was last updated.

The `data` key holds the actual currency information.

```json
{
    "data": {
        "AED": 3.67306,
        "AFN": 91.80254,
        "ALL": 108.22904,
        "AMD": 480.41659,
        "...": "150+ more currencies"
    }
}
```

---

Source: https://freecurrencyapi.com/docs/mcp

# MCP Server

freecurrencyapi ships a hosted [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server, so AI agents and assistants can call the API as native tools — no SDK or glue code required.

```
https://api.freecurrencyapi.com/mcp
```

The endpoint speaks the streamable HTTP transport. Listing the available tools works without authentication; executing a tool requires your API key, sent as the `apikey` header. You can [get a free API key here](https://app.freecurrencyapi.com/register).

## Connect

Using Claude Code:

```bash
claude mcp add --transport http freecurrencyapi https://api.freecurrencyapi.com/mcp --header "apikey: YOUR_API_KEY"
```

Or add the server to any MCP-capable client (Claude Desktop, Cursor, VS Code, ...):

```json
{
  "mcpServers": {
    "freecurrencyapi": {
      "url": "https://api.freecurrencyapi.com/mcp",
      "headers": { "apikey": "YOUR_API_KEY" }
    }
  }
}
```

## Available tools

The tools are generated from the same [OpenAPI specification](https://freecurrencyapi.com/docs/openapi.yaml) that describes the REST API, so they always match the documented endpoints, parameters and responses.

| Tool | Endpoint | Description |
|---|---|---|
| `getLatest` | `GET /v1/latest` | Latest exchange rates |
| `getHistorical` | `GET /v1/historical` | Historical exchange rates |
| `getCurrencies` | `GET /v1/currencies` | List supported currencies |
| `getStatus` | `GET /v1/status` | Account quota status |

## Quotas and errors

Tool calls are metered exactly like REST requests: they consume your plan quota and return the same status codes and error responses (`401`, `422`, `429`, ...). If a call fails, the tool result contains the API's error message including hints on how to proceed.

---

Source: https://freecurrencyapi.com/docs/status

# Status Endpoint

Returns your current quota

Requests to this endpoint do not count against your quota or rate limit

**Request Method:** `GET`  
**Request URL:** `https://api.freecurrencyapi.com/v1/status`

## Request Parameters

| Parameter | Type     | Mandatory  | Description  |
| --------- | -------- | ---------- | ------------ |
| `apikey`  | _string_ | ️ | Your API Key |

## Sample Response

```json
{
    "quotas": {
        "month": {
            "total": 300,
            "used": 71,
            "remaining": 229
        }
    }
}
```

---

Source: https://freecurrencyapi.com/docs/status-codes

# Request Status Codes

For all requests, we will return an HTTP status code that indicates a success or the problem that has led to the failure.

A successful request will be returned with status code `200`

## API Error Codes

### 401

Invalid authentication credentials

### 403

You are not allowed to use this endpoint, please [upgrade your plan](https://app.freecurrencyapi.com/subscription).

### 404

A requested endpoint does not exist

### 422

Validation error, please check the list of validation errors: [here](#validation-errors)

### 429

You have hit your rate limit or your monthly limit. For more requests please [upgrade your plan](https://app.freecurrencyapi.com/subscription).

### 500

Internal Server Error - let us know: support@freecurrencyapi.com

## Validation errors

#### Invalid currencies

One of the selected `currencies` is invalid, to get a full list of all currencies you can use the `currency` endpoint.

#### Invalid base_currency

The selected `base_currency` is invalid, to get a full list of all currencies you can use the `currency` endpoint.

#### Invalid date

The `date` is not a valid date. Please use the following format: YYYY-MM-DD

#### Wrong format: value

The `value` must be a number.

#### Chronological order issue: datetime_start

The `datetime_start` must be a date before or equal to datetime_end

#### Invalid datetime_start

The `datetime_start` is not a valid date.

Datetime for the start of your requested range (format: 2021-12-31T23:59:59Z / ISO8601 Datetime)

#### Chronological order issue: datetime_end

The `datetime_start` must be a date before or equal to datetime_end

#### Invalid datetime_end

The `datetime_start` is not a valid date.

Datetime for the end of your requested range (format: 2021-12-31T23:59:59Z / ISO8601 Datetime)

#### Invalid accuracy

The selected `accuracy` is invalid.

Possible Values: day, hour, quarter_hour, minute
Default: day