ISO 4217 currency codes explained

Every time your code writes "EUR" or "JPY", it relies on a standard. ISO 4217 currency codes give each currency a unique identifier that banks, payment networks, accounting software and exchange rate APIs like fxapi all understand. Knowing how the codes are built – and where the exceptions are – prevents formatting bugs, rounding errors and broken lookups when a currency changes.

ISO 4217 is the international standard for currency codes. It assigns each currency a three-letter alphabetic code (such as USD), a three-digit numeric code (such as 840) and a minor unit that says how many decimal places the currency uses. The list is maintained by SIX Financial Information on behalf of ISO.

Who publishes ISO 4217

The standard itself is published by the International Organization for Standardization; the current edition is ISO 4217:2015. Day-to-day maintenance – adding codes for new currencies, withdrawing old ones – is handled by SIX Financial Information AG, which runs the maintenance agency on behalf of ISO and the Swiss Association for Standardization (SNV).

SIX publishes three lists free of charge:

List One is available as XML and XLS. Amendments are announced as they are approved, which is why a hard-coded list in your code will go stale.

Structure of an ISO 4217 code

Each entry has three key fields:

Alphabetic code (alpha-3)

The first two letters are the ISO 3166-1 alpha-2 country code; the third is usually the first letter of the currency’s name: US + Dollar, JP + Yen, CH + Franc. There are deliberate exceptions. The euro is EUR because it belongs to no single country. A redenominated currency often changes its third letter so old and new units can coexist – Mexico’s MXN (N for “nuevo”) or Belarus moving from BYR to BYN.

Numeric code

The numeric code usually matches the ISO 3166-1 numeric country code (USD = 840, JPY = 392). It exists for systems that cannot use Latin letters and for legacy formats such as some card and banking messages. Like the alpha code, it can change when a currency is redenominated: the Mauritanian ouguiya moved from MRO (478) to MRU (929) in 2018.

Minor unit

The minor unit tells you how many decimal places to use when storing or displaying amounts:

There are oddities: the Mauritanian ouguiya and the Malagasy ariary divide into 5 subunits but are listed with a minor unit of 2. Never assume “two decimals” globally – read the minor unit per currency. The currency rounding and precision guide shows how to apply it.

X-codes: currencies without a single country

Codes beginning with X cover units that do not belong to one ISO 3166 country:

Two of these deserve a note for developers. XDR is not a currency anyone pays with – the IMF describes the SDR as an international reserve asset valued against the US dollar, euro, Chinese renminbi, Japanese yen and pound sterling. And XTS is a safe placeholder for unit tests: it will never collide with a real currency.

Crypto tickers are not ISO 4217

ISO 4217 does not assign codes to cryptocurrencies. BTC, ETH, USDT and similar symbols are exchange and market conventions. Some systems use XBT for bitcoin because it follows the X-prefix pattern, but it is not an official ISO code either.

This matters when you validate input: a strict ISO 4217 validator will reject BTC. If your product handles both fiat and crypto, validate against the list your data provider supports rather than against ISO alone. fxapi includes 16 cryptocurrencies (BTC, ETH, SOL, USDC and others) using the same request and response format as fiat codes – see the crypto exchange rates API.

Historic codes and code changes

When a country redenominates or adopts another currency, ISO withdraws the old code and assigns a new one: HRK → EUR in Croatia (2023), VEF → VES in Venezuela (2018), SLL → SLE in Sierra Leone (2022). Old codes stay relevant for as long as you have data or invoices that use them. The full list, with dates and conversion ratios, is in currency redenominations and code changes.

How fxapi uses ISO 4217

fxapi keys every response by its currency code and accepts any supported code as base_currency or target:

• 160 active fiat currencies with their ISO 4217 alphabetic codes.
• 11 legacy codes kept for historical data: BYR, CUC, HRK, LTL, LVL, MRO, SLL, STD, VEF, ZMK, ZWL.
• 4 precious metals with their ISO X-codes – XAU, XAG, XPT, XPD – priced per troy ounce (see the gold and silver price API).
• 16 cryptocurrencies using common market tickers.
• Newer codes such as VES, MRU, STN, SLE, ZWG and XCG.

The /v1/currencies endpoint returns metadata for each code – name, symbol, symbol_native, decimal_digits, rounding, type (fiat, metal or crypto) and countries as ISO 3166-1 alpha-2 codes – so you can format amounts and map currencies to countries without maintaining your own table.

Example: validate and format codes with /v1/currencies

curl -G "https://api.fxapi.com/v1/currencies" \
  -d currencies=JPY,KWD,EUR \
  -H "apikey: $FXAPI_KEY"

A Python helper that loads the list once at startup, rejects unknown codes and rounds to the right number of decimals:

import os
from decimal import Decimal, ROUND_HALF_UP
import requests

resp = requests.get(
    "https://api.fxapi.com/v1/currencies",
    headers={"apikey": os.environ["FXAPI_KEY"]},
    timeout=10,
)
resp.raise_for_status()
CURRENCIES = resp.json()["data"]          # keyed by code, e.g. CURRENCIES["JPY"]

def format_amount(amount: Decimal, code: str) -> str:
    meta = CURRENCIES.get(code.upper())
    if meta is None:
        raise ValueError(f"Unsupported currency code: {code}")
    places = Decimal(1).scaleb(-meta["decimal_digits"])
    return f"{amount.quantize(places, rounding=ROUND_HALF_UP)} {code.upper()}"

print(format_amount(Decimal("1234.5678"), "JPY"))   # 1235 JPY
print(format_amount(Decimal("1234.5678"), "KWD"))   # 1234.568 KWD

The endpoint counts as one request and changes rarely, so cache it for a day or more. Add as_html=true to get a ready-made HTML table of all codes. Browse individual currencies on the currencies hub, for example the euro.

Key takeaways

• ISO 4217 assigns an alpha-3 code, a numeric code and a minor unit to each currency; SIX maintains the list.
• The minor unit varies (0, 2, 3, even 4) – never hard-code two decimals.
• X-codes cover metals, the SDR, supranational currencies and test values.
• Crypto tickers are not ISO codes; validate against your provider’s supported list.
• Codes change. Load them from an API or the SIX list instead of hard-coding. Start with what is an exchange rate API if you are new to rate data.

Frequently asked questions