Name: Currency Converter API with ECB Exchange Rates
Brand: leadharbor
SKU: api-leadharbor-currency-converter
Availability: InStock
Author: API Market

Mohammed Samaan

# Currency Converter API

## Overview

The Currency Converter API converts amounts between currencies using the European Central Bank (ECB) euro foreign exchange reference rates, read from the ECB's published file. It has 1 endpoint, `/v1/market/fx`, with two operations selected by the `op` parameter. `op=convert` takes a `from` currency, a `to` currency and an `amount` and returns the rate and the converted result. `op=rates` returns the full rate table against a `base` currency. Both accept an optional `date` for any day in the last 90 days, so the same call gives you today's rate or a historical one. The API covers the currencies the ECB publishes, about 30 of them.

It is built for invoicing and accounting tools that need a dated, sourced rate for a transaction, e-commerce sites that show approximate prices in a visitor's currency, finance dashboards and reports, and back-office jobs that convert historical amounts. Every answer is a flat JSON object that carries the rate, the result or the rate table, the date of the rates in `as_of`, the `source` and a `note` that these are reference rates. A `meta` object holds a `stale` flag, which is `true` when the ECB file could not be reached and a cached table was served, and a `user` field that you can ignore.

## Features

*   **1 endpoint, 2 operations**: `op=convert` for converting an amount and `op=rates` for the full rate table against a base currency.
*   **Simple inputs**: ISO 4217 currency codes such as `USD`, `GBP` or `JPY`, an amount from 0 to 1e12, and an optional `YYYY-MM-DD` date.
*   **90 days of history**: Pass `date` for any day in the last 90 days. A weekend or holiday maps to the previous ECB publication day, and `as_of` tells you which day was used.
*   **Dated and sourced answers**: Every response carries `as_of`, `source` and a `note`, so you can record where a rate came from.
*   **Any base currency**: Rates are published against the euro, and the API cross-calculates them so you can convert between any two supported currencies or request the table against any base.
*   **Data source**: ECB euro foreign exchange reference rates, published once per working day around 16:00 CET. If the ECB file is unreachable, a cached table up to 48 hours old is served and marked with `meta.stale: true`.
*   **Rate limit**: 10 requests per second on every plan.

## Use Cases

*   **Invoicing and accounting**: Convert an invoice amount and store the rate, `as_of` date and source alongside it.
*   **Price display**: Show approximate prices in a shopper's local currency on product and checkout pages.
*   **Historical conversion**: Convert past transactions at the reference rate for the day they happened, up to 90 days back.
*   **Finance reporting**: Pull the full rate table once a day to convert totals in dashboards and reports.
*   **Expense tools**: Convert receipts in foreign currencies to the company's reporting currency.

## API Documentation

### Base URL

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

```
https://prod.api.market/api/v1/leadharbor/currency-converter
```

### Authentication

Every request needs 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. Convert an amount (op=convert)

Converts an amount from one currency to another and returns the `rate`, the `result`, the date of the rates in `as_of`, the `source` and a `note`. `convert` is the default operation, so `op` can be left out. Add `date` to convert at a historical rate.

**Method:** `GET`

**Endpoint:** `/v1/market/fx?op=convert`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `op` | query | Operation to run: `convert` or `rates`. | string | No | `convert` | - |
| `from` | query | Currency to convert from, as an ISO 4217 code (for example `USD`). Set it for `op=convert`. | string | No | - | - |
| `to` | query | Currency to convert to, as an ISO 4217 code (for example `GBP`). Set it for `op=convert`. | string | No | - | - |
| `amount` | query | Amount to convert. | number | No | `1` | 1e12 |
| `date` | query | Date of the rates, `YYYY-MM-DD`, within the last 90 days. A weekend or holiday maps to the previous publication day. | string | No | Latest rates | 90 days back |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/leadharbor/currency-converter/v1/market/fx?op=convert&from=USD&to=GBP&amount=100" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "from": "USD",
  "to": "GBP",
  "amount": 100,
  "rate": 0.749247,
  "result": 74.9247,
  "as_of": "2026-10-20",
  "source": "European Central Bank euro foreign exchange reference rates, https://www.ecb.europa.eu/stats/eurofxref/",
  "note": "Reference rates published once per working day (around 16:00 CET); not tradable quotes.",
  "meta": {
    "user": null,
    "stale": false
  }
}
```

**Example Request (historical rate):**

```bash
curl -X GET "https://prod.api.market/api/v1/leadharbor/currency-converter/v1/market/fx?op=convert&from=EUR&to=JPY&amount=50&date=2026-10-16" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "from": "EUR",
  "to": "JPY",
  "amount": 50,
  "rate": 177.82,
  "result": 8891,
  "as_of": "2026-10-16",
  "source": "European Central Bank euro foreign exchange reference rates, https://www.ecb.europa.eu/stats/eurofxref/",
  "note": "Reference rates published once per working day (around 16:00 CET); not tradable quotes.",
  "meta": {
    "user": null,
    "stale": false
  }
}
```

**Response fields:**

| Field | Type | Description |
|---|---|---|
| `from` | string | The source currency. |
| `to` | string | The target currency. |
| `amount` | number | The amount you sent. |
| `rate` | number | Units of `to` per one unit of `from`. |
| `result` | number | `amount` multiplied by `rate`. |
| `as_of` | string | The ECB publication date of the rates used. |
| `source` | string | Where the rates come from. |
| `note` | string | A reminder that these are daily reference rates, not tradable quotes. |
| `meta` | object | `stale` is `true` when a cached table was served because the ECB file was unreachable. `user` is metadata that you can ignore. |

#### 2. Get exchange rates (op=rates)

Returns the full rate table against a base currency, with the date of the rates in `as_of`, the `source` and a `note`. Each value in `rates` is the number of units of that currency per one unit of `base`. Add `date` to get the table for a past day.

**Method:** `GET`

**Endpoint:** `/v1/market/fx?op=rates`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `op` | query | Set to `rates`. | string | Yes | - | - |
| `base` | query | Base currency for the table, as an ISO 4217 code. | string | No | `EUR` | - |
| `date` | query | Date of the rates, `YYYY-MM-DD`, within the last 90 days. A weekend or holiday maps to the previous publication day. | string | No | Latest rates | 90 days back |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/leadharbor/currency-converter/v1/market/fx?op=rates&base=EUR" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "base": "EUR",
  "as_of": "2026-10-20",
  "rates": {
    "AUD": 1.6056,
    "BRL": 5.6339,
    "CAD": 1.5758,
    "CHF": 0.9237,
    "CNY": 7.4894,
    "CZK": 24.329,
    "DKK": 7.4746,
    "EUR": 1,
    "GBP": 0.84028,
    "HKD": 8.8023,
    "HUF": 364.68,
    "IDR": 20170.6,
    "ILS": 3.4853,
    "INR": 106.459,
    "ISK": 136.2,
    "JPY": 177.34,
    "KRW": 1489.17,
    "MXN": 20.7719,
    "MYR": 4.5788,
    "NOK": 10.5245,
    "NZD": 1.9748,
    "PHP": 70.804,
    "PLN": 4.3768,
    "RON": 5.3308,
    "SEK": 11.123,
    "SGD": 1.4338,
    "THB": 37.738,
    "TRY": 55.6009,
    "USD": 1.1215,
    "ZAR": 18.4769
  },
  "source": "European Central Bank euro foreign exchange reference rates, https://www.ecb.europa.eu/stats/eurofxref/",
  "note": "Reference rates published once per working day (around 16:00 CET); not tradable quotes.",
  "meta": {
    "user": null,
    "stale": false
  }
}
```

The `rates` object above lists every currency the API supports: AUD, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HUF, IDR, ILS, INR, ISK, JPY, KRW, MXN, MYR, NOK, NZD, PHP, PLN, RON, SEK, SGD, THB, TRY, USD and ZAR.

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The conversion or rate table was returned. Check `meta.stale` to see whether a cached table was used. |
| 400 | Bad Request | A currency is not published by the ECB (for example the Omani rial), the amount is not a number or is out of range, or the date is badly formatted or older than 90 days. The message names the field, and an unsupported currency error lists the supported codes. |
| 401 | Unauthorized | The `x-api-market-key` value is invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | The path is wrong. Check that you are calling `/v1/market/fx` under the base URL. |
| 429 | Too Many Requests | You went over 10 requests per second, or you have used all the calls in your plan. |
| 500 | Internal Server Error | Something failed while processing the request. Retry after a short delay. |
| 502 | Bad Gateway | The ECB rate file is unavailable and no cached table is held. Retry later. |

## Rate Limits

The Free trial, Starter and PAYG plans each allow 10 requests per second. The Free trial is a 7-day trial with 500 calls and a hard stop, Starter includes 10,000 calls with extra calls billed at $0.001 each, and PAYG bills $0.001 per call with no subscription. Requests above the per-second limit, or after the Free trial's calls are used up, return `429 Too Many Requests`. Back off before retrying and honour the `Retry-After` header, which says how many seconds to wait. The ECB publishes new rates once per working day, so if you convert many amounts it is cheaper to call `op=rates` once and cache the table until the next publication.

## FAQ

**Are these live or tradable exchange rates?**

No. They are the ECB euro foreign exchange reference rates, published once per working day around 16:00 CET. They suit invoicing, reporting and price display, not trading. Every response says so in `note`.

**Which currencies are supported?**

The currencies the ECB publishes, about 30: AUD, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HUF, IDR, ILS, INR, ISK, JPY, KRW, MXN, MYR, NOK, NZD, PHP, PLN, RON, SEK, SGD, THB, TRY, USD and ZAR. A currency the ECB does not publish returns `400` with the supported list.

**How do I get a historical rate?**

Add `date=YYYY-MM-DD` to either operation, for any day in the last 90 days. If the date is a weekend or a holiday, the rates from the previous publication day are used, and `as_of` shows that day.

**Why is `as_of` earlier than today?**

The ECB publishes once per working day, around 16:00 CET. Before that time, and on weekends and holidays, the latest available rates are from the previous publication day.

**What does `meta.stale` mean?**

It is `true` when the ECB file could not be reached and the API served a cached table up to 48 hours old. When it is `false`, the rates were read from the current ECB file. If the file is unreachable and nothing is cached, the API returns `502`.

**How are rates between two non-euro currencies calculated?**

The ECB publishes every rate against the euro. For a pair such as USD to GBP, the API divides the two euro rates, so the result matches the ECB reference rates for that day.

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


Currency converter API using ECB reference rates: convert amounts or get rate tables for 30 currencies, with the rate date, source and 90 days of history.

Currency Converter API with ECB Exchange Rates

Free trial