# CurrencyRest

> CurrencyRest is a REST API for real-time and historical currency exchange rates and conversions, covering 190 fiat currencies and 94 cryptocurrencies (284 total). Rates are aggregated from multiple independent sources — central banks (ECB, Fed, Bank of England, Bank of Japan), Google Finance, TradingView, Google Search, Binance, and CoinGecko — 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: 190 fiat currencies (incl. XOF/XAF as a fixed EUR peg) + 94 cryptocurrencies = 280+ 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 & plan limits

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

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

The **Free plan is a test sandbox**: it is limited to **2 currency pairs (USD/EUR and USD/BTC)**
and a one-time lifetime allowance of **300 total requests** (not monthly) — enough to test and
integrate the API. Paid plans (Starter/Pro/Business) unlock all 280+ currencies / every pair for
production use and raise the monthly quota (15,000 / 100,000 / 1,000,000 requests/month). Without
a key you can still call the API anonymously but you are limited by a shared per-IP rate limit
(100 requests/minute) — create a free sandbox key to test, then upgrade to a paid plan for
production access.
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` → `coingecko` → `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 90 days 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-08-08T12:00:00.000Z",
  "counts": { "fiat": 190, "crypto": 94, "total": 284 },
  "rates": {
    "fiat": { "USD": 1, "EUR": 0.8669, "XOF": 568.67, "JPY": 157.73 },
    "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": 56866.67,
  "rate": 568.6667,
  "source": "google-finance",
  "timestamp": "2026-08-08T12:00:00.000Z"
}
```

## Plans

Monthly, or yearly with 2 months free:

- Free (Sandbox): 300 total requests, one-time — $0 (test sandbox, USD/EUR + USD/BTC pairs only)
- Starter: 15,000 requests/month — $2.99/month or $29.90/year
- Pro: 100,000 requests/month — $9.99/month or $99.90/year
- Business: 1,000,000 requests/month — $19.99/month or $199.90/year

## Links

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