The Portfolio Bot (Formerly the Stock bot) keeps track of quantities, profits and losses and revaluations related to financial operations.
Profit or Loss is calculated on a FIFO basis.
Overview
In Bkper you track different entities (money and quantities) in different books.
To track finances you need a financial book and to track the number of securities (bonds, stock) or other assets you need another book to track quantities, in this case called an Portfolio book.
For the Portfolio Bot to understand its boundaries of operation, it requires that (all) these books are in one Bkper Collection.
Note: you can have as many currencies in one collection for the Portfolio Bot as you need.
The Portfolio Bot is triggered in the financial books on each Post and check transaction event. Once a stock operation is identified by some properties, that we’ll explain a bit later in this help guide, it will send the transaction data to the Portfolio Bot operating on the Portfolio book which records the same transaction resembling it in quantities.
Note: You always work (record, post, trash) on the financial book and never on the portfolio book!
Portfolio Bot Status
Gray: working properly
Red: error
No icon: not installed
Portfolio Bot Flow
1. Post a transaction that represents a stock order purchase on a financial book.
e.g. 100 Bank account >> Exchange buy 10 GOOG
2. This Post event Triggers the Portfolio Bot on this financial book.
3. The Portfolio Bot finds the required stock properties on the transaction and gets into Action.
4. First the Bot posts a Fee transaction and a Stock purchase transaction on the financial book
e.g. 10 Exchange >> Fees
90 Exchange >> GOOG
5. You check the stock purchase transaction.
90 Exchange >> GOOG
6. This check event Triggers the Portfolio Bot and it gets in action to post the quantity on the Portfolio book.
7. It gathers all the data from this transaction including the new property information and sends it to the Portfolio Bot on the Portfolio book.
8. The Portfolio Bot that is installed on the Portfolio book records a transaction resembling the same purchase but in quantities rather than value.
Installation
Books And Collection
Create the Financial Book(s)
Create one Portfolio Book (formerly Instruments book)
Add all the books to one Bkper Collection
Install the Stock Bot on all the Books in the Collection.
Accounts
The accounts you need for the Portfolio Bot to work properly.
On the Financial Book
Asset type accounts
A bank account: JP Morgan
An exchange or broker account: JP Morgan Broker
A stock account: GOOG
Outgoing type account
A Fees account: Broker Fees
On the Portfolio Book
Asset type account
The same stock account: GOOG
Groups
The groups you need for the Portfolio Bot to work.
On the Financial Book
Create a group and add the securities or assets (GOOG) to it.
e.g. NASDAQ or Portfolio US
On the Instruments Book
Create a group and add the securities or assets (GOOG) to it.
e.g. NASDAQ or Portfolio US
Note: once you have the portfolio Bot installed in your collection with the book properties it will keep this group in sync.
Configuration
To operate correctly the Portfolio Bot requires Book, Group, Account and Transaction properties.
Learn more about Properties
Book Properties
On the Financial Books
The exchange code is required in the book properties of a Financial books
exc_code : USD
This property is required in all the financial books in the collection.
exc_code : EUR
On the Instruments Book
This property is required in the instrument book properties of the Portfolio book
stock_book: true
stock_historical: true [optional]
stock_fair: true [optional]
Note: if you set either stock_historical or stock_fair to true the Portfolio Bot will not calculate the realized results with the other option.
Group Properties
On all the "stock" groups in the financial and Instruments Books add the stock_exc_code property.
On the Financial Books
Financial Book USD is required in the NASDAQ or Portfolio US Group
stock_exc_code : USD
Financial Book EUR is required in the DAX or Portfolio EUR Group
stock_exc_code : EUR
On the Instruments Book
Portfolio Book is required in the NASDAQ or Portfolio US Group
stock_exc_code : USD
Portfolio Book is required in the DAX or Portfolio EUR Group
stock_exc_code : EUR
The Portfolio bot uses this exchange code to keep Accounts in these Groups in sync between the Financial books and the Portfolio Book in the Collection.
So if you add a new security or asset account to a Portfolio Group in a financial book, it will automatically be added to the same group on the Portfolio book and vice versa.
It also helps the Portfolio Bot operating on the Instrument Book to find the way back to the origin of the transaction. ( Financial Book > Portfolio Group > Account)
Note: you can give this group property any value that makes sense to your operation but in one financial book the book property exc_code should have the same value as this group property stock_exc_code in the portfolio book. For example financial book property exc_code: USD and portfolio book group property stock_exc_code:USD
Account Properties
The exchange or broker Account (JP Morgan Exchange) has a fees account property that indicates the outgoing type account (red) where stock operation fees are booked.
The exchange or broker account requires the fee account property (even if you do not have or record fees)
stock_fees_account : Broker Fees
Transaction Properties
Transactions that represent the purchase or sale order at the exchange or broker account should have the following properties :
instrument : GOOG
quantity : #
trade_date : mm/dd/yyyy
fees : $ [optional]
interest : $ [optional]
order: # [optional]
Portfolio Operations
Purchase of Portfolio Assets
This section explains your actions to record the purchase of a Portfolio Asset, the events to which the Portfolio Bot listens and takes action in your book that corresponds to it (the event).
You: Post a portfolio purchase with the required properties in the Financial Book.
05/06/2025 165 JP Morgan >> JP Morgan Exchange buy
instrument: GOOG
quantity: 1
trade_date: 05/07/2025
The Portfolio Bot listens to the Post and Check Events.
Portfolio Bot: On each Post Event it checks for the required properties to get in action and posts the actual purchase of the Asset.
In case it finds the minimally required properties it will post a transaction in the financial book.
05/06/2025 165 JP Morgan Exchange >> GOOG buy
fees:0
interests:0
price: 165
quantity: 1
settlement_date: 2025-05-07
Note: The Portfolio Bot posts a second transaction in case you put in the fee property.
You: Check the actual purchase operation (the transaction posted by the portfolio bot)
Portfolio Bot: On each Check Event it checks for the required properties to get in action and posts the actual entry of the Quantity of the Asset in the portfolio book.
In case it finds the minimally required properties it will post a transaction in the Portfolio book.
05/06/2025 1 Buy >> GOOG buy
original_amount: 165
original_quantity: 1
purchase_price: 165
stock_exc_code: USD
After these transactions you have value and the quantity of the Portfolio Assets in the Financial and Portfolio book in sync.
Sale of Portfolio Assets
You: Post a portfolio sale with the required properties in the Financial Book.
05/06/2025 166 JP Morgan Exchange >> JP Morgan sell
instrument: GOOG
quantity: 1
trade_date: 05/07/2025
Portfolio Bot: On each Post Event it checks for the required properties to get in action and posts the actual sale of the Asset.
In case it finds the minimally required properties it will post a transaction in the financial book.
05/06/2025 166 JP Morgan Exchange >> GOOG sale
fees:0
interests:0
price: 166
quantity: 1
settlement_date: 2025-05-07
You: Check the actual sale operation (the transaction posted by the Portfolio Bot)
Portfolio Bot: On each Check Event it checks for the required properties to get in action and posts the actual entry of the Quantity of the Asset in the Portfolio Book.
In case it finds the minimally required properties it will post a transaction in the Portfolio book.
05/06/2025 1 GOOG >> Sell sell
original_amount: 165
original_quantity: 1
purchase_price: 165
stock_exc_code: USD
Portfolio Bot Operations
Calculate Realized Results
After operating (purchases and sales) the Portfolio Bot can calculate the Realized Results for you and Posts the result on your Financial book.
You: Open the Portfolio Book,
Select the Asset(s) that you would like to calculate the realized results of.
Select the Portfolio Bot from the More menu.
(the first time you need to authenticate and authorize the Portfolio Bot to make these calculations)
Check the market to market checkbox
Set the Date you want to calculate the Realized Results for and Press the button Calculate.
Portfolio Bot: Updates the properties on the Transactions included in this calculation and Checks these transactions in the Portfolio Book.
Posts two transactions in the Financial book according to the Book Properties set on the portfolio book (stock_historical and stock_fair).
The first transaction posts the gain "to" or loss "from" a Liability account.
The second transactions posts the difference between the Purchase Price and the Sale price of the Asset "to" (loss) or "from" (gain) the same Liability used in the first transaction.
Closing a Period and setting a Forward Date
Before entering in the details on how to do this in Bkper it is good to understand why Forwarding is used when calculating results with the FIFO (First-In, First-Out) method.
When using the FIFO method, each sale is matched against the oldest available purchases, preserving the correct cost basis. To maintain accurate tracking across periods, it’s essential to carry forward:
• Remaining inventory lots
• Mark-to-Market (MTM) valuations
• Realized Results (RR) calculations
This ensures the next period has the correct starting point to apply FIFO logic and avoids reprocessing past activity.
Without forwarding, FIFO can’t determine which lots are still available, leading to incorrect gain/loss and inventory valuation.
You: Open the Portfolio Book,
Select the Asset(s) that you are setting the forward date for.
Select the Portfolio Bot from the More menu.
Set the Date you want to use as the forward date and Press the text Set Forward Date.
At this point it is good practice to record any Realized Results that were not yet calculated till this Date. Select the text Calculate RR.
Once this is done, press the button Forward Date.
Reset Portfolio Bot Operations
In case you forgot any operations before you calculated the Realized Results or you found a mishap you can proceed to Reset the Portfolio Bot operations on its Assets.
The Reset procedure will revert all the realized result and Exchange Realized Results Transactions it posted and checked from the Financial book and it will remove any properties it added to Transactions to keep track of the open batches and prices of the portfolio Assets.
Note: in case you have the Exchange Bot installed on your Collection together with the Portfolio Bot, the reset will not undo the Exchange Bot its entries. You will have to do this seperately.
You: Open the Portfolio Book,
Select the Asset(s) that you are resetting.
Select the Portfolio Bot from the More menu.
Set the Date you want to use as the reset date.
Press the button Reset.
Portfolio Bot: Reverts all the Transactions for the Asset it has recorded Before to calculate Realized Results and Exchange Realized Results it has recorded in the past for the(se) asset(s). It also removes properties it previously added to transactions to keep track of open batches and prices of portfolio assets.
Template