Bkper Portfolio Agent

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

Overview

The Portfolio Agent monitors transactions in Financial Books and automatically tracks quantities of traded instruments in a separate Portfolio Book. Key features include:

• Automatic synchronization between Financial Books and the Portfolio Book.
• Realized Results tracking using the FIFO method.
• Support for both Historical Cost and Mark-To-Market accounting.
• Handling of fees, interests, and multiple exchange rates.
• Period closing support with Forward Date functionality.

Configuration

To configure the Bkper Portfolio Agent, ensure the following setup:

Collection:

• Both Financial and Portfolio Books must reside within the same Collection.
• Define a single Portfolio Book per Collection. This book is identified by either:
  • Setting the decimal places to 0 (zero) in the book settings, or
  • Setting the stock_book property to true.

Base Book (optional):

• Optionally, you can define a single Base Book per Collection for tracking realized exchange results separately. Refer to the Realized Results Service for more details.
• The Base Book is identified by setting the exc_base property to true.

Properties Interactions:

The Portfolio Agent 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.

Realized Results Service

The Portfolio Agent uses the FIFO (First-In, First-Out) method to calculate realized results, ensuring accurate tracking of gains and losses.

Key Features:

• Realized Results Tracking: Accurately tracks gains and losses from trade operations using the FIFO method. The Portfolio Agent 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 Agent 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 Agent can also adjust associated Interest accounts.

Important: The Portfolio Agent 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.

Forward Date Service

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 Agent 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.