# Currency Exchange Rates: Live, Historical, Convert (`apizilla/currency-exchange-rates-api`) Actor

Get live and past exchange rates for 340 currencies and crypto. Convert amounts in bulk, get daily rates for any date range since 1999, and compare sources. Uses official ECB rates, daily community rates and optional live Google Finance rates. Works as a batch run or a live HTTP API.

- **URL**: https://apify.com/apizilla/currency-exchange-rates-api.md
- **Developed by:** [APIzilla](https://apify.com/apizilla) (community)
- **Categories:** Developer tools, Business, Integrations
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 rate fetcheds

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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 API: Live, Historical, Convert

Get exchange rates for 340 currencies and crypto coins. Convert many amounts in one run. Get rates for any past day since 1999. Get daily rates between two dates. Compare rates from more than one source.

You can use it in two ways:

- **Batch run.** Fill in the input, click Start, and get a table of results.
- **Live API (Standby).** Call a web address from your app and get JSON back in under a second.

### What you can do

| Operation | What it does | Price event |
|---|---|---|
| `latest` | Latest rates from one base currency to many target currencies. | `rate-fetched` per pair |
| `convert` | Convert a list of amounts. Each item can have its own date. | `conversion` per amount |
| `historical` | Rates on one past day. | `historical-rate` per pair |
| `timeseries` | One rate per day between two dates. | `timeseries-day` per day and pair |
| `crosscheck` | Gets the same pair from ECB, community rates and Google, and shows how far apart they are. | `cross-check` per pair |
| `currencies` | List of all codes, names and how far back history goes. | Free |

Rates from the Google source cost a small extra fee per rate (`google-live-rate`). See Costs and limits below for all prices.

### Data sources

| Source | Currencies | How fresh | History | Notes |
|---|---|---|---|---|
| `ecb` | 30 main currencies (USD, EUR, GBP, JPY, CHF, CNY and more) | Once per working day, around 16:00 CET | Since 4 January 1999 | Official reference rates of the European Central Bank. We read them through the free Frankfurter service. If it is down, we read the ECB files directly. |
| `community` | 340 currencies and crypto coins | Once per day | Since 2 March 2024 | Free open data from the fawazahmed0 exchange-api project. Good for currencies the ECB does not cover, like NGN, AED, PKR, BTC and ETH. |
| `google` | Most currency pairs and big crypto coins | Live, a few minutes old | No history | Read from public Google Finance pages. Not an official feed. It can stop working if Google changes its pages or blocks requests. |
| `auto` (default) | All of the above | | | Uses the ECB when it has both currencies. Uses community rates for the rest. If the ECB source fails, it falls back to community rates. |

All rates are mid-market rates. They are not the buy or sell price of a bank. Do not use them for trading.

### Input examples

Latest rates:

```json
{
  "operation": "latest",
  "base": "USD",
  "targets": ["EUR", "GBP", "JPY", "NGN", "BTC"]
}
```

Convert amounts in bulk:

```json
{
  "operation": "convert",
  "conversions": [
    { "amount": 100, "from": "USD", "to": "EUR" },
    { "amount": 2500, "from": "GBP", "to": "JPY", "date": "2024-06-28", "id": "invoice-17" }
  ]
}
```

Rates on a past day:

```json
{ "operation": "historical", "base": "EUR", "targets": ["USD", "CHF"], "date": "2008-09-15" }
```

Daily rates between two dates:

```json
{ "operation": "timeseries", "base": "USD", "targets": ["EUR"], "startDate": "2025-01-01", "endDate": "2025-03-31" }
```

Live rates from Google:

```json
{ "operation": "latest", "base": "USD", "targets": ["EUR", "INR"], "source": "google" }
```

### Output

Each result is one row in the dataset. Example:

```json
{
  "operation": "convert",
  "status": "succeeded",
  "from": "USD",
  "to": "EUR",
  "amount": 100,
  "result": 89.246,
  "rate": 0.89246,
  "inverseRate": 1.120498398,
  "rateDate": "2026-10-22",
  "requestedDate": null,
  "source": "ecb",
  "sourceName": "European Central Bank reference rates",
  "backupUsed": false,
  "fetchedAt": "2026-10-22T15:56:16Z",
  "message": "",
  "charged": { "conversion": 1 }
}
```

- `rate`: how many units of `to` you get for 1 unit of `from`.
- `rateDate`: the day of the rate. On weekends and holidays the ECB does not publish rates. Then you get the last rate before that day, and `message` says so.
- `status`: `succeeded` or `failed`. A failed row has a clear `message`, for example an unknown code or a date that is too old.
- Google rows also have `quoteTime`, `previousClose` and `changePercent`.
- Cross-check rows have `rates` (one rate per source), `spreadPercent` and `sourcesAgree` (true when the sources are within 1%).

A short run summary is saved in the key-value store under the key `SUMMARY`.

### Live API (Standby mode)

The actor can also run as a web API. You do not need to start it. Just call the address shown on the Endpoints tab and add your Apify token.

```
curl -H "Authorization: Bearer YOUR_APIFY_TOKEN" \
  "https://ACTOR-ADDRESS.apify.actor/latest?base=USD&symbols=EUR,GBP"
```

| Endpoint | Example |
|---|---|
| `GET /latest` | `/latest?base=USD&symbols=EUR,GBP&source=auto` |
| `GET /convert` | `/convert?from=USD&to=EUR&amount=100&date=2024-05-02` |
| `POST /convert` | Body: `{"conversions": [{"amount": 100, "from": "USD", "to": "EUR"}]}`. Up to 1,000 items. |
| `GET /historical` | `/historical?date=2020-03-02&base=USD&symbols=EUR,JPY` |
| `GET /timeseries` | `/timeseries?base=USD&symbols=EUR&start=2025-01-01&end=2025-01-31` |
| `GET /crosscheck` | `/crosscheck?base=USD&symbols=EUR,GBP` |
| `GET /currencies` | `/currencies` (free) |

The answer is JSON with `ok`, `results` (the same rows as above) and `charged`. Bad input gives HTTP 400 with an `error` text.

Prices per result are the same as in batch runs. In Standby mode you also pay the small platform cost of the server while it is running. It stops by itself after a short time with no requests.

### Costs and limits

You pay per result. Prices:

| Event | When you pay | Price | Per 1,000 |
|---|---|---|---|
| `rate-fetched` | One latest rate for one pair | $0.001 | $1.00 |
| `conversion` | One amount converted | $0.001 | $1.00 |
| `historical-rate` | One pair on one past date | $0.0015 | $1.50 |
| `timeseries-day` | One day of one pair in a time series | $0.0002 | $0.20 |
| `cross-check` | One pair compared across sources | $0.003 | $3.00 |
| `google-live-rate` | Extra fee for each rate from the Google source | $0.002 | $2.00 |
| Actor start | Once per run (Apify default) | $0.00005 | $0.05 |

The `currencies` operation is free. Examples: 1,000 conversions cost $1.00. One year of daily USD to EUR rates (about 255 days) costs about $0.05. One live Google rate costs $0.003 in total.

- You only pay for rows that succeed. Failed rows are free.
- Set "Max cost per run" in the run options. The actor stops before it goes over.
- `maxResults` limits the number of rows in one run.
- A time series with community rates can be up to 400 days per pair. With ECB rates there is no practical limit.
- The Google source is live but not official. Use `auto` or `ecb` when you need stable, official numbers.

### Good to know

- Codes are not case sensitive. `usd` and `USD` both work.
- Crypto codes like BTC, ETH and SOL come from the community source or Google.
- ECB rates are rounded to 4 or 5 digits. Community rates have more digits.
- Data from the ECB and Frankfurter is free to reuse. Community rates are public domain (CC0). Google Finance data is for information only.

# Actor input Schema

## `operation` (type: `string`):

What you want to get.

## `base` (type: `string`):

The currency you convert from. Example: USD. Used by latest, historical, timeseries and crosscheck.

## `targets` (type: `array`):

The currencies you convert to. One code per line. Example: EUR, GBP, JPY, BTC. For latest and historical, leave empty to get all 30 ECB currencies.

## `conversions` (type: `array`):

Only for convert. A list of amounts to convert. Each item: {"amount": 100, "from": "USD", "to": "EUR"}. You can add "date" (YYYY-MM-DD) for a past rate and "id" to match rows to your data.

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

For historical: the day you want, like 2020-03-02. For convert: a default date for items with no date. Leave empty for the latest rates.

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

Only for timeseries. First day, like 2025-01-01.

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

Only for timeseries. Last day. Leave empty for today.

## `source` (type: `string`):

Auto uses official ECB rates for the 30 main currencies and daily community rates for all others. Google gives live rates and costs a bit more.

## `maxResults` (type: `integer`):

Stop after this many rows. This keeps your cost under control.

## `proxyConfiguration` (type: `object`):

Only used for the Google source and crosscheck. Usually not needed. Turn it on if Google blocks your runs.

## Actor input object example

```json
{
  "operation": "latest",
  "base": "USD",
  "targets": [
    "EUR",
    "GBP",
    "JPY"
  ],
  "conversions": [
    {
      "amount": 100,
      "from": "USD",
      "to": "EUR"
    },
    {
      "amount": 2500,
      "from": "GBP",
      "to": "JPY",
      "date": "2024-06-28"
    }
  ],
  "source": "auto",
  "maxResults": 1000
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `summary` (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 = {
    "operation": "latest",
    "base": "USD",
    "targets": [
        "EUR",
        "GBP",
        "JPY"
    ],
    "conversions": [
        {
            "amount": 100,
            "from": "USD",
            "to": "EUR"
        },
        {
            "amount": 2500,
            "from": "GBP",
            "to": "JPY",
            "date": "2024-06-28"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("apizilla/currency-exchange-rates-api").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 = {
    "operation": "latest",
    "base": "USD",
    "targets": [
        "EUR",
        "GBP",
        "JPY",
    ],
    "conversions": [
        {
            "amount": 100,
            "from": "USD",
            "to": "EUR",
        },
        {
            "amount": 2500,
            "from": "GBP",
            "to": "JPY",
            "date": "2024-06-28",
        },
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("apizilla/currency-exchange-rates-api").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 '{
  "operation": "latest",
  "base": "USD",
  "targets": [
    "EUR",
    "GBP",
    "JPY"
  ],
  "conversions": [
    {
      "amount": 100,
      "from": "USD",
      "to": "EUR"
    },
    {
      "amount": 2500,
      "from": "GBP",
      "to": "JPY",
      "date": "2024-06-28"
    }
  ]
}' |
apify call apizilla/currency-exchange-rates-api --silent --output-dataset

```

## MCP server setup

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

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/hXJWnfETVFalzZfax/builds/tGCbn4aUWMyyxDiDJ/openapi.json