# National Bank of Belarus API
> Live official exchange-rate data from the National Bank of the Republic of Belarus (NBRB), the central bank of Belarus, for the Belarusian rouble (BYN): the NBRB official rate for every published currency (normalised to one unit), a single currency's rouble-per-unit rate and inverse, the daily time series of a currency's official rate over a full date range, and currency conversion between any two published currencies (including BYN) cross-computed through the rouble at NBRB 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/nbrb-api/..."
```

## Pricing
- **Free** (Free) — 13,000 calls/Mo, 3 req/s
- **Basic** ($7/Mo) — 170,000 calls/Mo, 8 req/s
- **Pro** ($22/Mo) — 1,060,000 calls/Mo, 15 req/s
- **Scale** ($53/Mo) — 5,600,000 calls/Mo, 35 req/s

## Endpoints

### Rates

#### `GET /v1/rate` — One currency rouble-per-unit rate 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/nbrb-api/v1/rate?currency=USD"
```

**Response:**
```json
{
    "data": {
        "base": "BYN",
        "date": "2026-06-10",
        "name": "Доллар США",
        "scale": 1,
        "source": "National Bank of Belarus",
        "currency": "USD",
        "byn_per_unit": 2.7671,
        "unit_per_byn": 0.36138918,
        "official_rate": 2.7671
    },
    "meta": {
        "timestamp": "2026-06-10T14:01:34.308Z",
        "request_id": "ac5febd2-425c-4b3c-9c0e-273ad1c33860"
    },
    "status": "ok",
    "message": "Rate retrieved successfully",
    "success": true
}
```

#### `GET /v1/rates` — NBRB official rate for every currency vs the rouble

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

**Response:**
```json
{
    "data": {
        "base": "BYN",
        "date": "2026-06-10",
        "count": 30,
        "rates": [
            {
                "date": "2026-06-10",
                "name": "Дирхамов ОАЭ",
                "scale": 10,
                "cur_id": 513,
                "currency": "AED",
                "byn_per_unit": 0.75346,
                "official_rate": 7.5346
            },
            {
                "date": "2026-06-10",
                "name": "Армянских драмов",
                "scale": 1000,
                "cur_id": 510,
                "currency": "AMD",
                "byn_per_unit": 0.0075085,
                "official_rate": 7.5085
            },
            {
                "date": "2026-06-10",
                "name": "Австралийский доллар",
                "scale": 1,
                "cur_id": 440,
                "currency": "AUD",
                "byn_per_unit": 1.9514,
                "official_rate": 1.9514
            },
            {
                "date": "2026-06-10",
                "name": "Бразильских реалов",
                "scale": 10,
                "cur_id": 514,
                "currency": "BRL",
                "byn_per_unit": 0.53336,
                "official_rate": 5.3336
            },
            {
                "date": "2026-06-10",
                "name": "Канадский доллар",
                "scale": 1,
                "cur_id": 371,
       
…(truncated, see openapi.json for full schema)
```

### History

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

**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/nbrb-api/v1/history?currency=USD&from=2026-05-01&to=2026-05-31"
```

**Response:**
```json
{
    "data": {
        "to": "2026-05-31",
        "base": "BYN",
        "from": "2026-05-01",
        "name": "Доллар США",
        "count": 31,
        "scale": 1,
        "source": "National Bank of Belarus",
        "currency": "USD",
        "observations": [
            {
                "date": "2026-05-31",
                "byn_per_unit": 2.7596,
                "official_rate": 2.7596
            },
            {
                "date": "2026-05-30",
                "byn_per_unit": 2.7596,
                "official_rate": 2.7596
            },
            {
                "date": "2026-05-29",
                "byn_per_unit": 2.7596,
                "official_rate": 2.7596
            },
            {
                "date": "2026-05-28",
                "byn_per_unit": 2.7638,
                "official_rate": 2.7638
            },
            {
                "date": "2026-05-27",
                "byn_per_unit": 2.7703,
                "official_rate": 2.7703
            },
            {
                "date": "2026-05-26",
                "byn_per_unit": 2.7549,
                "official_rate": 2.7549
            },
            {
                "date": "2026-05-25",
                "byn_per_unit": 2.7506,
                "official_rate": 2.7506
            },
            {
                "date": "2026-05-24",
                "byn_per_unit": 2.7315,
                "official_rate": 2.7315
            },
            {
                "date": "2026-05-2
…(truncated, see openapi.json for full schema)
```

### Convert

#### `GET /v1/convert` — Convert an amount between two currencies at NBRB 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/nbrb-api/v1/convert?from=USD&to=EUR&amount=100"
```

**Response:**
```json
{
    "data": {
        "to": "EUR",
        "date": "2026-06-10",
        "from": "USD",
        "rate": 0.86485388,
        "amount": 100,
        "result": 86.485388,
        "source": "National Bank of Belarus",
        "byn_per_to": 3.1995,
        "byn_per_from": 2.7671
    },
    "meta": {
        "timestamp": "2026-06-10T14:01:34.856Z",
        "request_id": "a7631654-902a-4aa2-921c-27c046c4e1c1"
    },
    "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/nbrb-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "source": "National Bank of Belarus API (api.nbrb.by, live)",
        "service": "nbrb-api",
        "usd_byn": 2.7671,
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/rate": "One currency's official rate, rouble-per-unit and inverse (currency=USD).",
            "GET /v1/rates": "The NBRB official rate for every currency vs the rouble.",
            "GET /v1/convert": "Convert an amount between two currencies at NBRB rates (from=USD, to=EUR, amount=100).",
            "GET /v1/history": "Daily time series of a currency's official rate over a date range (currency=USD, from, to)."
        },
        "description": "Live official exchange-rate data from the National Bank of the Republic of Belarus (NBRB), the central bank of Belarus, for the Belarusian rouble (BYN), via its public API. The rates endpoint returns the NBRB's official rate for every published currency against the rouble, normalised to one unit; the rate endpoint returns a single currency's official rate (rouble-per-unit and the inverse); the history endpoint returns the daily time series of a currency's official rate over a full date range; the convert endpoint converts an amount between any two published currencies (including BYN) at the NBRB's official rates, cross-computed through the rouble. Live, no key, nothing stored. Distinct from the ECB, SNB, Bank of Canada, Norges Bank, NBP, CNB, BCB, CBR, Riksbank, NBU, HNB and NBG feeds and from market 
…(truncated, see openapi.json for full schema)
```


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