Exchange Bot

by Bkper

The Bkper Exchange Bot keeps balance values, in different Bkper Books with other currencies, synchronized.

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

Exchange Bot

The Bkper Exchange Bot must be installed on all books in a Collection. For every transaction in a book within the Collection, it records another transaction on other Books with different currencies in the Collection.

The Bkper Exchange Bot installation adds a menu item to books to record gains and loss transactions, based on exchange rates variation.

Exchange Bot Menu

The Bkper Exchange Bot default exchange rates are read at the moment of the gain/loss update from Open Exchange Rates Any other exchange rate source url can be used.

The chart of account (CoA) is synchronized on books in a Collection by the Bkper Exchange Bot.

Find a detailed explanation and instalation instructions on Bkper Help Bkper Exchange Bot Help


The Exchange Bot works 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.

Account Properties

By default, an account with suffix EXC will be used for each account. You can change the default account by setting a exc_account custom property in the account Account or Group, with the name of the 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 Open Exchange Rates endpoint is used to fetch rates, but any endpoint can be provided, from other third party providers such as Fixer or you can build your own.

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



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,