# FX Rates: Official ECB Rates + CFA Franc & Gulf Pegs (`calcio_you/fx-rates-ecb-cfa`) Actor

Convert currencies with official European Central Bank reference rates (daily since 1999), plus CFA franc (XOF/XAF), AED, SAR, QAR and other official pegs. Historical rates, time series, rate tables. Built for AI agents and invoicing. Pay per call.

- **URL**: https://apify.com/calcio_you/fx-rates-ecb-cfa.md
- **Developed by:** [Novarithm](https://apify.com/calcio_you) (community)
- **Categories:** AI, Business, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

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

## FX Rates API: Official ECB Exchange Rates + CFA Franc & Gulf Pegs

Convert currencies with the **official European Central Bank (ECB) reference rates**, daily since 1999, plus the **officially pegged currencies the ECB does not publish**:

- **CFA francs XOF (BCEAO) and XAF (BEAC)**, Comorian franc KMF, Cape Verde escudo CVE (fixed to the euro)
- **UAE dirham AED, Saudi riyal SAR, Qatari riyal QAR, Bahraini dinar BHD, Omani rial OMR** (fixed to the US dollar)

Every answer states the **rate date**, the **method** (direct ECB rate, cross rate via EUR, or peg-derived) and the source, so an AI agent or an accountant can justify the number.

### Three operations

| Operation | What you get |
|---|---|
| **Conversion** | Amount converted between two currencies, today or at any date since 1999 (weekends/holidays fall back to the last ECB business day, with a note). |
| **Time series** | Daily rates for a pair over up to 366 days, with min, max, mean and % change. |
| **Rate table** | All official rates for a base currency on the latest (or a given) ECB fixing date. |

### Use cases

- An AI invoicing or bookkeeping agent converts a USD invoice to EUR at the official rate of the invoice date.
- An e-commerce site in West Africa shows prices in XOF from EUR or USD.
- A Dubai trading desk converts AED quotes to EUR or GBP.
- A treasury report needs the GBP/USD trend for last quarter.

### Input

| Field | Example |
|---|---|
| `conversions` | `[{"from": "USD", "to": "EUR", "amount": 1250}, {"from": "EUR", "to": "XOF", "amount": 100, "date": "2025-12-31"}]` |
| `timeseries` | `[{"from": "GBP", "to": "USD", "start": "2026-01-01", "end": "2026-03-31"}]` |
| `rateTables` | `[{"base": "USD", "symbols": "EUR,GBP,AED,XOF,JPY"}]` (empty symbols = all currencies) |
| `queries` | Advanced: `[{"endpoint": "fx_convert", "params": {"from": "AED", "to": "EUR", "amount": 50000}}]`; endpoints `fx_convert`, `fx_timeseries`, `fx_latest` |
| `maxQueries` | Safety cap on calls per run (default 1000). |

### Output

One dataset item per call. Shortened examples from a real run:

```json
{
  "endpoint": "fx_convert",
  "input": {"from": "EUR", "to": "XOF", "amount": 100},
  "ok": true,
  "result": {
    "from": "EUR", "to": "XOF", "amount": 100,
    "rate": 655.957, "converted": 65595.7,
    "rate_date": "2026-10-22",
    "method": "peg_derived",
    "pegs": ["BCEAO — franc CFA UEMOA (parité fixe garantie par le Trésor français)"],
    "explanation": "1 EUR = 655.957000 XOF (ECB reference rate of 2026-10-22, via official peg)"
  },
  "charged_event": "fx-convert",
  "price_usd": 0.002
}
```

- `USD → EUR, 1250` → `converted: 1115.57`, `method: "ecb_direct"`.
- `GBP/USD, Q1 2026` → 63 daily points with min/max/mean/change %.
- Rate table, base USD → EUR, AED (3.6725, peg), XOF...

### Pricing (pay per event)

| Event | Price |
|---|---|
| Conversion | $0.002 |
| Rate table | $0.002 |
| Time series (up to 366 days) | $0.005 |

No start fee. **Not charged**: unsupported currencies, invalid dates or parameters, future dates, source outages and internal errors (the item says `"ok": false` and why).

### Honest limits

- **Not real-time**: ECB reference rates are published once a day around 16:00 CET on TARGET business days. No intraday or market rates.
- ECB rates are published **for information purposes**: they are not the rate your bank will apply to a transaction.
- Currencies outside the ECB list and outside official pegs (e.g. NGN, KES, MAD, EGP) are not covered and are answered with `unsupported_currency` (not charged).

### Data sources

- [ECB euro foreign exchange reference rates](https://www.ecb.europa.eu/stats/policy_and_exchange_rates/euro_reference_exchange_rates/html/index.en.html), free reuse with source acknowledgement. Downloaded live at each run.
- Official fixed parities set by treaty or central banks (BCEAO, BEAC, Banque Centrale des Comores, Banco de Cabo Verde, CBUAE, SAMA, QCB, CBB, CBO).

Made by Novarithm, AI agents and automation. Contact: contact@novarithm.com

***

Want this whole store under your brand? → https://gogeta2-u35175.vm.elestio.app/agents/clones/en/cases/api-store-for-ai-agents/

# Actor input Schema

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

List of {"from": "USD", "to": "EUR", "amount": 1250, "date": "YYYY-MM-DD" (optional)}. One charged call per conversion.

## `timeseries` (type: `array`):

List of {"from": "GBP", "to": "USD", "start": "2026-01-01", "end": "2026-03-31"} (max 366 days each).

## `rateTables` (type: `array`):

List of {"base": "USD", "symbols": "EUR,GBP,AED,XOF", "date": "YYYY-MM-DD" (optional)}. Empty symbols = all available currencies.

## `queries` (type: `array`):

e.g. \[{"endpoint": "fx_convert", "params": {"from": "AED", "to": "EUR", "amount": 50000}}]; endpoints: fx_convert, fx_timeseries, fx_latest.

## `maxQueries` (type: `integer`):

Safety cap: only the first N checks of the input are processed.

## Actor input object example

```json
{
  "conversions": [
    {
      "from": "USD",
      "to": "EUR",
      "amount": 1250
    },
    {
      "from": "EUR",
      "to": "XOF",
      "amount": 100
    }
  ],
  "rateTables": [
    {
      "base": "USD",
      "symbols": "EUR,GBP,AED,XOF,JPY"
    }
  ],
  "maxQueries": 1000
}
```

# Actor output Schema

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

All result items in the default dataset (JSON).

# 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 = {
    "conversions": [
        {
            "from": "USD",
            "to": "EUR",
            "amount": 1250
        },
        {
            "from": "EUR",
            "to": "XOF",
            "amount": 100
        }
    ],
    "rateTables": [
        {
            "base": "USD",
            "symbols": "EUR,GBP,AED,XOF,JPY"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("calcio_you/fx-rates-ecb-cfa").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 = {
    "conversions": [
        {
            "from": "USD",
            "to": "EUR",
            "amount": 1250,
        },
        {
            "from": "EUR",
            "to": "XOF",
            "amount": 100,
        },
    ],
    "rateTables": [{
            "base": "USD",
            "symbols": "EUR,GBP,AED,XOF,JPY",
        }],
}

# Run the Actor and wait for it to finish
run = client.actor("calcio_you/fx-rates-ecb-cfa").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 '{
  "conversions": [
    {
      "from": "USD",
      "to": "EUR",
      "amount": 1250
    },
    {
      "from": "EUR",
      "to": "XOF",
      "amount": 100
    }
  ],
  "rateTables": [
    {
      "base": "USD",
      "symbols": "EUR,GBP,AED,XOF,JPY"
    }
  ]
}' |
apify call calcio_you/fx-rates-ecb-cfa --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,calcio_you/fx-rates-ecb-cfa"
        }
    }
}
```

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/fe5z0Dpz44B7qgXIE/builds/Mhc0cHwIISXHbydpw/openapi.json