# Currency API
> Live & historical foreign-exchange rates from the European Central Bank: latest rates, historical lookups, time-series and currency conversion across 30+ currencies.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/currency-api/..."
```

## Pricing
- **Free** (Free) — 5,000 calls/Mo, 2 req/s
- **Basic** ($9/Mo) — 50,000 calls/Mo, 10 req/s
- **Pro** ($29/Mo) — 250,000 calls/Mo, 25 req/s
- **Mega** ($79/Mo) — 1,000,000 calls/Mo, 50 req/s

## Endpoints

### Rates

#### `GET /v1/historical` — Rates on a specific date

**Parameters:**
- `date` (query, required, string) — Date YYYY-MM-DD Example: `2024-01-02`
- `base` (query, optional, string) — Base currency Example: `EUR`
- `symbols` (query, optional, string) — Target currencies Example: `USD`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/currency-api/v1/historical?date=2024-01-02&base=EUR&symbols=USD"
```

**Response:**
```json
{
    "data": {
        "base": "EUR",
        "date": "2024-01-02",
        "rates": {
            "USD": 1.0956
        }
    },
    "meta": {
        "timestamp": "2026-05-29T19:13:38.861Z",
        "request_id": "84ac7766-7e4e-48f3-a1f6-ce389e479409"
    },
    "status": "ok",
    "message": "Historical rates retrieved successfully",
    "success": true
}
```

#### `GET /v1/latest` — Latest reference rates

**Parameters:**
- `base` (query, optional, string) — Base currency (ISO-4217) Example: `USD`
- `symbols` (query, optional, string) — Comma-separated target currencies Example: `EUR,GBP`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/currency-api/v1/latest?base=USD&symbols=EUR%2CGBP"
```

**Response:**
```json
{
    "data": {
        "base": "USD",
        "date": "2026-05-29",
        "rates": {
            "EUR": 0.85881,
            "GBP": 0.74479
        }
    },
    "meta": {
        "timestamp": "2026-05-29T19:13:39.238Z",
        "request_id": "539e2f37-15e0-4119-943d-c3ca69c6358c"
    },
    "status": "ok",
    "message": "Latest rates retrieved successfully",
    "success": true
}
```

#### `GET /v1/timeseries` — Rates over a date range

**Parameters:**
- `start_date` (query, required, string) — Start YYYY-MM-DD Example: `2024-01-01`
- `end_date` (query, optional, string) — End YYYY-MM-DD Example: `2024-01-31`
- `base` (query, optional, string) — Base currency Example: `EUR`
- `symbols` (query, optional, string) — Target currencies Example: `USD`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/currency-api/v1/timeseries?start_date=2024-01-01&end_date=2024-01-31&base=EUR&symbols=USD"
```

**Response:**
```json
{
    "data": {
        "base": "EUR",
        "rates": {
            "2023-12-29": {
                "USD": 1.105
            },
            "2024-01-02": {
                "USD": 1.0956
            },
            "2024-01-03": {
                "USD": 1.0919
            },
            "2024-01-04": {
                "USD": 1.0953
            },
            "2024-01-05": {
                "USD": 1.0921
            },
            "2024-01-08": {
                "USD": 1.0946
            },
            "2024-01-09": {
                "USD": 1.094
            },
            "2024-01-10": {
                "USD": 1.0946
            },
            "2024-01-11": {
                "USD": 1.0987
            },
            "2024-01-12": {
                "USD": 1.0942
            },
            "2024-01-15": {
                "USD": 1.0945
            },
            "2024-01-16": {
                "USD": 1.0882
            },
            "2024-01-17": {
                "USD": 1.0877
            },
            "2024-01-18": {
                "USD": 1.0875
            },
            "2024-01-19": {
                "USD": 1.0887
            },
            "2024-01-22": {
                "USD": 1.089
            },
            "2024-01-23": {
                "USD": 1.0872
            },
            "2024-01-24": {
                "USD": 1.0905
            },
            "2024-01-25": {
                "USD": 1.0893
            },
            "2024-01-26": {
                "USD": 1.0871

…(truncated, see openapi.json for full schema)
```

### Conversion

#### `GET /v1/convert` — Convert an amount

**Parameters:**
- `from` (query, required, string) — From currency Example: `USD`
- `to` (query, required, string) — To currency Example: `EUR`
- `amount` (query, optional, string) — Amount Example: `100`
- `date` (query, optional, string) — Date YYYY-MM-DD (default latest)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/currency-api/v1/convert?from=USD&to=EUR&amount=100"
```

**Response:**
```json
{
    "data": {
        "to": "EUR",
        "date": "2026-05-29",
        "from": "USD",
        "rate": 0.85881,
        "amount": 100,
        "result": 85.881
    },
    "meta": {
        "timestamp": "2026-05-29T19:13:40.144Z",
        "request_id": "3a874bea-8a00-4e1b-a535-2bfe8315c7a8"
    },
    "status": "ok",
    "message": "Conversion retrieved successfully",
    "success": true
}
```

### Reference

#### `GET /v1/currencies` — Supported currency codes

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/currency-api/v1/currencies"
```

**Response:**
```json
{
    "data": {
        "count": 30,
        "currencies": [
            {
                "code": "AUD",
                "name": "Australian Dollar"
            },
            {
                "code": "BRL",
                "name": "Brazilian Real"
            },
            {
                "code": "CAD",
                "name": "Canadian Dollar"
            },
            {
                "code": "CHF",
                "name": "Swiss Franc"
            },
            {
                "code": "CNY",
                "name": "Chinese Renminbi Yuan"
            },
            {
                "code": "CZK",
                "name": "Czech Koruna"
            },
            {
                "code": "DKK",
                "name": "Danish Krone"
            },
            {
                "code": "EUR",
                "name": "Euro"
            },
            {
                "code": "GBP",
                "name": "British Pound"
            },
            {
                "code": "HKD",
                "name": "Hong Kong Dollar"
            },
            {
                "code": "HUF",
                "name": "Hungarian Forint"
            },
            {
                "code": "IDR",
                "name": "Indonesian Rupiah"
            },
            {
                "code": "ILS",
                "name": "Israeli New Shekel"
            },
            {
                "code": "INR",
                "name": "Indian Rupee"
            },
            {
         
…(truncated, see openapi.json for full schema)
```


---
Marketplace page: https://www.oanor.com/api/currency-api
OpenAPI spec: https://www.oanor.com/api/currency-api/openapi.json