# 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

# Introduction

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

Get your free API key at [https://app.freecurrencyapi.com/register](https://app.freecurrencyapi.com/register) — you need it for every request.

## Authentication & API key Information

freecurrencyapi.com uses API keys to allow access to the API.
You can get your API key by [registering for a free account](https://app.freecurrencyapi.com/register).

## 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);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

$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",
);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

$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
```

Successful JSON responses from the data endpoints (latest, historical and
currencies) also include an `X-Cost` header with the quota cost of the request
and an `X-Execution-Time` header with the server-side processing time in
milliseconds. Responses from the status endpoint include neither header.

## 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/)                                       |

---

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

# Currencies Endpoint

Returns all our supported currencies. The API supports 33 currencies — see the full [currency list](https://freecurrencyapi.com/docs/currency-list).

**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-separated currency codes which you want to get (EUR,USD,CAD)By default all available currencies will be shown |
| `as_html`    | _boolean_ |            | Return the currency list as an HTML table instead of JSON                                                                          |

## Example Request

```bash
curl "https://api.freecurrencyapi.com/v1/currencies?currencies=EUR,GBP" \
    -H "apikey: YOUR-APIKEY"
```

## Sample Response

```json
{
    "data": {
        "EUR": {
            "symbol": "€",
            "name": "Euro",
            "symbol_native": "€",
            "decimal_digits": 2,
            "rounding": 0,
            "code": "EUR",
            "name_plural": "Euros",
            "type": "fiat"
        },
        "GBP": {
            "symbol": "£",
            "name": "British Pound Sterling",
            "symbol_native": "£",
            "decimal_digits": 2,
            "rounding": 0,
            "code": "GBP",
            "name_plural": "British pounds sterling",
            "type": "fiat"
        }
    }
}
```

Because the example request filters to `currencies=EUR,GBP`, exactly those two entries are
returned; omit the `currencies` parameter to receive all 33 supported currencies.

---

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 single given date. We provide data going back to `1999-01-01`, up to and including yesterday.
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_ |            | The date to retrieve historical rates for (format: 2021-12-31, between 1999-01-01 and yesterday)Defaults to yesterday          |
| `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 |

Passing the range parameters `date_from`/`date_to` returns a `403` error on the free plan.
For date ranges, upgrade to currencyapi.com and use its /range endpoint.

## Example Request

```bash
curl "https://api.freecurrencyapi.com/v1/historical?date=2022-01-01&currencies=EUR,GBP" \
    -H "apikey: YOUR-APIKEY"
```

## 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 requested currencies. Because the example request filters to `currencies=EUR,GBP`, exactly those two codes are
returned; omit the `currencies` parameter to receive all 33 supported currencies — see the full
[currency list](https://freecurrencyapi.com/docs/currency-list).

```json
{
    "data": {
        "2022-01-01": {
            "EUR": 0.879908,
            "GBP": 0.739337
        }
    }
}
```

---

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

# Latest Exchange Rates

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

We update our data 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 |

## Example Request

```bash
curl "https://api.freecurrencyapi.com/v1/latest?base_currency=USD&currencies=EUR,USD,GBP" \
    -H "apikey: YOUR-APIKEY"
```

## Sample Response

The API response comes as a JSON with a single `data` key. It holds a flat map of
currency code to exchange rate, relative to the requested `base_currency`.
Because the example request filters to `currencies=EUR,USD,GBP`, exactly those three
codes are returned; omit the `currencies` parameter to receive all 33 supported
currencies — see the full [currency list](https://freecurrencyapi.com/docs/currency-list).

```json
{
    "data": {
        "EUR": 0.918456,
        "USD": 1,
        "GBP": 0.789012
    }
}
```

---

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. All requests — including listing the available tools — require 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 |

## Example Request

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

## Sample Response

`account_id` is your account's numeric ID. The `month` bucket is your regular
monthly request quota. The `grace` bucket is a temporary extra allowance that
keeps your integration running while a pending payment is being completed — it
is `0` unless a grace period is active for your account.

```json
{
    "account_id": 313373133731337,
    "quotas": {
        "month": {
            "total": 300,
            "used": 71,
            "remaining": 229
        },
        "grace": {
            "total": 0,
            "used": 0,
            "remaining": 0
        }
    }
}
```

---

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 make this request — for example, the requested feature is not part of your plan
(please [upgrade your plan](https://app.freecurrencyapi.com/subscription)), the request's referrer is not
on your API key's referrer whitelist, or the API key belongs to a different EverAPI product.

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

## Error response format

Error responses with status `401`, `403`, `404` and `429` carry a machine-readable
envelope in addition to the human-readable `message`:

- `error.code` — a stable, machine-readable error code (see the table below)
- `error.message` — the same text as `message`
- `quota` — only on quota errors: your `limit`, `used`, `remaining` and the
  `resets_at` timestamp of the next quota reset
- `actions` — URLs for the most useful next steps, e.g. where to get an API key,
  upgrade your plan or find the machine-readable API specification

```json
{
    "message": "Invalid authentication credentials",
    "error": {
        "code": "invalid_api_key",
        "message": "Invalid authentication credentials"
    },
    "actions": {
        "get_free_api_key": "https://api.freecurrencyapi.com/v1/agent/keys",
        "sign_up": "https://app.freecurrencyapi.com/register?utm_source=api_error&utm_campaign=invalid_api_key",
        "docs": "https://freecurrencyapi.com/docs/openapi.yaml"
    }
}
```

| Status | Possible `error.code` values                                                                |
| ------ | ------------------------------------------------------------------------------------------- |
| `401`  | `missing_api_key`, `invalid_api_key`                                                        |
| `403`  | `forbidden`, `referrer_not_allowed`, `key_not_allowed_for_product`                          |
| `404`  | `not_found`                                                                                 |
| `429`  | `rate_limit_exceeded`, `quota_exceeded`, `grace_quota_exceeded`, `overage_quota_exceeded`   |

## Validation errors

Validation errors are returned with status `422` and contain a `message`
(`"Validation error"`), an `errors` object keyed by the offending parameter with
one or more messages per parameter, and an `info` link back to this page.

#### Invalid currencies

One of the selected `currencies` is invalid, to get a full list of all currencies you can use the [currencies](https://freecurrencyapi.com/docs/currencies) endpoint.

#### Invalid base_currency

The selected `base_currency` is invalid, to get a full list of all currencies you can use the [currencies](https://freecurrencyapi.com/docs/currencies) endpoint.

#### Invalid date

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

The `date` must be between `1999-01-01` and yesterday.