Name: Forex Rates API: ECB Exchange Rates and Conversion
Brand: betelgues
SKU: api-betelgues-forex-rates
Availability: InStock
Author: API Market

# Forex Rates API

## Overview

The Forex Rates API returns European Central Bank reference exchange rates as JSON. It lists the 30 supported currencies, gives the latest rates for any base currency, returns the rates for a past date, and converts an amount from one currency to another. Rates come from the ECB through frankfurter.dev and are updated once per working day.

It is for developers building pricing pages, invoicing and accounting tools, e-commerce checkouts and finance dashboards that need reliable reference rates without running their own feed. Every response states the base currency, the rate date and the source.

## Features

*   **5 endpoints**: health check, currency list, latest rates, historical rates and conversion.
*   **Any base currency**: set `base` to any supported code; EUR is the default.
*   **Symbol filter**: limit the result to the currencies you need with `symbols`.
*   **Historical lookups**: rates for any past working day by date.
*   **Conversion**: convert an amount and get the rate used.
*   **Data source**: ECB reference rates via frankfurter.dev.
*   **Rate limit**: up to 10 requests per second on every plan.

## Use Cases

*   **E-commerce**: show prices in the shopper's currency.
*   **Invoicing and accounting**: record the reference rate for the invoice date.
*   **Finance dashboards**: track currency moves over time.
*   **Travel and expense apps**: convert receipts into a home currency.

## API Documentation

### Base URL

All requests go through the API.market proxy at this base URL:

```
https://prod.api.market/api/v1/betelgues/forex-rates
```

### Authentication

Every request must include your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Health check

Returns the service status and version. Use it to confirm the Forex Rates API is up before making data calls.

**Method:** `GET`

**Endpoint:** `/health`

**Parameters:** None.

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/betelgues/forex-rates/health' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "status": "ok",
  "service": "forex-rates",
  "version": "0.1.0"
}
```

#### 2. List currencies

Returns every supported currency code with its full name.

**Method:** `GET`

**Endpoint:** `/currencies`

**Parameters:** None.

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/betelgues/forex-rates/currencies' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "count": 30,
  "currencies": {
    "AUD": "Australian Dollar",
    "BRL": "Brazilian Real",
    "CAD": "Canadian Dollar",
    "CHF": "Swiss Franc",
    "CNY": "Chinese Renminbi Yuan",
    "CZK": "Czech Koruna",
    "DKK": "Danish Krone",
    "EUR": "Euro",
    "GBP": "British Pound",
    "HKD": "Hong Kong Dollar",
    "HUF": "Hungarian Forint",
    "IDR": "Indonesian Rupiah",
    "ILS": "Israeli New Shekel",
    "INR": "Indian Rupee",
    "ISK": "Icelandic Króna",
    "JPY": "Japanese Yen",
    "KRW": "South Korean Won",
    "MXN": "Mexican Peso",
    "MYR": "Malaysian Ringgit",
    "NOK": "Norwegian Krone",
    "NZD": "New Zealand Dollar",
    "PHP": "Philippine Peso",
    "PLN": "Polish Złoty",
    "RON": "Romanian Leu",
    "SEK": "Swedish Krona",
    "SGD": "Singapore Dollar",
    "THB": "Thai Baht",
    "TRY": "Turkish Lira",
    "USD": "United States Dollar",
    "ZAR": "South African Rand"
  },
  "fetchedAt": "2026-11-04T07:12:52.178390+00:00"
}
```

#### 3. Latest rates

Returns the most recent reference rates for the chosen base currency.

**Method:** `GET`

**Endpoint:** `/latest`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| base | query | Base currency code | string | No | EUR | - |
| symbols | query | Comma-separated currency codes to return. Leave empty for all | string | No | - | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/betelgues/forex-rates/latest?base=EUR&symbols=USD%2CGBP%2CJPY' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "base": "EUR",
  "date": "2026-11-03",
  "rates": {
    "GBP": 0.83358,
    "JPY": 176.95,
    "USD": 1.1179
  },
  "amount": 1.0,
  "source": "frankfurter.dev (ECB)",
  "fetchedAt": "2026-11-04T07:12:53.035267+00:00"
}
```

#### 4. Historical rates

Returns the reference rates published for a past date.

**Method:** `GET`

**Endpoint:** `/historical`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| date | query | Date in YYYY-MM-DD format | string | Yes | - | - |
| base | query | Base currency code | string | No | EUR | - |
| symbols | query | Comma-separated currency codes to return | string | No | - | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/betelgues/forex-rates/historical?date=2026-10-01&base=EUR&symbols=USD%2CGBP' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "base": "EUR",
  "date": "2026-10-01",
  "rates": {
    "GBP": 0.85373,
    "USD": 1.1298
  },
  "amount": 1.0,
  "source": "frankfurter.dev (ECB)",
  "fetchedAt": "2026-11-04T07:12:53.821609+00:00"
}
```

#### 5. Convert

Converts an amount from one currency to another at the latest reference rate.

**Method:** `GET`

**Endpoint:** `/convert`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| amount | query | Amount to convert | number | Yes | - | - |
| from | query | Currency code to convert from | string | Yes | - | - |
| to | query | Currency code to convert to | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/betelgues/forex-rates/convert?amount=100&from=USD&to=EUR' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "amount": 100.0,
  "from": "USD",
  "to": "EUR",
  "result": 89.45,
  "date": "2026-11-03",
  "rate": 0.8945000000000001,
  "source": "frankfurter.dev (ECB)",
  "fetchedAt": "2026-11-04T07:12:54.624400+00:00"
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded and the response body holds the result. |
| 400 | Bad Request | A required parameter is missing or a value is invalid. Check the parameter table for the endpoint. |
| 401 | Unauthorized | The `x-api-market-key` header is missing or the key is not valid. |
| 403 | Forbidden | Your key is valid but your subscription does not allow this request, for example an endpoint outside your plan. |
| 404 | Not Found | The path does not exist, or the resource you asked for was not found. |
| 429 | Too Many Requests | You sent more than 10 requests per second. Slow down and retry, honouring the `Retry-After` header. |
| 500 | Internal Server Error | Something went wrong while processing the request. Retry after a short wait. |
| 503 | Service Unavailable | The service or its upstream data source is temporarily unavailable. Retry with backoff. |

## Rate Limits

Every plan allows up to 10 requests per second. Subscription plans also have a monthly call quota shown on the pricing page. Sending more than 10 requests per second returns `429 Too Many Requests`. Throttle your client to stay under 10 requests per second, back off and retry when you get a 429, and honour the `Retry-After` header when it is present.

## FAQ

*   **How often are rates updated?**

    The ECB publishes reference rates once per working day. The `date` field in each response shows which day's rates you received.

*   **Which currencies are supported?**

    The 30 currencies returned by `/currencies`, which are the ECB reference set.

*   **Are these live market rates?**

    No. They are daily reference rates, suited to pricing, invoicing and reporting rather than trading.

*   **What is the /health endpoint for?**

    It returns the service name and version so you can confirm the API is reachable before sending real requests. It does not fetch any data.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Latest and historical ECB exchange rates for 30 currencies, with any base currency and amount conversion, as clean JSON.