# Currency & Exchange Rates API — live and historical FX rates from the European Central Bank: latest rates, currency conversion, time-series and fluctuation

> latest reference rates for a base (default EUR) → all or selected target currencies (+ unix timestamp)
> ReefAPI engine `currency` · 6 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/currency/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /currency/v1/latest — 1 credit
latest reference rates for a base (default EUR) → all or selected target currencies (+ unix timestamp)

**Parameters:**
- `base` (enum, optional, default "EUR") — Base currency the rates are expressed in (ISO-4217). Defaults to EUR. Retired codes (RUB/HRK/legacy euro-joiners) work only for historical dates that predate their discontinuation. [one of: EUR, USD, JPY, GBP, CHF, AUD, CAD, CNY, HKD, NZD, SEK, NOK, DKK, CZK, HUF, PLN, RON, BGN, TRY, ISK, ILS, INR, IDR, KRW, MYR, PHP, SGD, THB, ZAR, MXN, BRL, RUB, HRK, GRD, CYP, EEK, LTL, LVL, MTL, SIT, SKK, ROL, TRL]
- `symbols` (string, optional) — Optional comma-separated target currencies to return (e.g. 'USD,GBP,JPY'). Omit to return every currency in the ECB set. Unknown codes are reported under 'unavailable', not rejected.

**Returns:** base, date, timestamp (ECB 16:00 CET/CEST unix), rates{CUR:val}, amount; unavailable[] for any unknown requested symbols

**Example request body:**
```json
{
  "base": "EUR"
}
```

### POST /currency/v1/convert — 1 credit
convert an amount from→to at the latest rate (or a given historical date); returns rate + result

**Parameters:**
- `from` (enum, required) — Source currency to convert FROM (ISO-4217). [one of: EUR, USD, JPY, GBP, CHF, AUD, CAD, CNY, HKD, NZD, SEK, NOK, DKK, CZK, HUF, PLN, RON, BGN, TRY, ISK, ILS, INR, IDR, KRW, MYR, PHP, SGD, THB, ZAR, MXN, BRL, RUB, HRK, GRD, CYP, EEK, LTL, LVL, MTL, SIT, SKK, ROL, TRL]
- `to` (enum, required) — Target currency to convert TO (ISO-4217). [one of: EUR, USD, JPY, GBP, CHF, AUD, CAD, CNY, HKD, NZD, SEK, NOK, DKK, CZK, HUF, PLN, RON, BGN, TRY, ISK, ILS, INR, IDR, KRW, MYR, PHP, SGD, THB, ZAR, MXN, BRL, RUB, HRK, GRD, CYP, EEK, LTL, LVL, MTL, SIT, SKK, ROL, TRL]
- `amount` (number, optional, default 1) — Amount of the source currency to convert (default 1).
- `date` (string, optional) — Optional historical date (YYYY-MM-DD) to convert at; omit for the latest published rate.

**Returns:** from, to, amount, rate, result (amount*rate), date (+ requested_date if the date rolled back to a working day)

**Example request body:**
```json
{
  "from": "USD",
  "to": "EUR",
  "amount": 100
}
```

### POST /currency/v1/historical — 1 credit
reference rates on a past date (YYYY-MM-DD; weekend/holiday → last working day) since 1999-01-04

**Parameters:**
- `date` (string, required) — Reference date (YYYY-MM-DD), since 1999-01-04. A weekend/holiday resolves to the last working day (echoed as requested_date).
- `base` (enum, optional, default "EUR") — Base currency the rates are expressed in (ISO-4217). Defaults to EUR. Retired codes (RUB/HRK/legacy euro-joiners) work only for historical dates that predate their discontinuation. [one of: EUR, USD, JPY, GBP, CHF, AUD, CAD, CNY, HKD, NZD, SEK, NOK, DKK, CZK, HUF, PLN, RON, BGN, TRY, ISK, ILS, INR, IDR, KRW, MYR, PHP, SGD, THB, ZAR, MXN, BRL, RUB, HRK, GRD, CYP, EEK, LTL, LVL, MTL, SIT, SKK, ROL, TRL]
- `symbols` (string, optional) — Optional comma-separated target currencies to return (e.g. 'USD,GBP,JPY'). Omit to return every currency in the ECB set. Unknown codes are reported under 'unavailable', not rejected.

**Returns:** base, date (actual working day), rates{CUR:val} (+ requested_date if rolled back); unavailable[] if any

**Example request body:**
```json
{
  "date": "2020-07-01",
  "base": "USD",
  "symbols": "EUR,GBP"
}
```

### POST /currency/v1/timeseries — 2 credits
rates over a date range (working days) for a base → selected/all targets; {date:{CUR:val}}

**Parameters:**
- `start` (string, required) — Range start date (YYYY-MM-DD, inclusive). Only ECB working days inside the range are returned.
- `end` (string, required) — Range end date (YYYY-MM-DD, inclusive).
- `base` (enum, optional, default "EUR") — Base currency the rates are expressed in (ISO-4217). Defaults to EUR. Retired codes (RUB/HRK/legacy euro-joiners) work only for historical dates that predate their discontinuation. [one of: EUR, USD, JPY, GBP, CHF, AUD, CAD, CNY, HKD, NZD, SEK, NOK, DKK, CZK, HUF, PLN, RON, BGN, TRY, ISK, ILS, INR, IDR, KRW, MYR, PHP, SGD, THB, ZAR, MXN, BRL, RUB, HRK, GRD, CYP, EEK, LTL, LVL, MTL, SIT, SKK, ROL, TRL]
- `symbols` (string, optional) — Optional comma-separated target currencies to return (e.g. 'USD,GBP,JPY'). Omit to return every currency in the ECB set. Unknown codes are reported under 'unavailable', not rejected.

**Returns:** base, start, end, rates{date:{CUR:val}} per working day (+ stop_reason if the range was capped)

**Example request body:**
```json
{
  "start": "2024-01-02",
  "end": "2024-01-05",
  "base": "EUR",
  "symbols": "USD"
}
```

### POST /currency/v1/fluctuation — 2 credits
per-currency change over a date range: {CUR:{start_rate,end_rate,change,change_pct}} (derived from the range endpoints)

**Parameters:**
- `start` (string, required) — Range start date (YYYY-MM-DD, inclusive). Only ECB working days inside the range are returned.
- `end` (string, required) — Range end date (YYYY-MM-DD, inclusive).
- `base` (enum, optional, default "EUR") — Base currency the rates are expressed in (ISO-4217). Defaults to EUR. Retired codes (RUB/HRK/legacy euro-joiners) work only for historical dates that predate their discontinuation. [one of: EUR, USD, JPY, GBP, CHF, AUD, CAD, CNY, HKD, NZD, SEK, NOK, DKK, CZK, HUF, PLN, RON, BGN, TRY, ISK, ILS, INR, IDR, KRW, MYR, PHP, SGD, THB, ZAR, MXN, BRL, RUB, HRK, GRD, CYP, EEK, LTL, LVL, MTL, SIT, SKK, ROL, TRL]
- `symbols` (string, optional) — Optional comma-separated target currencies to return (e.g. 'USD,GBP,JPY'). Omit to return every currency in the ECB set. Unknown codes are reported under 'unavailable', not rejected.

**Returns:** base, start, end, start_date, end_date, rates{CUR:{start_rate,end_rate,change,change_pct}}

**Example request body:**
```json
{
  "start": "2024-01-02",
  "end": "2024-01-31",
  "base": "EUR",
  "symbols": "USD"
}
```

### POST /currency/v1/currencies — 1 credit
the current ECB reference currency set (code → name)

**Parameters:** none

**Returns:** date, count, base (EUR), currencies{CODE:name} for the current ECB reference set

## More
- Try it live, no code: https://reefapi.com/playground?engine=currency
- Human docs page: https://reefapi.com/docs/currency
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt