# National Bank of North Macedonia (NBRM) FX API
> Official Macedonian denar (MKD) exchange rates from the National Bank of the Republic of North Macedonia (NBRM), with no key. Get the latest official rate for every quoted currency, a single-currency rate, a currency converter and the list of quoted currencies. The bank publishes a nominal (1 or 100 units) and a middle rate, so every rate is normalised to a per-unit MKD value (middle rate ÷ nominal) and conversions are correct. The North-Macedonia-FX layer for treasury, pricing and FX dashboards.

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

## Pricing
- **Free** (Free) — 1,340 calls/Mo, 2 req/s
- **Basic** ($10/Mo) — 40,500 calls/Mo, 5 req/s
- **Pro** ($29/Mo) — 165,000 calls/Mo, 15 req/s
- **Business** ($62/Mo) — 682,000 calls/Mo, 40 req/s

## Endpoints

### FX

#### `GET /v1/convert` — Convert an amount between two currencies via MKD

**Parameters:**
- `from` (query, required, string) — Source ISO code (or MKD) Example: `EUR`
- `to` (query, required, string) — Target ISO code (or MKD) Example: `MKD`
- `amount` (query, optional, string) — Amount to convert Example: `100`

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

**Response:**
```json
{
    "data": {
        "to": "MKD",
        "base": "MKD",
        "date": "2026-06-15",
        "from": "EUR",
        "rate": 61.6327,
        "amount": 100,
        "result": 6163.27
    },
    "meta": {
        "timestamp": "2026-06-15T11:15:35.391Z",
        "request_id": "7b615e9e-cc47-4962-85eb-8f22bcb46cd7"
    },
    "status": "ok",
    "message": "Conversion retrieved successfully",
    "success": true
}
```

#### `GET /v1/currencies` — All currencies quoted by the NBRM

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

**Response:**
```json
{
    "data": {
        "base": "MKD",
        "date": "2026-06-15",
        "count": 31,
        "currencies": [
            "AUD",
            "BRL",
            "CAD",
            "CHF",
            "CNY",
            "CZK",
            "DKK",
            "EUR",
            "GBP",
            "HKD",
            "HUF",
            "IDR",
            "ILS",
            "INR",
            "JPY",
            "KRW",
            "MXN",
            "MYR",
            "NOK",
            "NZD",
            "PHP",
            "PLN",
            "RON",
            "RSD",
            "RUB",
            "SEK",
            "SGD",
            "THB",
            "TRY",
            "USD",
            "ZAR"
        ]
    },
    "meta": {
        "timestamp": "2026-06-15T11:15:35.456Z",
        "request_id": "4478f797-28e3-4f8f-b73f-4f50105bb0fc"
    },
    "status": "ok",
    "message": "Currencies retrieved successfully",
    "success": true
}
```

#### `GET /v1/latest` — Latest official MKD rates (all or selected)

**Parameters:**
- `symbols` (query, optional, string) — Comma-separated ISO codes Example: `EUR,USD,GBP`

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

**Response:**
```json
{
    "data": {
        "base": "MKD",
        "date": "2026-06-15",
        "count": 3,
        "rates": [
            {
                "iso": "EUR",
                "name": "Euro",
                "nominal": 1,
                "middle_rate": 61.6327,
                "per_unit_mkd": 61.6327
            },
            {
                "iso": "USD",
                "name": "US dollar",
                "nominal": 1,
                "middle_rate": 53.2832,
                "per_unit_mkd": 53.2832
            },
            {
                "iso": "GBP",
                "name": "Pound sterling",
                "nominal": 1,
                "middle_rate": 71.4127,
                "per_unit_mkd": 71.4127
            }
        ]
    },
    "meta": {
        "timestamp": "2026-06-15T11:15:35.545Z",
        "request_id": "61b79a9b-30c2-4f63-89ec-d6e91814e2b7"
    },
    "status": "ok",
    "message": "Latest rates retrieved successfully",
    "success": true
}
```

#### `GET /v1/rate` — Single-currency MKD rate

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

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/macedonia-fx-api/v1/rate?symbol=EUR"
```

**Response:**
```json
{
    "data": {
        "iso": "EUR",
        "base": "MKD",
        "date": "2026-06-15",
        "name": "Euro",
        "nominal": 1,
        "middle_rate": 61.6327,
        "per_unit_mkd": 61.6327
    },
    "meta": {
        "timestamp": "2026-06-15T11:15:35.648Z",
        "request_id": "49ece549-ebc2-42be-953d-8ddf8a934462"
    },
    "status": "ok",
    "message": "Rate retrieved successfully",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Bank metadata & endpoint guide

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

**Response:**
```json
{
    "data": {
        "bank": "National Bank of the Republic of North Macedonia (NBRM)",
        "note": "per_unit_mkd = middle_rate / nominal, so conversions are correct even when the NBRM quotes a currency per 100 units.",
        "source": "NBRM XML service (nbrm.mk/KLServiceNOV/GetExchangeRate), keyless",
        "country": "North Macedonia",
        "examples": {
            "rate": "/v1/rate?symbol=EUR",
            "latest": "/v1/latest?symbols=EUR,USD,GBP",
            "convert": "/v1/convert?from=EUR&to=MKD&amount=100",
            "currencies": "/v1/currencies"
        },
        "endpoints": {
            "/v1/rate": "single-currency rate with nominal, middle rate and per-unit MKD value (symbol=EUR)",
            "/v1/latest": "latest official MKD rates for all (or selected) currencies (symbols optional)",
            "/v1/convert": "convert an amount between any two quoted currencies via MKD (from, to, amount)",
            "/v1/currencies": "all currencies quoted by the NBRM"
        },
        "cache_ttl_ms": 300000,
        "base_currency": "MKD"
    },
    "meta": {
        "timestamp": "2026-06-15T11:15:35.745Z",
        "request_id": "dad23c06-da25-4bb7-bb4a-0190b46d6015"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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