Exchange Bot

by Bkper

The Exchange Bot helps you keep multiple Books in different currencies in sync.

It works by mirroring transactios from one book to other books, automatically applying updated conversions rates.

Exchange Bot

For every transaction in a base book, it will generate another transaction on associated books, with different currencies.

The Bot also adds a menu item to your books too update gains and losses, based on exchange rates variation.

Exchange Bot Menu

The Exchange Bot uses rates from Open Exchange Rates by default, but any rates source endpoint can be used.


The Exchange Bot work by listening for TRANSACTION_CHECKED events in your book, applying exchange rates from the an exchange rates endpoint and recording another transaction to the associated books:

Exchange Bot Flow

The books are associated by its Collection, so a transaction in one book is mirrored on all books of the Collection.

Book Properties

In order to proper setup the Exchange Bot on your books, some book properties should be set:

You can associate multiple books.


exc_code: USD

Group Properties

As the rates changes over time, the balances on accounts with different currencies than the book should be adjusted and by gain/loss transactions. The transactions are triggered by an item on menu:

Exchange Bot Menu

The accounts will be selected by matching the group names with exc_code from associated books, or by the exc_code property set on Groups.

By default, an account with prefix Exchange_ will be used for each exc_code of associated books. You can change the default account by setting a exc_account custom property in the account Group, with the name of exchange account to use. Example:

exc_account: Assets_Exchange

The first exc_account property found will be used, so, make sure to have only one group per account with the property set, to avoid unexpected behavior.

Transaction Properties

To bypass dynamic rates from the endpoint and force use of fixed amount for a given exc_code, just use the following transaction properties:

This is specially useful for remitences, when fees and spread will be processed later on gain/loss updates.

Some additional properties uses to track converted amounts:


exc_code: UYU
exc_amount: 1256.43

That will generate a transaction in the current book of amount $1000, as well as another transaction on UYU book of $U35790.76.

Exchange rates endpoint

By default, the free endpoint is used to fetch rates, but any endpoint can be provided, from other third party providers such as Fixer or Open Exchange Rates, or build your own.

To change the default endpoint, set the exc_rates_url book property.


exc_rates_cache: 3600  #optional cache

Supported expressions:

Despite of which endpoint choosed, the json format returned MUST be:

  base: string;
  date: string; //yyyy-MM-dd
  rates: {
    [key: string]: number;


  "base": "EUR",
  "date": "2020-05-29",
  "rates": {
    "CAD": 1.565,
    "CHF": 1.1798,
    "GBP": 0.87295,
    "SEK": 10.2983,
    "EUR": 1.092,
    "USD": 1.2234,