# CurrencyRest

> CurrencyRest is a REST API for real-time and historical currency exchange rates and conversions, covering 68 fiat currencies and 20 cryptocurrencies (88 total). Rates are aggregated from multiple independent sources — central banks (ECB, Fed, Bank of England, Bank of Japan), Google Finance, TradingView, Google Search, and Binance — with automatic cross-rate calculation via USD/EUR pivots and transparent source fallback.

## Overview

- Base URL: `https://api.currencyrest.com/api/v1` (all endpoints are prefixed with `/api/v1`).
- Format: JSON. Errors follow RFC 7807 (`application/problem+json`).
- Coverage: 68 fiat currencies (incl. XOF/XAF as a fixed EUR peg) + 20 cryptocurrencies = 88 currencies.
- Cross-rates: any pair the providers don't quote directly is computed via a USD or EUR pivot, so e.g. `XOF` is available from any base.

## Authentication

API keys are optional but recommended. Send your key as either header:

- `X-API-Key: <your_key>`
- `Authorization: Bearer <your_key>`

Without a key, requests are anonymous and subject to a stricter shared rate limit. With a key, usage is metered against your plan's monthly request quota. Create keys in the dashboard at `https://currencyrest.com/dashboard/api-keys`.

## Sources & default mode

When no `source` is given (default mode), the API auto-selects the most suitable source per currency type using this priority and falls back transparently if one is down:

- Fiat: `ecb` → `boe` → `boj` → `fed` → `fixed` → `google-finance` → `tradingview` → `google-search`
- Crypto: `binance` → `tradingview` → `google-finance` → `google-search`

Pass an explicit `source` (e.g. `source=ecb`) to pin one provider. If that source doesn't quote the requested pair, the API returns a 404 listing the sources that do (it never silently mixes sources). Use `/rates/sources` to discover which sources serve a pair. Provider availability is published at `/status`.

## Endpoints

- `GET /api/v1/rates?base=USD&source=`: All current rates for a base currency, split into `fiat` and `crypto` groups with a `counts` summary. `base` defaults to `USD`. Optional `source` returns only that provider's direct rates.
- `GET /api/v1/rates/pair?from=USD&to=EUR&source=`: Single pair rate. Optional `source` pins a provider.
- `GET /api/v1/rates/sources?from=USD&to=EUR`: List sources currently quoting a pair.
- `GET /api/v1/convert?from=USD&to=XOF&amount=100&source=`: Convert an amount between two currencies. Returns `result`, `rate`, `source`, `timestamp`.
- `POST /api/v1/convert`: Same as above with a JSON body `{ "from", "to", "amount", "source"? }`.
- `GET /api/v1/historical?from=USD&to=EUR&startDate=&endDate=&source=&limit=`: Historical rate series (up to 1 year of retention) filtered by date range, currency pair, and optional source.
- `GET /api/v1/status`: Per-source operational status (operational / degraded / outage) and latency.
- `GET /api/v1/health`, `GET /api/v1/health/live`, `GET /api/v1/health/ready`: Service health/liveness/readiness probes.

## Example: GET /api/v1/rates?base=USD

```json
{
  "base": "USD",
  "source": "default",
  "timestamp": "2026-06-17T13:00:00.000Z",
  "counts": { "fiat": 68, "crypto": 20, "total": 88 },
  "rates": {
    "fiat": { "USD": 1, "EUR": 0.8625, "XOF": 565.81, "JPY": 157.2 },
    "crypto": { "BTC": 0.0000153, "ETH": 0.00041 }
  }
}
```

## Example: GET /api/v1/convert?from=USD&to=XOF&amount=100

```json
{
  "from": "USD",
  "to": "XOF",
  "amount": 100,
  "result": 56581.43,
  "rate": 565.8143,
  "source": "google-finance",
  "timestamp": "2026-06-17T13:00:00.000Z"
}
```

## Plans

- Free: 300 requests/month — €0
- Starter: 15,000 requests/month — €10/month
- Pro: 100,000 requests/month — €30/month
- Business: 1,000,000 requests/month — €80/month

## Links

- Documentation: https://currencyrest.com/docs
- Pricing: https://currencyrest.com/pricing
- API status: https://currencyrest.com/status
- Dashboard & API keys: https://currencyrest.com/dashboard