The Portfolio Bot automatically manages investment portfolios by tracking stocks, bonds, and other financial instruments on a dedicated portfolio book. Synchronizes transactions, maintains precise quantities, and calculates realized gains/losses using the FIFO method.
The Portfolio Bot monitors transactions in Financial Books and automatically tracks quantities of traded instruments in a separate Portfolio Book. Key features include:
To configure the Bkper Portfolio Bot, ensure the following setup:
stock_book property to true.exc_base property to true.The Portfolio Bot interacts with various properties to manage and synchronize data effectively. Ensure these properties are correctly set in your books for optimal performance.
Book Properties:
Financial Books:
exc_code: Required - The exchange code representing the book currency.Portfolio Book:
stock_book: Optional - true/false - Identifies the Portfolio book of the collection. If not present, decimal places must be set to 0 (zero) in the book settings.stock_historical: Optional - true/false - Defines if realized results calculations should consider only historical costs and rates.stock_fair: Optional - true/false - Defines if realized results calculations should consider only fair costs and rates.Observations:
If neither stock_historical nor stock_fair properties are set, calculations will consider both historical and fair basis. For more information, check out this article on Mark-To-Market vs. Historical Cost accounting.
Group Properties:
stock_exc_code: Required - Defines the exchange code representing the currency of the instrument that will have quantities mirrored into the Portfolio Book. Only transactions from/to accounts within groups with the stock_exc_code property set will be mirrored.Account Properties:
stock_fees_account: Optional - The fees account used by the broker account. The broker account is identified by having an associated fees account.Transaction Properties:
instrument: Required - The instrument name or ticker.quantity: Required - The quantity of the instrument stock operation to track.trade_date: Required - The date of the stock operation.order: Optional - The order of the operation, if multiple operations happened in the same day.fees: Optional - The value included in the transaction amount corresponding to fees.interest: Optional - The value included in the transaction amount corresponding to interests.cost_hist: Optional - The amount representing the historical cost of the transaction. This property is necessary only if calculating realized results in both historical and fair basis.cost_base: Optional - The amount representing the cost of the transaction in the base currency. Providing a cost_base effectively fixes a specific exchange rate for the operation, as it determines a unique ratio between the instrument currency and the base currency.cost_hist_base: Optional - The amount representing the historical cost of the transaction in the base currency. Providing a cost_hist_base also fixes a specific historical exchange rate for the operation. This property is necessary only if calculating realized results in both historical and fair basis.Observations:
Neither cost_base nor cost_hist_base properties are necessary if there is no Base Book defined in the collection.
The Portfolio Bot uses the FIFO (First-In, First-Out) method to calculate realized results, ensuring accurate tracking of gains and losses.
Realized Results Tracking: Accurately tracks gains and losses from trade operations using the FIFO method. The Portfolio Bot records these results in both the Portfolio and Financial Books, and if a Base Book is defined, it separates realized exchange results from stock market results.
Mark-to-Market Valuation: Optionally, the Portfolio Bot can automatically adjust the market value of remaining instruments in Financial Books to match the last realized price. This procedure is known as Mark-To-Market. It is particularly useful for liquidated Bonds instruments, where the Portfolio Bot can also adjust associated Interest accounts.
Important: The Portfolio Bot automatically adds properties to transactions in the Portfolio Book when calculating realized results. These properties are used for state and log control. It also manages trade states by checking/unchecking transactions (see Transaction States). These properties and states must not be manually altered.
To close a period and set a closing date for the Portfolio Book, instruments must be carried forward to the next period by setting a Forward Date in the Portfolio Book.
Each unprocessed transaction will have its date, price, and exchange rate updated to the current valuation, while retaining a log of its previous state. Once the last instrument is forwarded, a closing date is set on the Portfolio Book one day before the Forward Date.
After forwarding, future FIFO calculations will use the new Forward valuation. To calculate gains/losses solely on a historical basis, ensure the stock_historical property is set to true in the Portfolio Book.
Important: The Portfolio Bot automatically adds properties to transactions in the Portfolio Book during the forwarding process. These properties are used for state and log control and must not be manually altered.
