Whenever you process payments, display prices, or build a multi-currency application, you'll run into ISO 4217 — the international standard that defines a three-letter code for every currency in the world. This guide explains what ISO 4217 is, how the codes are structured, why they matter, and how to fetch a programmatic, always-updated list via the Country Data API.
What is ISO 4217?
ISO 4217 is the international standard published by the International Organization for Standardization (ISO) that defines codes for currencies. The standard was first published in 1978 and is maintained by the ISO Technical Committee 68 (TC 68), the same body that handles financial services standards. It's the universal language used by banks, payment processors, exchanges, and any system that needs to refer to a currency unambiguously.
Without ISO 4217 you'd run into immediate confusion: a "dollar" could mean US dollars, Canadian dollars, Australian dollars, Hong Kong dollars, Singapore dollars, or any of a dozen others. The "peso" is used by Mexico, Argentina, Chile, Colombia, the Philippines, Cuba, the Dominican Republic and Uruguay — each completely separate currencies. ISO 4217 solves this with three letters that uniquely identify every active currency on the planet.
How ISO 4217 Codes Are Structured
Every ISO 4217 code is exactly three uppercase letters. The first two letters typically come from the ISO 3166-1 alpha-2 country code (the same letters used for top-level domains like .us or .de), and the third letter is usually the first letter of the currency name.
For example:
USD— United States + DollarGBP— Great Britain + PoundJPY— JaPan + YenCHF— Confederatio Helvetica (Switzerland's Latin name) + FrancCNY— ChiNa + Yuan
There are exceptions. The Euro is EUR (not country-specific because it spans multiple ISO 3166 codes). Cryptocurrencies and metals also have ISO 4217 codes that don't follow the country-letter pattern: XAU for gold, XAG for silver, XBT historically used for bitcoin (though most exchanges prefer BTC).
Numeric Codes
In addition to the three-letter alphabetic code, ISO 4217 also assigns a three-digit numeric code to each currency. These numeric codes are useful in environments where letters are unreliable (legacy banking systems, EDI files). For example, USD is 840, EUR is 978, GBP is 826, and JPY is 392. Most modern APIs and applications use the alphabetic code because it's human-readable.
The Most Common Currencies and Their Codes
Here is a quick reference for the most-used currencies in international commerce:
| Code | Currency | Used by (examples) | Symbol |
|---|---|---|---|
| USD | US Dollar | United States, Ecuador, El Salvador, Panama, East Timor | $ |
| EUR | Euro | 20 EU member states (Germany, France, Spain, Italy, etc.) | € |
| JPY | Japanese Yen | Japan | ¥ |
| GBP | British Pound | United Kingdom | £ |
| CNY | Chinese Yuan | China | ¥ |
| AUD | Australian Dollar | Australia, Kiribati, Nauru, Tuvalu | A$ |
| CAD | Canadian Dollar | Canada | C$ |
| CHF | Swiss Franc | Switzerland, Liechtenstein | CHF |
| HKD | Hong Kong Dollar | Hong Kong | HK$ |
| SGD | Singapore Dollar | Singapore | S$ |
| SEK | Swedish Krona | Sweden | kr |
| KRW | South Korean Won | South Korea | ₩ |
| NOK | Norwegian Krone | Norway | kr |
| NZD | New Zealand Dollar | New Zealand, Cook Islands, Niue | NZ$ |
| INR | Indian Rupee | India, Bhutan | ₹ |
| MXN | Mexican Peso | Mexico | $ |
| BRL | Brazilian Real | Brazil | R$ |
| RUB | Russian Ruble | Russia | ₽ |
| ZAR | South African Rand | South Africa, Lesotho, Namibia, Eswatini | R |
| TRY | Turkish Lira | Turkey, Northern Cyprus | ₺ |
Why You Need an API for Currency Codes
You might be tempted to hard-code a list of currencies in your application. Don't. Currency codes change more often than you'd think:
- New currencies are added. South Sudan introduced
SSPin 2011. The Bolivar was redenominated several times in Venezuela:VEB→VEF(2008) →VES(2018). - Currencies are retired. The Lithuanian litas (
LTL) was retired in 2015 when Lithuania adopted the Euro. The same happened with the Latvian lats (LVL) in 2014. - Some countries officially use multiple codes. Cuba has both
CUP(Cuban peso) and previouslyCUC(convertible peso, retired in 2021).
An always-updated source eliminates the risk of stale data costing you transactions or compliance issues.
Fetching ISO 4217 Codes via REST API
Country Data API exposes currency information through the /v1/countries endpoint. Each country object includes its currency code, currency name and currency symbol, so you can build a complete currency dropdown with one request:
GET https://api.countrydataapi.com/v1/countries
Authorization: Bearer YOUR_API_KEY
The response includes objects like:
{
"name": "Germany",
"iso2": "DE",
"iso3": "DEU",
"currency": "EUR",
"currency_name": "Euro",
"currency_symbol": "€"
}If you only need countries that use a specific currency (for example, all countries that use the Euro), use the countries by currency endpoint:
GET https://api.countrydataapi.com/v1/countries/by-currency?currency=EUR
Authorization: Bearer YOUR_API_KEY
This is particularly useful if you're building a payment gateway, a currency converter, or a tax calculation engine that needs to enumerate jurisdictions by currency.
Building a Currency Dropdown — JavaScript Example
Here's how to build a deduplicated, alphabetized currency selector in plain JavaScript using the API:
async function loadCurrencies() {
const res = await fetch('https://api.countrydataapi.com/v1/countries', {
headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const countries = await res.json();
// Deduplicate by currency code
const seen = new Set();
const currencies = countries
.filter(c => {
if (seen.has(c.currency)) return false;
seen.add(c.currency);
return true;
})
.map(c => ({
code: c.currency,
name: c.currency_name,
symbol: c.currency_symbol
}))
.sort((a, b) => a.code.localeCompare(b.code));
const select = document.getElementById('currency-select');
for (const cur of currencies) {
const opt = document.createElement('option');
opt.value = cur.code;
opt.textContent = `${cur.code} — ${cur.name} (${cur.symbol})`;
select.appendChild(opt);
}
}
Common Pitfalls
Don't assume a country uses one currency. Switzerland accepts both CHF and EUR in many places. Cuba had two parallel currencies until 2021. Several Pacific Island states use the AUD, USD or NZD with no native currency.
Don't display the symbol without context. The "$" symbol is used by USD, CAD, AUD, MXN, ARS and many others. Always pair the symbol with the ISO code in financial contexts.
Don't use lowercase or 4-letter codes. ISO 4217 codes are always exactly three uppercase letters. Sending usd or USDOLLAR to a payment gateway will get you rejected.
Be careful with cryptocurrency codes. Bitcoin is commonly written as BTC, but ISO 4217 historically uses XBT in the metals/special category. Most exchanges use BTC. Cryptocurrencies are not formally part of the ISO 4217 standard for fiat currencies.
FAQ
How many ISO 4217 codes are there? There are about 180 active currency codes for fiat currencies, plus a handful of special codes for precious metals and historical currencies.
Are cryptocurrency codes part of ISO 4217? Not formally. ISO 4217 is for sovereign currencies and a few special items like gold (XAU), silver (XAG), platinum (XPT) and palladium (XPD). Cryptocurrencies are not officially registered.
What's the difference between alphabetic and numeric ISO 4217 codes? The alphabetic code (e.g., USD) is human-readable and used in most APIs and applications. The numeric code (e.g., 840) is used in legacy systems and EDI formats. Both refer to the same currency.
How often does the ISO 4217 list change? Several times a year, although changes are typically minor. New currencies are introduced when new countries form or existing ones redenominate. Old currencies are deprecated when countries adopt a different currency (often the Euro).
Get Started
To start fetching currency data via the API, create a free account and get your API key in seconds. Plans start at $9.99/month with 10,000 monthly requests, scaling to enterprise volumes. Then check out the countries by currency endpoint documentation for full request and response details.