# Currency Codes (ISO 4217) API
> The ISO 4217 currency-code register as an API — not foreign-exchange rates, but the metadata a checkout or accounting system needs to handle money correctly. Each currency carries its 3-letter alphabetic code, 3-digit numeric code, official name, the number of minor units (decimal places, e.g. JPY 0, USD 2, BHD 3) and the list of countries that use it. Look a currency up by alphabetic or numeric code, find the currencies a country uses, search by name, or list the whole register. Bundled and served from memory — always fast, no key needed upstream.

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

## Pricing
- **Free** (Free) — 15,000 calls/Mo, 3 req/s
- **Starter** ($5/Mo) — 150,000 calls/Mo, 8 req/s
- **Pro** ($16/Mo) — 700,000 calls/Mo, 20 req/s
- **Mega** ($40/Mo) — 3,000,000 calls/Mo, 50 req/s

## Endpoints

### Lookup

#### `GET /v1/code` — Currency by alphabetic or numeric code

**Parameters:**
- `code` (query, optional, string) — Alphabetic ISO 4217 code Example: `USD`
- `number` (query, optional, string) — Numeric ISO 4217 code Example: `840`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/currencycodes-api/v1/code?code=USD&number=840"
```

**Response:**
```json
{
    "data": {
        "currency": {
            "code": "USD",
            "name": "US Dollar",
            "active": true,
            "numeric": "840",
            "countries": [
                "AMERICAN SAMOA",
                "BONAIRE, SINT EUSTATIUS AND SABA",
                "BRITISH INDIAN OCEAN TERRITORY (THE)",
                "ECUADOR",
                "EL SALVADOR",
                "GUAM",
                "HAITI",
                "MARSHALL ISLANDS (THE)",
                "MICRONESIA (FEDERATED STATES OF)",
                "NORTHERN MARIANA ISLANDS (THE)",
                "PALAU",
                "PANAMA",
                "PUERTO RICO",
                "TIMOR-LESTE",
                "TURKS AND CAICOS ISLANDS (THE)",
                "UNITED STATES MINOR OUTLYING ISLANDS (THE)",
                "UNITED STATES OF AMERICA (THE)",
                "VIRGIN ISLANDS (BRITISH)",
                "VIRGIN ISLANDS (U.S.)"
            ],
            "minor_unit": 2
        }
    },
    "meta": {
        "timestamp": "2026-06-08T18:25:12.472Z",
        "request_id": "50e1b683-d4bf-43d4-bef7-9f196c97ae62"
    },
    "status": "ok",
    "message": "Currency retrieved successfully",
    "success": true
}
```

#### `GET /v1/country` — Currencies used by a country

**Parameters:**
- `country` (query, required, string) — Country name Example: `Japan`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/currencycodes-api/v1/country?country=Japan"
```

**Response:**
```json
{
    "data": {
        "count": 1,
        "country": "Japan",
        "currencies": [
            {
                "code": "JPY",
                "name": "Yen",
                "active": true,
                "numeric": "392",
                "countries": [
                    "JAPAN"
                ],
                "minor_unit": 0
            }
        ]
    },
    "meta": {
        "timestamp": "2026-06-08T18:25:12.603Z",
        "request_id": "aebd9f4f-0b87-4df6-bbaa-a655405e69b0"
    },
    "status": "ok",
    "message": "Country currencies retrieved successfully",
    "success": true
}
```

### Search

#### `GET /v1/search` — Search currencies by code, name or country

**Parameters:**
- `q` (query, required, string) — Search query (min 2 chars) Example: `dinar`
- `limit` (query, optional, string) — Max results (1-100) Example: `25`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/currencycodes-api/v1/search?q=dinar&limit=25"
```

**Response:**
```json
{
    "data": {
        "count": 17,
        "query": "dinar",
        "total": 17,
        "currencies": [
            {
                "code": "BAD",
                "name": "Dinar",
                "active": false,
                "numeric": "070",
                "countries": [],
                "minor_unit": null
            },
            {
                "code": "BHD",
                "name": "Bahraini Dinar",
                "active": true,
                "numeric": "048",
                "countries": [
                    "BAHRAIN"
                ],
                "minor_unit": 3
            },
            {
                "code": "CSD",
                "name": "Serbian Dinar",
                "active": false,
                "numeric": "891",
                "countries": [],
                "minor_unit": null
            },
            {
                "code": "DZD",
                "name": "Algerian Dinar",
                "active": true,
                "numeric": "012",
                "countries": [
                    "ALGERIA"
                ],
                "minor_unit": 2
            },
            {
                "code": "HRD",
                "name": "Croatian Dinar",
                "active": false,
                "numeric": "191",
                "countries": [],
                "minor_unit": null
            },
            {
                "code": "IQD",
                "name": "Iraqi Dinar",
                "active": true,
               
…(truncated, see openapi.json for full schema)
```

### List

#### `GET /v1/list` — List all currencies

**Parameters:**
- `limit` (query, optional, string) — Page size (1-500) Example: `50`
- `offset` (query, optional, string) — Offset Example: `0`
- `active` (query, optional, string) — Filter out withdrawn currencies Example: `true`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/currencycodes-api/v1/list?limit=50&offset=0&active=true"
```

**Response:**
```json
{
    "data": {
        "count": 50,
        "total": 178,
        "currencies": [
            {
                "code": "AED",
                "name": "UAE Dirham",
                "active": true,
                "numeric": "784",
                "countries": [
                    "UNITED ARAB EMIRATES (THE)"
                ],
                "minor_unit": 2
            },
            {
                "code": "AFN",
                "name": "Afghani",
                "active": true,
                "numeric": "971",
                "countries": [
                    "AFGHANISTAN"
                ],
                "minor_unit": 2
            },
            {
                "code": "ALL",
                "name": "Lek",
                "active": true,
                "numeric": "008",
                "countries": [
                    "ALBANIA"
                ],
                "minor_unit": 2
            },
            {
                "code": "AMD",
                "name": "Armenian Dram",
                "active": true,
                "numeric": "051",
                "countries": [
                    "ARMENIA"
                ],
                "minor_unit": 2
            },
            {
                "code": "AOA",
                "name": "Kwanza",
                "active": true,
                "numeric": "973",
                "countries": [
                    "ANGOLA"
                ],
                "minor_unit": 2
            },
            {
            
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Service metadata

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

**Response:**
```json
{
    "data": {
        "service": "currencycodes-api",
        "endpoints": {
            "GET /v1/code": "Currency detail by alphabetic code (code=, e.g. USD) or numeric (number=, e.g. 840).",
            "GET /v1/list": "List all currencies (limit, offset, active=true to filter out withdrawn).",
            "GET /v1/meta": "This document.",
            "GET /v1/search": "Search currencies by code, name or country (q=, min 2 chars).",
            "GET /v1/country": "Currencies used by a country (country=, e.g. Japan)."
        },
        "description": "ISO 4217 currency-code register (no FX rates): 3-letter alphabetic code, 3-digit numeric code, official currency name, minor-unit decimal places and the countries using each currency. The metadata a checkout or accounting system needs to format and validate money. No key.",
        "total_currencies": 307,
        "active_currencies": 178,
        "countries_indexed": 261
    },
    "meta": {
        "timestamp": "2026-06-08T18:25:12.980Z",
        "request_id": "6ba814c8-0dff-4f3a-9fbf-ea6b33325b7b"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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