# Currency Rates — History Since 1999 and 166 Latest (`xtracto/currency-rates`) Actor

Exchange rates with real history: ECB reference data back to 1999 for 30 currencies, plus latest rates for 166. Weekend gaps and range quirks handled honestly. Keyless, HTTP-only.

- **URL**: https://apify.com/xtracto/currency-rates.md
- **Developed by:** [Farhan Febrian Nauval](https://apify.com/xtracto) (community)
- **Categories:** Other
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.33 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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 Rates — History Since 1999, 166 Currencies Latest

Get daily exchange rates for any base currency: full history back to 1999 for 30 major currencies, or today's rates for 166 currencies.

### Why use this actor

- **No account, no login, no API key.** Pick a base currency and run.
- **Real history.** Official European Central Bank reference rates for 30 currencies, every trading day since 1999-01-04.
- **Wide latest coverage.** Today's rates for 166 currencies, including ones the ECB does not publish (VND, NGN, ARS…).
- **Both directions in one row.** `rate` and `inverseRate`, plus `base` and `symbol` as separate columns for easy pivoting.
- **Every row says where it came from** (`_source`), so you always know which data set served it.
- **Stable JSON output** ready for spreadsheets, databases or price conversion in other pipelines. Export to JSON, CSV or Excel.

### How it works

1. You choose a base currency and, optionally, the target currencies (empty = all).
2. Set a **start date** to get a daily history, or leave it empty to get the latest rates.
3. History and latest rates for ECB currencies come from ECB reference data; latest rates for other currencies come from a wider public rates source.
4. You get one row per date and currency pair.

Currencies and dates are checked before anything is fetched, so a typo gets a clear message instead of an empty dataset. Nothing to install or maintain.

### Input

**Latest rates:**

```json
{
  "baseCurrency": "USD",
  "targetCurrencies": ["EUR", "GBP", "IDR", "JPY"]
}
```

**History:**

```json
{
  "baseCurrency": "USD",
  "targetCurrencies": ["EUR", "IDR"],
  "startDate": "2024-01-02",
  "endDate": "2024-01-04"
}
```

| Field | Type | Description |
|---|---|---|
| `baseCurrency` | string | Three-letter code, such as `USD`. Each rate is what one unit of this buys. Required. |
| `targetCurrencies` | array of strings | Currencies to quote. Leave empty for every currency available. |
| `startDate` | string | `YYYY-MM-DD`. Setting it switches to history (30 ECB currencies, back to 1999-01-04). Leave empty for latest rates. |
| `endDate` | string | `YYYY-MM-DD`. Leave empty to run to the most recent published rate. |

### Output

One row per date and currency pair. Real output from local runs.

**Latest rates, ECB currencies** (first input above, 2 of 4 rows):

```json
[
  {
    "_input": "USD",
    "_source": "S1-frankfurter-ecb",
    "_scrapedAt": "2026-11-11T13:14:01Z",
    "date": "2026-11-10",
    "base": "USD",
    "symbol": "EUR",
    "rate": 0.89174,
    "inverseRate": 1.1214031,
    "pair": "USD/EUR",
    "amount": 1.0
  },
  {
    "_input": "USD",
    "_source": "S1-frankfurter-ecb",
    "_scrapedAt": "2026-11-11T13:14:01Z",
    "date": "2026-11-10",
    "base": "USD",
    "symbol": "IDR",
    "rate": 18062,
    "inverseRate": 5.536e-05,
    "pair": "USD/IDR",
    "amount": 1.0
  }
]
```

**Latest rates including a non-ECB currency** (`"targetCurrencies": ["EUR", "VND"]`):

```json
[
  {
    "_input": "USD",
    "_source": "S2-open-er-api",
    "_scrapedAt": "2026-11-11T13:15:56Z",
    "date": "2026-11-11",
    "base": "USD",
    "symbol": "EUR",
    "rate": 0.893927,
    "inverseRate": 1.11865958,
    "pair": "USD/EUR",
    "amount": 1.0
  },
  {
    "_input": "USD",
    "_source": "S2-open-er-api",
    "_scrapedAt": "2026-11-11T13:15:56Z",
    "date": "2026-11-11",
    "base": "USD",
    "symbol": "VND",
    "rate": 25608.244657,
    "inverseRate": 3.905e-05,
    "pair": "USD/VND",
    "amount": 1.0
  }
]
```

**History** (second input above, 2 of 6 rows):

```json
[
  {
    "_input": "USD",
    "_source": "S1-frankfurter-ecb",
    "_scrapedAt": "2026-11-11T13:14:10Z",
    "date": "2024-01-02",
    "base": "USD",
    "symbol": "EUR",
    "rate": 0.91274,
    "inverseRate": 1.09560225,
    "pair": "USD/EUR",
    "amount": 1.0
  },
  {
    "_input": "USD",
    "_source": "S1-frankfurter-ecb",
    "_scrapedAt": "2026-11-11T13:14:10Z",
    "date": "2024-01-02",
    "base": "USD",
    "symbol": "IDR",
    "rate": 15524,
    "inverseRate": 6.442e-05,
    "pair": "USD/IDR",
    "amount": 1.0
  }
]
```

| Field | Type | Description |
|---|---|---|
| `date` | string | The trading day the rate was published for |
| `pair` | string | The pair, such as `USD/EUR` |
| `base`, `symbol` | string | Base and target currency, as separate columns |
| `rate` | number | What one unit of the base currency buys |
| `inverseRate` | number | The reverse: one unit of the target in the base currency |
| `amount` | number | The base amount quoted (always 1) |
| `_source` | string | `S1-frankfurter-ecb` (ECB reference data) or `S2-open-er-api` (wider latest rates) |
| `_input`, `_scrapedAt` | string | The base currency requested and the time of the run |

### Notes

- **Weekends and holidays are absent, and that is correct.** No rate is published when markets are closed, so 2024-01-04 to 2024-01-09 returns the 4th, 5th, 8th and 9th. Nothing is carried forward to fill the gaps.
- **No phantom rows at the start of a range.** A range that starts on a weekend returns only dates inside your window.
- **History covers the 30 ECB currencies only.** Ask for history on another currency (VND, NGN, ARS…) and the run stops with a message listing every covered currency. Leave `startDate` empty and the same currency works for latest rates.
- **When any target is outside the ECB set, latest rates for the whole request come from the wider source**, as in the VND example above; `_source` on each row tells you which.
- **Error rows** carry an `_error` code: `no_rates` (the source answered without rates), `not_found` (nothing published for that date), `source_unavailable` (the source did not answer after retries).
- Useful alongside ecommerce actors such as **Shopify Products** or **Amazon Products**, where prices arrive in the local currency.

# Actor input Schema

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

Three-letter code. One unit of this is what each rate is quoted against.

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

Leave empty for every currency the source offers.

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

YYYY-MM-DD. Setting this switches to historical mode, which uses ECB reference data — 30 currencies, back to 1999-01-04. Leave empty for latest rates, which cover 166 currencies.

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

YYYY-MM-DD. Leave empty to run to the most recent published rate.

## Actor input object example

```json
{
  "baseCurrency": "USD",
  "targetCurrencies": [
    "EUR",
    "GBP",
    "IDR",
    "JPY"
  ]
}
```

# Actor output Schema

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

One row per scraped record, stored in the run's default dataset.

# 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",
        "IDR",
        "JPY"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("xtracto/currency-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",
        "IDR",
        "JPY",
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("xtracto/currency-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",
    "IDR",
    "JPY"
  ]
}' |
apify call xtracto/currency-rates --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,xtracto/currency-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/yfJJk0YqtcK8IFQsN/builds/L76yoeXN894tBR7rr/openapi.json
