Zum Inhalt springen
GET AI agent ready /v1/currency-list/list

Currency List API - ISO 4217 Codes, Symbols, and Countries

Returns metadata for 160+ ISO 4217 currencies: the code, display name, symbol, decimal digit count (e.g., 2 for USD, 0 for JPY, 3 for BHD), and the countries that use it (ISO 3166-1 alpha-2). Pass filter (or q) to substring-match on code or name.

Parameters

string

Optional query-string filter. Matches code or name (case-insensitive).

string

Alias for filter.

Code examples

curl -X POST https://api.botoi.com/v1/currency-list/list \
  -H "Content-Type: application/json" \
  -d '{"filter":"euro","q":"eur"}'

When to use this API

Populate currency dropdowns

Use the full list to render a currency selector with symbol + code. The countries array lets you group or sort by region. No external dependency needed for standard currency metadata.

Format money with correct decimal places

The decimal_digits field tells you how many decimals to format. USD uses 2 ($10.50), JPY uses 0 (¥1500), BHD uses 3 (BHD 1.250). Prevents common "always 2 decimal" formatting bugs.

Map countries to currencies

Combine with /v1/country/lookup. Given a country code, find the currency where countries includes that code. Useful for auto-defaulting currency on country selection.

Frequently asked questions

Why is this a GET endpoint when most others are POST?
List endpoints conform to REST convention (GET for reads, POST for actions). A deprecated POST /list alias is still available for backward compatibility but new code should use GET.
How do I search?
Pass ?filter=eur or ?q=eur in the query string. Matches happen on both code and name substrings, case-insensitive. "euro" returns EUR and any currency named "Euro-" as well.
Are cryptocurrencies included?
No. Only ISO 4217 fiat currencies. For crypto prices and metadata use /v1/crypto/search and /v1/crypto/price.
What about USD-equivalent territories (like Ecuador)?
USD's countries array includes every country that has adopted USD as its currency (Ecuador, El Salvador, Panama, Puerto Rico, plus US territories). That's 18 entries in total.
Are the decimal_digits always correct?
They follow ISO 4217. Some currencies with hyperinflation (e.g., VES) have official decimal digits but are commonly quoted with different precision in practice. Use the official value for accounting; adjust for display when needed.

Get your API key

Free tier includes 5 requests per minute with no credit card required. Upgrade for higher limits.

Sign up free View full docs