About this endpoint
What it does
Returns daily reference rates and converted amounts from one currency, crypto or metal code to up to 20 others, for the latest day or a past date. It can also return a daily history over a date range, or the list of supported codes.
Request Body
| Parameter | Type | Description |
|---|---|---|
| to | String / String Array | Required unless listCurrencies is true. One code, or a list of codes, to convert to. Not case-sensitive. Max 20 items. |
| from | String | Code to convert from: a currency, crypto or metal. Not case-sensitive. Default: USD. |
| amount | Number | Amount to convert. Default: 1. Range: 0.000001 to 1000000000000 (1e12). |
| source | ENUM | Which rate set to use. Allowed values: auto, broad, ecb. Default: auto. auto uses the broad set and falls back to the ECB set. broad uses only the broad set (340 codes). ecb uses only the ECB set (about 30 fiat currencies). |
| date | String | Past date in YYYY-MM-DD format. Omit for the latest rates. ECB currencies start on 1999-01-04; crypto, metals and the broad set start on 2024-03-02. Can't be in the future. Not allowed with startDate or endDate. |
| startDate | String | First day of a daily history, in YYYY-MM-DD format. Send together with endDate. History covers the ECB currencies only. |
| endDate | String | Last day of the history, in YYYY-MM-DD format. Not before startDate. The range can be at most 366 days. |
| listCurrencies | Boolean | true returns the supported codes instead of rates. With source: ecb it returns the ECB codes only. Default: false. |
Only these fields are accepted. Any other field returns a 400 error.
Response
Returns a JSON object with a result object. Its fields depend on the request: a rate lookup, a history range or a currency list. Every response has source, sourceId, live, note and disclaimer.
| Parameter | Type | Description |
|---|---|---|
| result.source | String | Where the rates come from: Publicly available reference rates. |
| result.sourceId | ENUM | Which rate set was used. Allowed values: reference-broad (broad set), reference-daily (ECB set). |
| result.live | Boolean | Always false: these are daily reference rates, not live prices. |
| result.note | String | Explains that the rates refresh about once a day and differ from bank, card or exchange prices. |
| result.disclaimer | String | Use notice. |
| result.from | String | The code you converted from, in uppercase. Rate lookups and history. |
| result.amount | Number | The amount used. Rate lookups and history. |
| result.date | String | Date of the rates used (YYYY-MM-DD). Rate lookups and currency lists. |
| result.requestedDate | String | The date you sent. Only when you sent date. |
| result.stale | Boolean | true if older rates were used than expected. Present on most rate lookups and lists. |
| result.rates | Object | One rate per target code: 1 unit of from in that code. Rate lookups. |
| result.converted | Object | amount converted into each target code. Rounded to 2 decimals, with more decimals for small values (for example 8 for BTC). Rate lookups. |
| result.typeNote | String | Only when crypto or metal targets are included. Says these are reference values, not tradable prices. |
| result.crossRateNote | String | Present on source: ecb rate lookups. Explains how rates between two non-base currencies are calculated. |
| result.fallback | Boolean | Only when auto fell back to the ECB set. Then true. |
| result.to | String Array | The target codes. History only. |
| result.startDate | String | First day of the range. History only. |
| result.endDate | String | Last day of the range. History only. |
| result.observations | Integer | Number of days in series. History only. |
| result.series | Object Array | One row per working day with a published rate. History only. |
| result.series[].date | String | The day (YYYY-MM-DD). |
| result.series[].rates | Object | The rate for each target code that day. |
| result.series[].converted | Object | amount converted into each target code that day. |
| result.summary | Object | One entry per target code with first, last, high, low and changePct (percent change from first to last). History only. |
| result.note2 | String | Extra note. For history: weekends and holidays have no row. For lists: what the type values mean. |
| result.currencyCount | Integer | Number of supported codes. Broad currency list only. |
| result.fiatCount | Integer | Number of fiat currencies. Broad currency list only. |
| result.metalCount | Integer | Number of metals. Broad currency list only. |
| result.otherCount | Integer | Number of crypto and other codes. Broad currency list only. |
| result.currencies | String Array | All supported codes. Currency lists only. |
| result.details | Object Array | One row per code. Broad currency list only. |
| result.details[].code | String | The code, for example BTC. |
| result.details[].type | ENUM | Allowed values: fiat, metal, other (crypto and codes outside ISO 4217). |
| result.details[].name | String | The full name, for example Bitcoin. |
Notes
- Errors return
400witherror(a plain-language message) andcode. Codes seen:invalid_input(missingto, more than 20 targets, unknown code, range over 366 days,datesent with a range,startDatewithoutendDate, a future date, unknown field) anddate_before_data_start(a crypto, metal or broad-set rate before 2024-03-02, or a crypto code in a history range).amountoutside the range returnsamount_out_of_range. - With
source: auto, a weekenddatereturns that day's broad-set rate.



