# Croatian National Bank API
> Live official exchange-rate data from the Croatian National Bank (Hrvatska narodna banka, HNB), the central bank of Croatia, against the euro — uniquely with three rates per currency (buying, selling and middle): the official rate for every published currency, a single currency's buying/selling/middle rate plus the inverse, a currency's official rate on a specific past date, and currency conversion between any two published currencies (including the euro) cross-computed through the euro at HNB middle 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/hnb-api/..."
```

## Pricing
- **Free** (Free) — 11,000 calls/Mo, 3 req/s
- **Basic** ($7/Mo) — 160,000 calls/Mo, 8 req/s
- **Pro** ($19/Mo) — 1,000,000 calls/Mo, 15 req/s
- **Scale** ($48/Mo) — 5,300,000 calls/Mo, 35 req/s

## Endpoints

### Rates

#### `GET /v1/rate` — One currency buying, selling and middle rate

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

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

**Response:**
```json
{
    "data": {
        "base": "EUR",
        "date": "2026-06-10",
        "source": "Croatian National Bank",
        "country": "SAD",
        "currency": "USD",
        "buy_per_eur": 1.159,
        "mid_per_eur": 1.1573,
        "code_numeric": 840,
        "eur_per_unit": 0.86408019,
        "sell_per_eur": 1.1556
    },
    "meta": {
        "timestamp": "2026-06-10T14:01:41.858Z",
        "request_id": "aedcc491-3221-447f-b0c9-48323d06f8d7"
    },
    "status": "ok",
    "message": "Rate retrieved successfully",
    "success": true
}
```

#### `GET /v1/rates` — HNB official rate for every currency vs the euro

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

**Response:**
```json
{
    "data": {
        "base": "EUR",
        "date": "2026-06-10",
        "note": "units of the listed currency per 1 EUR",
        "count": 13,
        "rates": [
            {
                "buy": 1.6416,
                "mid": 1.6391,
                "date": "2026-06-10",
                "sell": 1.6366,
                "country": "Australija",
                "currency": "AUD",
                "country_iso": "AUS",
                "code_numeric": 36
            },
            {
                "buy": 1.95876,
                "mid": 1.95583,
                "date": "2026-06-10",
                "sell": 1.9529,
                "country": "Bosna i Hercegovina",
                "currency": "BAM",
                "country_iso": "BIH",
                "code_numeric": 977
            },
            {
                "buy": 1.6135,
                "mid": 1.6111,
                "date": "2026-06-10",
                "sell": 1.6087,
                "country": "Kanada",
                "currency": "CAD",
                "country_iso": "CAN",
                "code_numeric": 124
            },
            {
                "buy": 0.922,
                "mid": 0.9206,
                "date": "2026-06-10",
                "sell": 0.9192,
                "country": "Švicarska",
                "currency": "CHF",
                "country_iso": "CHE",
                "code_numeric": 756
            },
            {
                "buy": 24.204,
                "mid": 24.168,
        
…(truncated, see openapi.json for full schema)
```

### History

#### `GET /v1/history` — A currency official rate on a specific past date

**Parameters:**
- `currency` (query, required, string) — 3-letter ISO currency code Example: `USD`
- `date` (query, required, string) — Date YYYY-MM-DD Example: `2026-05-15`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/hnb-api/v1/history?currency=USD&date=2026-05-15"
```

**Response:**
```json
{
    "data": {
        "base": "EUR",
        "date": "2026-05-15",
        "source": "Croatian National Bank",
        "currency": "USD",
        "buy_per_eur": 1.172,
        "mid_per_eur": 1.1702,
        "eur_per_unit": 0.85455478,
        "sell_per_eur": 1.1684
    },
    "meta": {
        "timestamp": "2026-06-10T14:01:42.177Z",
        "request_id": "75ddb5db-be7a-4135-ac19-2c85b8203387"
    },
    "status": "ok",
    "message": "History retrieved successfully",
    "success": true
}
```

### Convert

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

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

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

**Response:**
```json
{
    "data": {
        "to": "GBP",
        "date": "2026-06-10",
        "from": "USD",
        "rate": 0.74604683,
        "amount": 100,
        "result": 74.604683,
        "source": "Croatian National Bank",
        "eur_per_to": 1.15821172,
        "eur_per_from": 0.86408019
    },
    "meta": {
        "timestamp": "2026-06-10T14:01:42.335Z",
        "request_id": "fa709753-86f5-43c2-9581-9eb62a5e9117"
    },
    "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/hnb-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "source": "Croatian National Bank API (api.hnb.hr, live)",
        "service": "hnb-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/rate": "One currency's buying, selling and middle rate and inverse (currency=USD).",
            "GET /v1/rates": "The HNB official rate for every published currency vs the euro.",
            "GET /v1/convert": "Convert an amount between two currencies at HNB middle rates (from=USD, to=GBP, amount=100).",
            "GET /v1/history": "A currency's official rate on a specific past date (currency=USD, date=2026-05-15)."
        },
        "description": "Live official exchange-rate data from the Croatian National Bank (Hrvatska narodna banka, HNB), the central bank of Croatia, via its public API. Since Croatia adopted the euro, the HNB publishes official daily rates against the euro, uniquely with three rates per currency: buying, selling and middle. The rates endpoint returns the official rate for every published currency against the euro; the rate endpoint returns a single currency's buying, selling and middle rate plus the inverse; the history endpoint returns a currency's official rate on a specific past date; the convert endpoint converts an amount between any two published currencies (including the euro) at the HNB's middle rates, cross-computed through the euro. Live, no key, nothing stored. Distinct from the ECB, SNB, Bank of Canada, Norges Bank, NBP, CNB, BCB, CBR, R
…(truncated, see openapi.json for full schema)
```


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