# Currency Converter (`pintostudio/currency-converter`) Actor

Convert currencies & compare live rates, free by default (Frankfurter, open.er-api.com). Optional support for your own exchangeratesapi.io, fixer.io, openexchangerates.org or currencylayer.com key. Multi-currency, historical dates, source comparison.

- **URL**: https://apify.com/pintostudio/currency-converter.md
- **Developed by:** [Pinto Studio](https://apify.com/pintostudio) (community)
- **Categories:** Integrations
- **Stats:** 2 total users, 0 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.00 / 1,000 results

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 Converter & Live Exchange Rate API

Convert currencies and compare live exchange rates with a free, no-signup Apify Actor and API. Works out of the box using free sources (**Frankfurter/ECB** and **open.er-api.com**), and can also pull rates from your own **exchangeratesapi.io**, **fixer.io**, **openexchangerates.org** or **currencylayer.com** account. Use it as a one-off Actor run, a scheduled Task, a REST API, or a tool for AI agents via the Apify MCP server.

### What does Currency Converter do?

Currency Converter turns a `from` currency, one or more `to` currencies, and an `amount` into up-to-date converted values and exchange rates. It supports:

- Single or multi-currency conversion (`to` accepts one currency or a list, e.g. `["EUR", "GBP", "JPY"]`).
- Historical rates for any past date, alongside the latest rate.
- A `compareSources` mode that queries every available provider at once and returns the best, worst and spread between them.
- Six interchangeable rate providers, with automatic fallback when the default free sources are unavailable.
- A live HTTP API (Standby mode) for on-demand conversions with no cold start, in addition to normal Actor runs.

### Why use this instead of a single free API?

Public exchange-rate APIs each have gaps: Frankfurter only covers ECB currencies, open.er-api.com has no historical data, and the free tiers of exchangeratesapi.io, fixer.io, openexchangerates.org and currencylayer.com all force a fixed base currency (EUR or USD) that doesn't match what you actually asked for. This Actor normalizes all of that: it computes correct cross-rates for any `from`/`to` pair regardless of a provider's base-currency restriction, and falls back automatically between free sources so a single outage doesn't break your pipeline.

### Input parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | string | Yes | 3-letter source currency code, e.g. `USD`. |
| `to` | string or array | Yes | One target currency code, or a list of codes, e.g. `["EUR", "GBP"]`. |
| `amount` | string/number | No (default `1`) | Amount to convert. |
| `date` | string | No | Historical date as `YYYY-MM-DD`. Omit for the latest rate. |
| `source` | string | No (default `auto`) | `auto`, `frankfurter`, `open_er_api`, `exchangeratesapi`, `fixer`, `openexchangerates` or `currencylayer`. |
| `compareSources` | boolean | No | When `true`, queries every provider you have access to and returns the best, worst and spread. |
| `apiKey` | string (secret) | No | Your own API key, required only for exchangeratesapi.io, fixer.io, openexchangerates.org or currencylayer.com. |

### Example input

```json
{
  "from": "USD",
  "to": ["EUR", "GBP"],
  "amount": "100",
  "compareSources": true
}
```

### Example output (dataset item)

```json
{
  "from": "USD",
  "to": "EUR",
  "amount": 100,
  "convertedAmount": 86.27,
  "rate": 0.8627,
  "source": "frankfurter",
  "sourceLabel": "Frankfurter (ECB)",
  "date": "latest",
  "mode": "single",
  "fetchedAt": "2026-09-14T09:01:22.700Z"
}
```

Every run also writes a run summary to the key-value store under the `OUTPUT` key, and each dataset item follows the published [dataset schema](https://docs.apify.com/platform/actors/development/actor-definition/dataset-schema), so results render as a clean table in Apify Console and in any tool that reads Apify's Actor output schema.

### Ready-made Tasks

This Actor ships with pre-configured [Apify Tasks](https://docs.apify.com/platform/actors/running/tasks) you can run immediately or trigger via the API without writing any input JSON yourself:

- **Quick USD to EUR Conversion** – convert 100 USD to EUR using the best free live rate.
- **Compare All Rate Sources** – convert USD to EUR, GBP and JPY and compare every available provider.
- **Multi-Currency Basket from EUR** – convert 1000 EUR into USD, GBP, JPY, CHF and CAD in one run.
- **Historical Rate Lookup** – look up the USD/EUR rate for a specific past date.

### Run it with the Apify API (curl)

```bash
curl "https://api.apify.com/v2/acts/pintostudio~currency-converter/run-sync-get-dataset-items?token=<YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"from": "USD", "to": ["EUR", "GBP"], "amount": "100"}'
```

### Live HTTP API (Standby mode)

This Actor also runs as an always-on web server ([Standby mode](https://docs.apify.com/platform/actors/running/standby)), so you can call it like a normal REST API without starting a new run each time:

```bash
curl "https://pintostudio--currency-converter.apify.actor/convert?from=USD&to=EUR&amount=100"
```

```bash
curl "https://pintostudio--currency-converter.apify.actor/convert?from=USD&to=EUR,GBP,JPY&amount=100&compareSources=true"
```

The endpoint, parameters and response shape are fully described by the Actor's published [OpenAPI schema](https://docs.apify.com/platform/actors/development/actor-definition/web-server-schema), so any OpenAPI-aware client or code generator can consume it directly.

### Use it from AI agents (MCP)

Currency Converter can be called by Claude, ChatGPT and other MCP-compatible agents through the [Apify MCP Server](https://docs.apify.com/platform/integrations/mcp), so an agent can convert currencies or fetch live rates as one of its tools instead of guessing at exchange rates from memory:

```json
{
  "mcpServers": {
    "apify": {
      "command": "npx",
      "args": ["-y", "@apify/actors-mcp-server", "--actors", "pintostudio/currency-converter"],
      "env": {
        "APIFY_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}
```

### Frequently asked questions

#### Is this currency converter free to use?

Yes. The default `auto` source uses Frankfurter (ECB) and open.er-api.com, both free with no API key and no signup. You only need an API key if you explicitly choose `exchangeratesapi`, `fixer`, `openexchangerates` or `currencylayer` as the `source`.

#### How many currencies does it support?

Frankfurter and open.er-api.com together cover over 160 world currencies. Coverage for a specific pair depends on the provider: Frankfurter is limited to major/ECB-tracked currencies, while open.er-api.com covers a much wider set, which is why `auto` mode tries Frankfurter first and falls back to open.er-api.com.

#### Can I get historical exchange rates, not just the latest?

Yes. Pass a `date` in `YYYY-MM-DD` format and the Actor returns the rate for that day instead of the latest rate. This works with the free `auto` source as well as the named providers.

#### What does `compareSources` do?

When `compareSources` is `true`, the Actor queries every rate provider you have access to (the two free ones, plus any paid provider you supplied an `apiKey` for) and returns the best rate, the worst rate, the spread between them, and every individual quote, so you can see whether providers disagree.

#### Why is my `exchangeratesapi.io`/`fixer.io`/`openexchangerates.org`/`currencylayer.com` result correct even though their free plan only allows one base currency?

Those providers' free tiers force `base=EUR` (exchangeratesapi.io, fixer.io) or `base=USD` (openexchangerates.org, currencylayer.com) and ignore any other base you request. This Actor detects that restriction and computes the correct cross-rate for your actual `from`/`to` pair from the forced-base data, so you get the right answer even on a free plan.

#### Can I call this without starting a new Actor run each time?

Yes. The Actor supports [Standby mode](https://docs.apify.com/platform/actors/running/standby), which keeps an HTTP server warm so `GET /convert` requests are answered immediately, the same way you'd call any REST API.

#### Can AI agents use this Actor as a tool?

Yes. It is compatible with the [Apify MCP Server](https://docs.apify.com/platform/integrations/mcp), so agents built with Claude, the OpenAI Agents SDK, LangChain or similar frameworks can call it directly for live currency conversion instead of relying on outdated training data.

#### What happens if a provider is down or returns an error?

In `auto` mode, the Actor tries Frankfurter first and automatically falls back to open.er-api.com if it fails or doesn't cover the requested currency pair. If every provider fails for a given target currency, that result row includes an `error` field instead of stopping the whole run, so the rest of your requested conversions still complete.

### Getting your own API key (optional)

You only need this if you want to use a named paid provider instead of the free defaults:

- [exchangeratesapi.io](https://exchangeratesapi.io/) – free tier available, forces `base=EUR`.
- [fixer.io](https://fixer.io/) – free tier available, forces `base=EUR`.
- [openexchangerates.org](https://openexchangerates.org/signup/free) – free tier available, forces `base=USD`.
- [currencylayer.com](https://currencylayer.com/product) – free tier available, forces `source=USD`.

Paste the key into the `apiKey` input field and set `source` to the matching provider (or leave `compareSources` on to use it alongside the free sources automatically).

# Actor input Schema

## `from` (type: `string`):

3-letter ISO code of the currency you are converting from, e.g. USD.

## `to` (type: `array`):

One or more 3-letter ISO target currency codes, e.g. EUR, GBP, JPY.

## `amount` (type: `string`):

The amount to convert. Decimals are allowed, e.g. 100.50.

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

Format YYYY-MM-DD. Leave empty for the latest rate. Supported by Frankfurter and by any keyed provider; ignored by open.er-api.com.

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

'auto' uses free sources that need no signup (Frankfurter, falling back to open.er-api.com). Pick a specific provider to use your own API key from that service.

## `compareSources` (type: `boolean`):

Query every available source (all free ones, plus any paid one you have supplied an API key for) and return a side-by-side rate comparison instead of a single value.

## `apiKey` (type: `string`):

Your own API key or App ID for exchangeratesapi.io, fixer.io, openexchangerates.org or currencylayer.com. Only needed when 'source' is set to one of those, or when comparing sources and you want them included.

## Actor input object example

```json
{
  "from": "USD",
  "to": [
    "EUR"
  ],
  "amount": "100",
  "source": "auto",
  "compareSources": false
}
```

# Actor output Schema

## `resultsJson` (type: `string`):

Every conversion result from this run, one item per requested target currency.

## `resultsCsv` (type: `string`):

The same results as a downloadable CSV file.

## `summary` (type: `string`):

A single JSON object with the input and all results for this run.

# 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 = {
    "from": "USD",
    "to": [
        "EUR"
    ],
    "amount": "100"
};

// Run the Actor and wait for it to finish
const run = await client.actor("pintostudio/currency-converter").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 = {
    "from": "USD",
    "to": ["EUR"],
    "amount": "100",
}

# Run the Actor and wait for it to finish
run = client.actor("pintostudio/currency-converter").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 '{
  "from": "USD",
  "to": [
    "EUR"
  ],
  "amount": "100"
}' |
apify call pintostudio/currency-converter --silent --output-dataset

```

## MCP server setup

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

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/eDhswznzVQCVgNwXa/builds/YJ1ZztrnW8zrMZGtq/openapi.json