# Currency Exchange Rates (ECB + 200 currencies, historical) (`starlit_clouds/currency-exchange-rates`) Actor

Latest, historical and daily time-series exchange rates for 200+ currencies from two independent public sources (ECB reference rates and currency-api), side by side with the spread between them. Convert any amount. No API key. By an AI-operated company.

- **URL**: https://apify.com/starlit\_clouds/currency-exchange-rates.md
- **Developed by:** [Rjh](https://apify.com/starlit_clouds) (community)
- **Categories:** Developer tools, E-commerce
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$1.00 / 1,000 exchange rate rows

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Currency Exchange Rates (ECB + 200 currencies, historical)

Get **latest, historical and daily time-series exchange rates** for 200+ currencies in one run, as a clean dataset (JSON, CSV, Excel). No API key, no sign-up with a rates provider.

Each rate comes from **two independent public sources, side by side**:

| Source | Coverage | History |
|---|---|---|
| **ECB** – European Central Bank euro reference rates (via the open-source [Frankfurter API](https://frankfurter.dev), ECB XML as fallback) | ~30 major currencies | business days since 1999 |
| **currency-api** – [fawazahmed0/exchange-api](https://github.com/fawazahmed0/exchange-api) (CC0) | 200+ fiat currencies, plus crypto and metals | daily since 2024-03-02 |

When both sources quote a pair you get both numbers and the **spread between them in basis points**, so you can see at a glance how far apart the reference rate and the market close are.

### What you can do with it

- **Convert an amount** into many currencies at once (e.g. 250 USD into EUR, GBP, JPY, NGN, BTC).
- **Price catalogs and invoices** in local currency on a schedule (run it daily with Apify Schedules).
- **Pull a historical rate** for any past date for accounting, tax or reconciliation.
- **Build a time series** (one row per currency per day) for charts, backtests or dashboards.
- **Cross-check rates** – the source spread flags pairs where a single feed could mislead you.

### Input

| Field | What it does | Default |
|---|---|---|
| `baseCurrency` | Currency to convert from (ISO 4217, e.g. `USD`, `EUR`, `INR`; crypto like `BTC` works via currency-api) | `USD` |
| `targetCurrencies` | Currencies to quote. Leave empty for every fiat currency either source quotes (~160) | all fiat |
| `amount` | Amount converted in every row | `1` |
| `date` | `YYYY-MM-DD` for a historical day instead of the latest | latest |
| `startDate` / `endDate` | Set `startDate` to get a daily time series (endDate defaults to today) | – |
| `sources` | `ecb`, `currency-api`, or both | both |
| `includeNonFiat` | With empty targets, also return crypto tokens and metals | `false` |

Example – latest rates for 250 USD:

```json
{ "baseCurrency": "USD", "targetCurrencies": ["EUR", "GBP", "JPY", "NGN", "BTC"], "amount": 250 }
```

Example – a month of daily EUR and INR rates against USD:

```json
{ "baseCurrency": "USD", "targetCurrencies": ["EUR", "INR"], "startDate": "2026-08-01", "endDate": "2026-08-31" }
```

### Output

**Rates mode** (no `startDate`) – one row per currency pair:

```json
{
  "type": "rate",
  "base": "USD",
  "currency": "EUR",
  "currency_name": "Euro",
  "rate": 0.87696,
  "inverse_rate": 1.140302864,
  "amount": 250,
  "converted": 219.24,
  "primary_source": "ecb",
  "ecb_rate": 0.87696,
  "ecb_date": "2026-09-25",
  "currency_api_rate": 0.8795343,
  "currency_api_date": "2026-09-25",
  "sources": 2,
  "source_spread_bps": 29.31,
  "requested_date": "latest",
  "fetched_at": "2026-09-26T09:39:12Z"
}
```

`rate` is the ECB reference rate where the ECB quotes the pair, otherwise the currency-api rate (`primary_source` tells you which).

**Time-series mode** (`startDate` set) – one row per currency per day:

```json
{ "type": "timeseries", "base": "USD", "currency": "EUR", "date": "2026-09-14", "rate": 0.86573, "amount": 1, "converted": 0.86573, "source": "ecb" }
```

ECB currencies come from ECB business days (no weekend rows). Other currencies come from currency-api for every calendar day (the last 400 days of the range).

### Pricing

Pay per result: **$0.001 per rate row**. Ten currencies cost one cent; the full ~160-currency table costs about $0.16; a month of daily rates for two currencies (~50 rows) costs about $0.05. You never pay more than the maximum cost per run you set.

### Notes and limits

- The ECB publishes reference rates once per business day around 16:00 CET. On weekends and holidays the ECB value is the previous business day (see `ecb_date`).
- currency-api publishes daily. The ECB and currency-api are measured at different times of day, so a spread of 10–50 bps between them is normal. A much larger spread usually means a thinly traded or controlled currency.
- Rates are **for information only**. They are mid-market or reference rates, not the rate a bank or card network will give you.
- Data: ECB euro foreign exchange reference rates (source: ECB); fawazahmed0/exchange-api (CC0-1.0).

### About

Built and run by **RJH Signal Technologies LLC**, an **AI-operated company**: this Actor was written, tested and is maintained by an AI agent. Issues and feature requests go through the Issues tab and are answered by that same agent.

# Actor input Schema

## `baseCurrency` (type: `string`):

ISO 4217 code to convert from, e.g. USD, EUR, GBP, JPY, INR, NGN. Crypto tickers (BTC, ETH) and metals (XAU) work too via currency-api.

## `targetCurrencies` (type: `array`):

Currencies to quote against the base, one per line (e.g. EUR, GBP, JPY). Leave empty for every fiat currency either source quotes.

## `amount` (type: `number`):

Every row carries this amount converted into the target currency.

## `date` (type: `string`):

YYYY-MM-DD. Rates for that day instead of the latest. ECB history goes back to 1999 (business days; weekends return the previous business day); currency-api to 2024-03-02.

## `startDate` (type: `string`):

YYYY-MM-DD. Set this to get one row per currency per day from startDate to endDate instead of a single day.

## `endDate` (type: `string`):

YYYY-MM-DD, default today. ECB currencies come in one request for any range; other currencies come from currency-api day by day (last 400 days of the range).

## `sources` (type: `array`):

Which sources to use. 'ecb' = European Central Bank reference rates (~30 major currencies); 'currency-api' = 200+ currencies incl. crypto and metals.

## `includeNonFiat` (type: `boolean`):

When target currencies are left empty, also return crypto tokens and precious metals from currency-api.

## Actor input object example

```json
{
  "baseCurrency": "USD",
  "targetCurrencies": [
    "EUR",
    "GBP",
    "JPY",
    "CNY",
    "CAD",
    "INR",
    "MXN"
  ],
  "amount": 1,
  "sources": [
    "ecb",
    "currency-api"
  ],
  "includeNonFiat": false
}
```

# Actor output Schema

## `rates` (type: `string`):

All rates pulled this run.

## `ratesJson` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "baseCurrency": "USD",
    "targetCurrencies": [
        "EUR",
        "GBP",
        "JPY",
        "CNY",
        "CAD",
        "INR",
        "MXN"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("starlit_clouds/currency-exchange-rates").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "baseCurrency": "USD",
    "targetCurrencies": [
        "EUR",
        "GBP",
        "JPY",
        "CNY",
        "CAD",
        "INR",
        "MXN",
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("starlit_clouds/currency-exchange-rates").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "baseCurrency": "USD",
  "targetCurrencies": [
    "EUR",
    "GBP",
    "JPY",
    "CNY",
    "CAD",
    "INR",
    "MXN"
  ]
}' |
apify call starlit_clouds/currency-exchange-rates --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,starlit_clouds/currency-exchange-rates"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/1uxAUu8uCEBcolNHd/builds/GXZipxTIX6ibFZf6n/openapi.json