# National Bank of Ukraine API
> Live official exchange-rate data from the National Bank of Ukraine (NBU), the central bank of Ukraine, for the hryvnia (UAH): the NBU official daily rate for every one of 45-plus currencies, a single currency's rate (hryvnia-per-unit and inverse), the daily time series of a currency's official rate over a date range and currency conversion between any two currencies (including UAH) cross-computed through the hryvnia at NBU rates.

## 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/nbu-api/..."
```

## Pricing
- **Free** (Free) — 12,000 calls/Mo, 3 req/s
- **Basic** ($7/Mo) — 170,000 calls/Mo, 8 req/s
- **Pro** ($21/Mo) — 1,050,000 calls/Mo, 15 req/s
- **Scale** ($50/Mo) — 5,500,000 calls/Mo, 35 req/s

## Endpoints

### Rates

#### `GET /v1/rate` — One currency official rate, hryvnia-per-unit and inverse

**Parameters:**
- `currency` (query, required, string) — 3-letter ISO currency code Example: `USD`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/nbu-api/v1/rate?currency=USD"
```

**Response:**
```json
{
    "data": {
        "base": "UAH",
        "date": "2026-06-11",
        "name": "Долар США",
        "source": "National Bank of Ukraine",
        "currency": "USD",
        "code_numeric": 840,
        "uah_per_unit": 44.979,
        "unit_per_uah": 0.0222326
    },
    "meta": {
        "timestamp": "2026-06-10T14:01:46.473Z",
        "request_id": "be21b2d1-5ba1-4fc8-97b1-11bf0fc34dd3"
    },
    "status": "ok",
    "message": "Rate retrieved successfully",
    "success": true
}
```

#### `GET /v1/rates` — NBU official rate for every currency vs hryvnia

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

**Response:**
```json
{
    "data": {
        "base": "UAH",
        "date": "2026-06-11",
        "count": 45,
        "rates": [
            {
                "date": "2026-06-11",
                "name": "Дирхам ОАЕ",
                "currency": "AED",
                "code_numeric": 784,
                "uah_per_unit": 12.2458
            },
            {
                "date": "2026-06-11",
                "name": "Австралійський долар",
                "currency": "AUD",
                "code_numeric": 36,
                "uah_per_unit": 31.4898
            },
            {
                "date": "2026-06-11",
                "name": "Азербайджанський манат",
                "currency": "AZN",
                "code_numeric": 944,
                "uah_per_unit": 26.4645
            },
            {
                "date": "2026-06-11",
                "name": "Така",
                "currency": "BDT",
                "code_numeric": 50,
                "uah_per_unit": 0.3665
            },
            {
                "date": "2026-06-11",
                "name": "Канадський долар",
                "currency": "CAD",
                "code_numeric": 124,
                "uah_per_unit": 32.2812
            },
            {
                "date": "2026-06-11",
                "name": "Швейцарський франк",
                "currency": "CHF",
                "code_numeric": 756,
                "uah_per_unit": 
…(truncated, see openapi.json for full schema)
```

### History

#### `GET /v1/history` — Daily time series of a currency official rate

**Parameters:**
- `currency` (query, required, string) — 3-letter ISO currency code Example: `USD`
- `from` (query, optional, string) — Start date YYYY-MM-DD Example: `2026-05-01`
- `to` (query, optional, string) — End date YYYY-MM-DD Example: `2026-05-31`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/nbu-api/v1/history?currency=USD&from=2026-05-01&to=2026-05-31"
```

**Response:**
```json
{
    "data": {
        "to": "2026-05-31",
        "base": "UAH",
        "from": "2026-05-01",
        "name": "US Dollar",
        "count": 31,
        "source": "National Bank of Ukraine",
        "currency": "USD",
        "observations": [
            {
                "date": "2026-05-31",
                "uah_per_unit": 44.2653
            },
            {
                "date": "2026-05-30",
                "uah_per_unit": 44.2653
            },
            {
                "date": "2026-05-29",
                "uah_per_unit": 44.2653
            },
            {
                "date": "2026-05-28",
                "uah_per_unit": 44.2996
            },
            {
                "date": "2026-05-27",
                "uah_per_unit": 44.2767
            },
            {
                "date": "2026-05-26",
                "uah_per_unit": 44.2447
            },
            {
                "date": "2026-05-25",
                "uah_per_unit": 44.2619
            },
            {
                "date": "2026-05-24",
                "uah_per_unit": 44.2341
            },
            {
                "date": "2026-05-23",
                "uah_per_unit": 44.2341
            },
            {
                "date": "2026-05-22",
                "uah_per_unit": 44.2341
            },
            {
                "date": "2026-05-21",
                "uah_per_unit": 44.2271
            },
            {
                "date": "2026-05-20",
                "uah_per_
…(truncated, see openapi.json for full schema)
```

### Convert

#### `GET /v1/convert` — Convert an amount between two currencies at NBU rates

**Parameters:**
- `from` (query, required, string) — Source currency Example: `USD`
- `to` (query, required, string) — Target currency Example: `EUR`
- `amount` (query, optional, string) — Amount to convert Example: `100`

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

**Response:**
```json
{
    "data": {
        "to": "EUR",
        "date": "2026-06-11",
        "from": "USD",
        "rate": 0.86673925,
        "amount": 100,
        "result": 86.673925,
        "source": "National Bank of Ukraine",
        "uah_per_to": 51.8945,
        "uah_per_from": 44.979
    },
    "meta": {
        "timestamp": "2026-06-10T14:01:47.032Z",
        "request_id": "df9ccdc1-ce1a-441c-84c8-d22a540992f5"
    },
    "status": "ok",
    "message": "Conversion completed successfully",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Service metadata and endpoint catalog

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

**Response:**
```json
{
    "data": {
        "source": "National Bank of Ukraine statistics API (bank.gov.ua, live)",
        "service": "nbu-api",
        "usd_uah": 44.979,
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/rate": "One currency's official rate, hryvnia-per-unit and inverse (currency=USD).",
            "GET /v1/rates": "The NBU official rate for every currency vs the hryvnia.",
            "GET /v1/convert": "Convert an amount between two currencies at NBU rates (from=USD, to=EUR, amount=100).",
            "GET /v1/history": "Daily time series of a currency's official rate (currency=USD, from, to)."
        },
        "description": "Live official exchange-rate data from the National Bank of Ukraine (NBU), the central bank of Ukraine, for the hryvnia (UAH), via its public statistics API. The rates endpoint returns the NBU's official daily rate for every one of 45-plus currencies against the hryvnia; the rate endpoint returns a single currency's official rate (hryvnia-per-unit and the inverse); the history endpoint returns the daily time series of a currency's official rate over a date range; the convert endpoint converts an amount between any two currencies (including UAH) at the NBU's official rates, cross-computed through the hryvnia. Live, no key, nothing stored. Distinct from the ECB, SNB, Bank of Canada, Norges Bank, NBP, CNB, BCB, CBR and Riksbank feeds and from market mid-rates — this is the National Bank of Ukraine's own officia
…(truncated, see openapi.json for full schema)
```


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