Exchange API — Documentation

Smart Number Formatting

The API returns both raw numbers and pre-formatted display strings. Each currency follows its canonical formatting rules — no more "1.0934€".

Standard (2 decimals)

1,093.40 USD

Raw: 1093.4 → "1,093.40"

Zero-decimal (JPY, KRW)

14,329 JPY

Raw: 14328.7 → "14,329"

Three-decimal (KWD, BHD)

30.845 KWD

Raw: 30.8452 → "30.845"

Step-rounded (SYP, LBP)

14,330 SYP

Raw: 14328 → rounded to nearest 5

Rate: Large (≥1000)

14,329

No decimals for huge rates

Rate: Normal (≥1)

1.09

2 decimals for standard rates

Rate: Small (<0.01)

0.000034

Up to 6 significant figures

Flags & Currency Metadata

Each currency comes with rich metadata from the /currencies endpoint.

Example currency object
{
  "code": "USD",
  "name": "US Dollar",
  "flag": "🇺🇸",
  "countryCode": "US",
  "countryName": "United States",
  "flagUrl": "https://flagcdn.com/w320/us.png"
}

Flag emoji: Mapped for 170+ currencies. Falls back to ISO 3166 derivation.
Flag image: High-resolution PNG from FlagCDN, perfect for UI rendering.

GET

Health Check

/health

Simple health probe. Returns 200 when the server is up.

Response
{
  "status": "ok",
  "time": "2025-01-15T12:00:00.000Z"
}

Try it

GET

List Currencies

/currencies

Returns all supported currencies with names, emoji flags, country metadata, and flag image URLs.

Response
{
  "currencies": [
    {
      "code": "EUR",
      "name": "Euro",
      "flag": "🇪🇺",
      "countryCode": "EU",
      "countryName": "European Union",
      "flagUrl": "https://flagcdn.com/w320/eu.png"
    },
    ...
  ]
}

Try it

GET

Exchange Rates

/rates?base=USD&symbols=EUR,GBP

Get live exchange rates for a base currency. Optionally filter to specific symbols. Falls back across providers automatically.

Parameter	Type	Description
base*	string	Base currency code (e.g. "USD", "EUR")
symbolsoptional	string	Comma-separated target currencies (e.g. "EUR,GBP,JPY")

Response
{
  "base": "USD",
  "date": "2025-01-15",
  "rates": {
    "EUR": 0.9134,
    "GBP": 0.7892
  },
  "meta": {
    "provider": "exchangeRateApi",
    "fallbackUsed": false,
    "updatedAt": "2025-01-15T12:00:00.000Z",
    "requestedSymbols": ["EUR", "GBP"],
    "sources": { "EUR": "exchangeRateApi", "GBP": "exchangeRateApi" }
  }
}

Try it

GET

Convert Amount

/convert?from=EUR&to=USD&amount=100

Convert an amount between two currencies. Returns both raw numbers and smart-formatted display strings.

Parameter	Type	Description
from*	string	Source currency code
to*	string	Target currency code
amount*	number	Positive amount to convert

Response — with display formatting
{
  "from": "EUR",
  "to": "USD",
  "amount": 100,
  "rate": 1.0934,
  "result": 109.34,
  "date": "2025-01-15",
  "display": {
    "amount": "100.00",
    "result": "109.34",
    "rate": "1.09"
  },
  "meta": {
    "provider": "exchangeRateApi",
    "updatedAt": "2025-01-15T12:00:00.000Z"
  }
}

Try it

GET

Historical Timeseries

/timeseries?base=USD&symbols=EUR&start=2025-01-01&end=2025-01-10

Get historical exchange rates for a date range. Useful for charts and trend analysis.

Parameter	Type	Description
base*	string	Base currency code
symbols*	string	Comma-separated target currencies
start*	string	Start date (YYYY-MM-DD)
end*	string	End date (YYYY-MM-DD)

Response
{
  "base": "USD",
  "symbols": ["EUR"],
  "start": "2025-01-01",
  "end": "2025-01-10",
  "points": [
    { "date": "2025-01-01", "rates": { "EUR": 0.9234 } },
    { "date": "2025-01-02", "rates": { "EUR": 0.9198 } }
  ],
  "meta": {
    "provider": "frankfurter",
    "fallbackUsed": false,
    "updatedAt": "2025-01-15T12:00:00.000Z"
  }
}

Try it

GET

Provider Status

/source-status

Shows real-time availability and health of all exchange rate data providers.

Response
{
  "providers": [
    {
      "name": "exchangeRateApi",
      "available": true,
      "lastSuccessAt": "2025-01-15T12:00:00.000Z",
      "lastErrorAt": null,
      "lastErrorMessage": null
    }
  ]
}