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.
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.
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:
The books are associated by its Collection, so a transaction in one book is mirrored on all books of the Collection.
In order to proper setup the Exchange Bot on your books, some book properties should be set:
exc_code: Required - The book (currency) exchange code.exc_rates_url: Optional - The rates endpoint url to use. Default: exchangeratesapi.io.
rate.exc_base: Optional - true/false - Define a book as a base and only mirror transactions to other books that matches the exchange base from accounts.exc_on_check: Optional - true/false - True to only exchange on CHECK event. Default is false, performing exchange on POST events.You can associate multiple books.
Example:
exc_code: USD
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:
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.
exc_code: The (currency) exchange code of the accounts of the group.exc_account: The name of exchange account to use.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.
To bypass dynamic rates from the endpoint and force use of fixed amount for a given exc_code, just use the following transaction properties:
exc_code: The exchange code to override.exc_amount: The amount for that transaction, in the specified exchange code.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: The exchange base code used to convert the transaction.exc_rate: The exchange base rate used to convert the transaction.Example:
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.
By default, the free exchangeratesapi.io 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.
Example:
exc_rates_url: https://data.fixer.io/api/${date}?access_key=*****
exc_rates_cache: 3600 #optional cache
Supported expressions:
${date}: The date of transaction in the standard ISO format yyyy-mm-dd.${agent}: The agent for the fetch request. 'app' for Gain/Loss update from menu. 'bot' for transaction post.Despite of which endpoint choosed, the json format returned MUST be:
{
base: string;
date: string; //yyyy-MM-dd
rates: {
[key: string]: number;
}
}
Example:
{
"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,
}
}
