Skip to main content

Bkper Portfolio Bot

Record Trading operations keeping track of quantities, realized and unrealized profits and losses.

Updated today

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 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. Check the stock purchase transaction.

90 Exchange >> GOOG

6. This check event Triggers the portfolio Bot and it gets in action to record 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

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 in the NASDAQ or Portfolio US Group

stock_exc_code : USD

Financial Book EUR in the DAX or Portfolio EUR Group

stock_exc_code : EUR

On the Instruments Book

Portfolio Book in the NASDAQ or Portfolio US Group

stock_exc_code : USD

Portfolio Book 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

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]

Transactions

The Transaction you post to put the Portfolio Bot at work.

05/05/2025 165 JP Morgan >> JP Morgan Exchange buy

The Portfolio Bot is triggered on the financial books by Posting the transaction that has the instrument, quantity and trade_date properties. It continues its actions when the posted transaction has an instrument account that is part of the stock group identified by the stock_exc_code property.

The Portfolio Bot is triggered on the financial book by checking the transaction that has the quantity property. It continues its actions when the checked transaction has a stock account that is part of the stock group identified by the stock_exc_code property.

Action from the Portfolio Bot

The Portfolio Bot on the financial book collects the data from the posted stock order transaction.

From the collected data on the posted transaction it creates two transactions on the Financial Book.

On the Financial Book

A transaction that actually represents the purchase of the Stock

n Exchange Account >> Stock

The Portfolio Bot also adds properties to the newly recorded transaction that refers to the stock order.

fees:$
interest:$
price:$$
quantity: #

A transaction that represents the payment of the fees on this operation

n Exchange Account >> Fees

The Portfolio Bot on the financial book collects the data from the checked stock transaction.

On the Instruments Book

The collected data is passed to the Portfolio Bot on the instruments book which records a transaction that represents the same operation but the balance value of the stock account in this book represents the quantity rather than its value.

The Portfolio Bot also adds properties to the newly recorded transaction that refers to the financial operation.

original_amount: $$
original_quantity: n
purchase_price: $

Template

Did this answer your question?