Currency Converter

Raffi includes a currency converter with real-time exchange rates from the Frankfurter API. A second source, the Bank of England’s daily rates, can be enabled as a backup.

Overview

Convert between currencies by typing an amount with a trigger character (default $) followed by target currency codes. Exchange rates are cached for one hour to minimize API requests.

Usage

Basic Syntax

<trigger><amount> to <currency>
<trigger><amount><source> to <target>

Examples

Default Currency

$10 to eur
# Converts 10 USD to EUR

Explicit Source

$50 gbp to usd
# Converts 50 GBP to USD

No Spaces

$100eur to jpy
# Converts 100 EUR to JPY

Custom Trigger

€10 to usd
# With trigger set to €

Configuration

Configure the currency converter in your raffi.yaml:

addons:
  currency:
    enabled: true
    trigger: "$"
    default_currency: USD
    currencies:
      - USD
      - EUR
      - GBP
      - JPY
      - CAD
      - AUD

Configuration Options

addons.currency.enabled boolean (default: true)

Enable or disable the currency converter.

addons.currency.trigger string (default: $)

Character that starts a conversion. Common options: $, €, £, ¥.

addons.currency.default_currency string (default: USD)

Source currency when the query names none, so $10 to eur converts from USD. Use a 3-letter ISO code such as EUR, GBP or JPY.

addons.currency.currencies array[string] (default: [USD, EUR, GBP])

Currencies to convert into when you type an amount with no target. With the default source currency, $100 lists 100 USD in every currency of this list except USD, and $100 gbp does the same from GBP. A conversion with a target, such as $10 to jpy, works for any supported currency whether or not it is in the list.

addons.currency.close_on_action boolean (default: true)

Close Raffi after Enter copies a result. Leave it unset to follow general.close_on_action.

addons:
  currency:
    close_on_action: false

addons.currency.sources array (default: [frankfurter])

Where exchange rates come from, in the order the sources are tried. Raffi contacts the next source only when the previous one could not be reached or returned none of the requested rates. With the default, only Frankfurter is ever contacted. See Exchange Rate Sources for the available sources and how to point one at your own mirror.

addons:
  currency:
    sources:
      - frankfurter
      - bank_of_england

Custom Trigger

Dollar ($)

addons:
  currency:
    trigger: "$"
    default_currency: USD

Usage: $100 to eur

Euro (€)

addons:
  currency:
    trigger: "€"
    default_currency: EUR

Usage: €100 to usd

Pound (£)

addons:
  currency:
    trigger: "£"
    default_currency: GBP

Usage: £100 to eur

Target Currencies

Choose which currencies an amount alone is converted into:

addons:
  currency:
    enabled: true
    currencies:
      - USD  # US Dollar
      - EUR  # Euro
      - GBP  # British Pound
      - JPY  # Japanese Yen
      - CAD  # Canadian Dollar
      - AUD  # Australian Dollar
      - CHF  # Swiss Franc
      - CNY  # Chinese Yuan
      - INR  # Indian Rupee
      - BRL  # Brazilian Real

Tip

Without a currencies list, an amount alone is converted into USD, EUR and GBP. Typing a target, as in $10 to chf, works for any supported currency either way.

Exchange Rate Sources

By default Raffi uses the Frankfurter API and nothing else:

• Free and open-source
• No API key required
• Updated daily with European Central Bank rates
• Rates are cached for 1 hour locally (5 minutes when a backup source answered)

addons.currency.sources chooses the sources and their order. The first entry is the preferred one; each later entry is contacted only when every source before it failed or had none of the requested rates. Available sources:

Source	Contacts	Rates
frankfurter	api.frankfurter.dev	European Central Bank, about 30 currencies
bank_of_england	allratestoday.com	Bank of England daily rates, about 20 currencies

To keep Frankfurter but fall back to the Bank of England when it is down:

addons:
  currency:
    sources:
      - frankfurter
      - bank_of_england

Note

Each source listed is a separate website that may be contacted, and it sees the currency codes you convert between. bank_of_england is never used unless you list it. If you want a single source, list only that one, or leave sources unset for Frankfurter alone. An empty list (sources: []) contacts nothing, and conversions show an error.

A source can also be fetched from another address, such as a mirror or a proxy on your own network that serves the same response format:

addons:
  currency:
    sources:
      - provider: frankfurter
        url: https://rates.example.org/v1/latest
      - provider: bank_of_england
        url: https://rates.example.org/boe.json

The first source gets up to 10 seconds to answer; each later source gets 4 seconds, so a backup never doubles the wait. When no source can provide a single requested rate, the result row shows an error naming each source and why it failed, in the order they were tried. A currency pair that a source does not quote simply moves on to the next source; the pairs it does quote are still shown.

Cache Behavior

1. First Request

   Fetches live rates from Frankfurter API

2. Subsequent Requests

   Uses cached rates (valid for 1 hour)

3. After 1 Hour

   Automatically fetches fresh rates on next conversion

Conversion Patterns

Implicit Source Currency

When you don’t specify a source currency, the default_currency is used:

$10 to eur      # 10 USD → EUR
$50 to gbp      # 50 USD → GBP
$100 to jpy     # 100 USD → JPY

Explicit Source Currency

Specify both source and target currencies:

$10 usd to eur  # 10 USD → EUR
$50 gbp to usd  # 50 GBP → USD
$100 eur to jpy # 100 EUR → JPY

Compact Format

No spaces between amount and currency:

$100eur to jpy  # 100 EUR → JPY
$50gbp to usd   # 50 GBP → USD

Keyboard Shortcuts

Enter copies the converted amount. Escape closes Raffi.

Disable Currency Converter

To disable the currency converter:

addons:
  currency:
    enabled: false

Requirements

Caution

Internet connection required for fetching exchange rates (cached for 1 hour)

Note

The converter needs wl-copy, xclip or xsel to copy results to the clipboard

Examples

$1000 to eur     # Planning trip to Europe
$99 usd to gbp   # Compare prices
€500 to usd      # Invoice conversion
$10000 to jpy    # Currency exchange

Troubleshooting

No conversion results

1. Check internet connection
2. Verify currency codes are correct (3-letter ISO codes)
3. Ensure enabled: true in config
4. Read the error row: it names each source in addons.currency.sources and why it failed
5. Check that the Frankfurter API (or the sources you configured) is accessible

Wrong default currency

Set default_currency in your config:

addons:
  currency:
    default_currency: EUR  # Change from USD to EUR

Trigger not working

Make sure your trigger character doesn’t conflict with other features:

addons:
  currency:
    trigger: "$"  # Or try "€", "£", etc.