# Currency Exchange Rates API (`sfoln/fx-rates`)

Get latest or historical exchange rates for any currency pairs, with amount conversion: ECB and 100+ central-bank reference rates via Frankfurter, data back to 1948. $0.50 per 1,000 rates; invalid pairs and dates without data are free.

- Family: Data utilities
- Categories: Developer tools, Automation, Ecommerce
- Store: https://apify.com/sfoln/fx-rates (Markdown: https://apify.com/sfoln/fx-rates.md)
- JSON: https://www.sfoln.com/actors/fx-rates.json
- MCP: https://mcp.apify.com?tools=sfoln/fx-rates
- REST (sync): POST https://api.apify.com/v2/actors/sfoln~fx-rates/run-sync-get-dataset-items
- REST (async): POST https://api.apify.com/v2/actors/sfoln~fx-rates/runs

Currency Exchange Rates API gets latest or historical exchange rates for any list of currency pairs and converts an amount in the same call. Rates are mid-market reference rates published by the European Central Bank and 100+ other central banks and official sources, blended by the open-source Frankfurter service (data back to 1948). Ideal for invoicing, e-commerce price lists, accounting exports, spreadsheets and AI agents that need a reliable, citable rate.

## Price per delivered record

| Event | Price | Per 1,000 | Charged for |
| --- | --- | --- | --- |
| Exchange rate (`fx-rate`) | $0.0005 | $0.50 / 1,000 | Charged once per currency pair (and date) for which an exchange rate was returned. |

Pay-per-event, USD, billed by Apify; no platform usage charge. Only records with status `ok` are charged. Cap a run with `maxTotalChargeUsd`. Apify free plan: up to 10 per run.

## Run

```bash
curl -X POST "https://api.apify.com/v2/actors/sfoln~fx-rates/run-sync-get-dataset-items" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pairs":["USD/EUR","EUR/GBP","GBP/JPY@2024-01-05"]}'
```

MCP client configuration:

```json
{
  "mcpServers": {
    "apify": {
      "type": "http",
      "url": "https://mcp.apify.com?tools=sfoln/fx-rates"
    }
  }
}
```

Example prompt: Get today's USD/EUR, EUR/GBP and GBP/JPY exchange rates and convert 2,500 USD to EUR.

## Input

List currency pairs such as USD/EUR. Each pair produces one dataset record with the rate, its date and the converted amount.

| Field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `pairs` (required) | array | — | Currency pairs: Pairs as BASE/QUOTE with ISO 4217 codes, e.g. USD/EUR. Add @YYYY-MM-DD for a historical rate (EUR/GBP@2024-01-05). API callers can also pass objects {"base":"USD","quotes":["EUR","JPY"],"date":"2024-01-05","amount":250}. Accounts on the Apify free plan can process up to 10 currency pairs per run. |
| `amount` | string | `"1"` | Amount to convert: Amount in the base currency to convert: a plain number with a decimal point, e.g. 100 or 99.95 (no thousands separators, decimal commas or currency signs; otherwise the pairs are skipped as invalid). Default 1. |
| `date` | string | — | Date: Historical date (YYYY-MM-DD) applied to pairs without their own @date. Leave empty for the latest rates. |
| `maxPairs` | integer | `1000` | Max pairs: Safety cap on the number of pairs processed in this run. |
| `concurrency` | integer | `5` | Concurrency: Parallel workers. Pairs sharing a base currency and date are fetched in one request. |
| `includeRaw` | boolean | `false` | Include raw upstream response: Attach the unmodified Frankfurter row to each record. |

Example input:

```json
{
  "pairs": [
    "USD/EUR",
    "EUR/GBP",
    "GBP/JPY@2024-01-05"
  ]
}
```

## Output

One record per input item with `status` (`ok` is charged; `not_found`, `error`, `skipped_*` are free) and `charged`. The run stores an `OUTPUT` summary record.

| Field | Type | Meaning |
| --- | --- | --- |
| `input` | object | Input: Parsed pair request. |
| `pair` | string | Pair |
| `base` | string | null | Base currency |
| `quote` | string | null | Quote currency |
| `rate` | number | null | Rate: Units of quote currency per 1 unit of base currency (mid-market). |
| `inverseRate` | number | null | Inverse rate: 1 / rate, 10 significant digits. |
| `date` | string | Rate date: Date of the reference rate (YYYY-MM-DD). |
| `requestedDate` | string | null | Requested date: null = latest. |
| `amount` | number | null | Amount: Amount in base currency (null when the given amount was not a plain number; the record is then skipped_invalid). |
| `converted` | number | Converted: amount × rate, in quote currency. |
| `status` | string | Status: ok \| not_found \| error \| skipped_invalid \| skipped_budget \| skipped_free_plan |
| `charged` | boolean | Charged |
| `source` | string | Source |
| `fetchedAt` | string | Fetched at |

Example record:

```json
{
  "input": {
    "pair": "USD/EUR",
    "base": "USD",
    "quote": "EUR",
    "amount": 100
  },
  "pair": "USD/EUR",
  "base": "USD",
  "quote": "EUR",
  "rate": 0.89273,
  "inverseRate": 1.120159511,
  "date": "2026-10-14",
  "requestedDate": null,
  "amount": 100,
  "converted": 89.273,
  "status": "ok",
  "charged": true,
  "chargedEvent": "fx-rate",
  "source": "frankfurter (ECB and other central banks)",
  "fetchedAt": "2026-10-14T10:00:00.000Z"
}
```

## Related

- [Geocoding API – Address to Coordinates](https://www.sfoln.com/actors/geocode-address.md) (`sfoln/geocode-address`)
- [Historical Weather Data API](https://www.sfoln.com/actors/historical-weather.md) (`sfoln/historical-weather`)
- [VIN Decoder API – Specs, Recalls & Safety](https://www.sfoln.com/actors/vin-decoder.md) (`sfoln/vin-decoder`)

Publisher: SFOLN LLC, contact@sfoln.com. Catalogue: https://www.sfoln.com/catalog.json. Agent guide: https://www.sfoln.com/agents.md.