> For the complete documentation index, see [llms.txt](https://help.bots.business/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.bots.business/import-and-integrations/currency-services.md).

# Display currency conversions

Read and validate cached CurrencyQuote rates, convert an amount, and replace the old free CurrencyConverter endpoint.

`CurrencyQuote` exposes cached fiat and cryptocurrency quotes in the runtime. It is separate from the installed `Libs.CurrencyConverter` wrapper and its external free API.

Use quotes for informational conversion. Before displaying a value, check that the currencies exist and that the underlying data is recent enough for your use case.

## Convert an amount

{% code title="Convert an amount · Example 1" overflow="wrap" %}

```javascript
const fiat = CurrencyQuote.fiat;
const crypto = CurrencyQuote.crypto;
if (!fiat || !crypto ||
    typeof fiat.getCachingTime !== "function" ||
    typeof crypto.getCachingTime !== "function") {
  Bot.sendMessage("Quotes are unavailable. Please try later.");
  return;
}
const fiatAge = fiat.getCachingTime();
const cryptoAge = crypto.getCachingTime();
const maxAge = 3600; // Your application's freshness limit, in seconds.
if (!isFresh(fiatAge, maxAge) || !isFresh(cryptoAge, maxAge)) {
  Bot.sendMessage("Quotes are too old for this estimate.");
  return;
}
if (!fiat.EUR || !crypto.BTC) {
  Bot.sendMessage("A required currency is unavailable.");
  return;
}
const amount = CurrencyQuote.convert({ amount: 15, from: "EUR", to: "BTC" });
Bot.sendMessage("Estimated BTC for 15 EUR: " + amount);

function isFresh(age, limit) {
  return Number.isFinite(age) && age >= 0 && age <= limit;
}
```

{% endcode %}

The freshness limit in this example is your chosen policy, not a promise that every quote refreshes within an hour. Both rates must be valid for a cross-family conversion.

## Reference

* `CurrencyQuote.fiat.SYMBOL` and `CurrencyQuote.crypto.SYMBOL` return available quote values.
* `fiat.getCachingTime()` and `crypto.getCachingTime()` report seconds since their respective updates when initialized.
* `CurrencyQuote.convert({ amount, from, to })` calculates using the available USD-based rates. Missing symbols throw. The current function rejects zero because `amount` is checked for truthiness; handle a zero amount before calling it.
* Provider details may exist under `crypto.details`; do not assume every symbol has a detail record or fixed fields.

The result is not a provider invoice, executable trade, guaranteed exchange rate, or fee calculation. Use the payment provider's actual invoice data when requesting payment.

<details>

<summary>The older CurrencyConverter library</summary>

## The older CurrencyConverter library

The checked Store source calls `http://free.currencyconverterapi.com/api/v5/convert` and maintains its own 30-minute cache. The provider currently reports the free API as down without a promised restoration date. A valid-looking old library therefore does not establish a working data source. [Provider status](https://free.currencyconverterapi.com/).

For existing bots, inventory calls to `Libs.CurrencyConverter.convert`, replace them with a verified quote source and update the callback contract at the same time. The old callback puts the converted value in command parameters, whereas `CurrencyQuote.convert` returns a number immediately. Do not replace one call mechanically while keeping the old callback command.

For another external rate source, use [HTTP](/bjs-reference/http.md), validate its response and timestamp, and define an explicit unavailable-data response.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.bots.business/import-and-integrations/currency-services.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.