&Ace.Jones; &Ace.Jones.mail;
&Michael.Carpino; &Michael.Carpino.mail;
&Jack.H.Ostroff; &Jack.H.Ostroff.mail;
2024-12-01
5.2.0

# Investments

## Investments in &kmymoney;

In very general terms, an investment is any allocation of money with the expectation of a future benefit. &kmymoney;'s Investment accounts are designed for one particular type of investment: securities. A security investment (or just a security) is an instrument for investing money that is traded on a market with the intention of a profitable return in the form of either appreciation in value, income such as interest or dividends, or a combination of both. Stocks and mutual funds are the most common securities; and they are the ones specifically supported within &kmymoney;. Bonds have a different financial structure, but can usually be handled by &kmymoney;. Futures, commodities, options, and more complex investment instruments like derivatives are other types of investments, but &kmymoney; has no special functionality for them. As long an investment has similar characteristics to a stock or mutual fund, it can be tracked.

### Investment Accounts

A &kmymoney; Investment Account holds a collection of Securities, also referred to as Equities. An Investment account contains transactions, recording activities such as buys, sells, dividends, reinvestments, yields, splits and income of those investments. Each transaction in an Investment account must relate to a specific security.

It is common for an account at a Brokerage Institution to contain both securities and cash. In &kmymoney;, an Investment account holds only securities. It cannot contain any cash balance. This was a design decision made when Investment accounts were first included in &kmymoney;. It might be changed in the future, but that is likely to be done as part of a significant revision in all of &kmymoney;'s handling of investments. For now, any cash needed to purchase a security or gained from a sell or dividend transaction requires the use of a Brokerage Account.

### Brokerage Accounts

When an investment transaction uses (to buy a security) or produces case, such as from a sale or dividend, that transaction must refer to another account which can hold the money, most commonly a checking account. You can specify any suitable account for any investment transaction which requires one. However, &kmymoney; has the concept of a Brokerage Account, also sometimes referred to as a Cash Account, which is the default account for such transactions.

When you create an Investment Account, you have the option of creating an associated Brokerage Account with it. The default name of the Brokerage account will be the name of the investment account with " (Brokerage)" appended. &kmymoney; assumes this naming convention in several actions related to investments. Following the convention is not absolutely required, but without it, you will often have to take extra steps to complete the entry of transactions.

### Base Currency

Your &kmymoney; data file has a base currency, specified when the file was created. In addition, an Investment account has a base currency, specified when it is created. Separately, each security has its own base currency. This is the currency in which it is traded. When a price quote is entered for an investment, the currency of the value given is always its base currency. A stock on the NYSE (New York Stock Exchange) would be in US dollars (USD), and one on an Australian market would be in Australian dollars (AUD). The base currency for a security does not need to be the same as the base currency for the Investment account holding that security.

## The Investments View

The Investments View provides a summary of all your investments, similar to several of the other major views. It has a single display area, with two tabs. The first tab, Equities, provides a high level view of those securities held within a single Investment Account, as specified in the Select Account: dropdown. The second tab, Securities, is similar, but provides slightly different information about all the stocks, mutual funds, bonds, &etc;, you track in &kmymoney;.

### The Equities tab

investments view equities tab
investments view equities tab

The distinction between equities and securities on these two tabs may seem somewhat arbitrary, and is known to cause confusion. Perhaps the terminology may be changed in the future, if anyone can propose a different set of terms that doesn't have the same or other problems. However, as stated above, in the current terminology, an equity as shown on the Equities Tab currently refers to the details of an investment within an investment account. Within &kmymoney;, it is a sub-account of an investment account, denominated in a security. A security as shown on the Securities Tab provides access to the security information unrelated to any account. A security can be referenced in multiple equities, which can also be said as different equities can be denominated in the same security.

At the top of the list of equities is the Select Account: dropdown, where you can select the investment account for which you want to see the specific investments. If you have checked Synchronize account selection of Ledgers View and Investments View in the configuration dialog, then if you are looking at an investment account in the Ledgers View, and then switch to the Investments View, that account will already be selected.

Similar to the Institutions and several other views, the Equities tab displays several columns with descriptive and summary information about each equity. As with the Institutions View, you can select which columns are shown by right-clicking any column heading and selecting or unselecting the checkbox next to the name of the column.

Name

  The name of the equity. This column is always displayed. All the other columns are optionally display, as described above.

Symbol

  This is trading symbol as used on the market where the equity is traded.

Quantity

  This is the number of shares of the equity you own in this investment account. The precision of this and the other value columns can be adjusted, as described later in this section.

Price

  This is the most recent price for this equity known to &kmymoney;.

Value

  This is the total value of this investment in this investment account. It should be the same as the product of the Quantity and the Price.

Last Price Update

  This is the date of the most recent price. Prices can be updated in several ways, all described later in this section.

The order for any of the columns except Name can be changed by left clicking the column header, and dragging it to the left or right.

### The Securities tab

investments view securities tab
investments view securities tab

At the top of the list of securities is a search box. Because this tab lists all investments you own in all Investment accounts, it can grow lengthy, and you can use the search box to find a specific entry on the list, by typing any part of its name.

Security

  The name of the security. This column is always displayed. All the other columns are optionally display, as described above. The names should be the same names as shown in the Name column on the Equities tab.

Symbol

  This is trading symbol as used on the market where the equity is traded. It is also the same as the same column in the Equities tab.

Type

  This is the specific type of investment being tracked. Currently, only Stocks, Bonds, and Mutual Funds are possibly values.

Market

  This is the market where this investment is traded.

Currency

  This displays the symbol of the currency in which this investment is traded.

Fraction

  This is the smallest fraction used when entering the amount of this investment in any transaction.

As with the Equities tab, the order for any of the columns except Security can changed by left clicking the column header and dragging it to the left or right.

## Creating an Investment Account

The first step on the path to working with investments is to create an Investment account to hold your defined securities. Choose the Account New account... menu item to begin the process. Create an account as previously described in the Account section, making sure to choose Investment as the type of account.

To work with the new investment account, open that account in the Ledgers View, as previously described.

### Price Entry

Whenever you enter or edit a buy, sell, or reinvest transaction, you need to specify the number of shares, price per share, and the total amount of the transaction. As described here you actually specify only two of those values, and &kmymoney; calculates the third. The default price entry setting for new Investment Accounts is Price per share, but this can be changed to Total amount when you edit the account.

## Adding Investments to Your Account

To add individual securities to your Investment Account, navigate to the Investments View, select the Equities tab, and choose the Investment account where the investment is held from the Select Account dropdown.

Right-click in any empty space in the view. This brings up the Investment Options context menu. Choose New investment... from this menu. This launches the New Investment Wizard which you use to create your new Investment.

### New Investment Wizard

The first thing you will be asked to enter is the name of the investment. This is the name which will be used on the Equities Tab. You will also be asked to specify the type of investment. The currently available values are Stock, Bond, and Mutual Fund. If your investment is not strictly one of these types, it is ok to mislabel here, as the type is not currently used to restrict or control what you can do with the investment.

new investment wizard type
new investment wizard type

Next, the investment details page is presented. The following information is entered on this page:

new investment wizard details
new investment wizard details

- Trading Symbol. A trading or ticker symbol is an abbreviation used to identify a publicly traded security of a particular instrument on a particular market or exchange. &kmymoney; requires a trading symbol for all securities; however some investments do not have symbols. In this case, you will need to make up a symbol for it.

  The dropdown includes all trading symbols which currently exist in your data file. If you select one of these &kmymoney; will reuse the referenced security for the new equity, unless you check the "Create duplicates of symbol," in which case a new security will be created with the same symbol.

  If you plan to use Online Quotes to retrieve prices for this investment, ensure that the symbol exactly matches the symbol used by your quote source. Yahoo covers most of the world's markets, and requires a suffix on the end of symbols outside the US, to specify the country or market. For example, Rubicon Limited on the New Zealand market should be entered as RBC.NZ.

- Full name of the investment, although it can be a friendly, readable name, ⪚, Advanced Micro Devices, Inc. This name is also referred to as the security.

- Fraction. This indicates the degree of precision to which your holdings are measured. For example, in the US most mutual funds measure holdings to three decimal places, so you would enter 1000 in this field. Stocks are often measured to only whole units, so you could enter 1 for a stock like this, but you would use 10000 for a stock measured to four decimal digits. You'll want to mirror the same decimal places that your brokerage uses to record your securities so the transactions amounts match within &kmymoney;. Using extra precision will not cause a problem, but using too little precision can cause rounding errors which can make &kmymoney; unable to exactly match the information shown by your brokerage institution.

- Trading market. Where the investment is traded. This is an optional field which is provided for your convenience. This information is not used anywhere else within &kmymoney;.

- Identification number. An optional field to enter additional identification information you might like to keep track of. Stocks often have such a number, which can sometimes be used as well as the symbol for retrieving information about it. Again, this information is not used anywhere else.

- Trading currency. The market exchange currency in which this investment is traded. This is typically the currency of the country that the security trades within. It is usually, but not necessarily, the same as the default currency for the Investment account holding that security.

- Price entry. When you enter or edit a buy, sell, or reinvest transaction for this investment, this dropdown indicates whether you want to enter the price per share or the total for all shares or to follow the default for the account, which was specified when the Investment Account was created.

- Price Precision. This is a small integer, specifying the number of decimal places used to specify the price of this investment in the specified currency. This is used for both purchase and sale price, the current price, and also for the total value of the investment.

- Remainder. This is a dropdown with values Round, Ceil, Floor, and Truncate, which specifies what &kmymoney; should do in the last decimal place of values. For example, this can be relevant when you specify the total price of a purchase rather than an exact price per share.

Finally, you're presented with the Online Update screen. This is where you tell &kmymoney; how you would like to update the prices of your investment, if you do want to use an online source. The following items are set here:

- Use Finance::Quote. This is an option for &gnucash; users who are used to this style of quotes. Most users can leave this unchecked. Finance::Quote is a Perl module, so to use it, you would need to have both Perl and its Finance::Quote module installed.

- Online Source. The online source you'd like to use for this particular investment. The most common choice is Yahoo Finance. Try that first, and if the investment cannot be found using this source, then experiment with the others.

  Note that although &kmymoney; knows how to extract security prices from web pages retrieved from Yahoo and many other sources, those sources have been known to change the format of those pages, which can prevent &kmymoney; from successfully extracting the desired information. This is an unfortunately too frequent topic of discussion on the various support channels. However, if fetching prices works for a long time and then you start to get errors, please consider this possibility.

- Factor. A multiplier that should be applied to quotes retrieved for this investment. This is most commonly needed for UK stocks where the price quoted is in pence (1/100), and the stock is denominated in pounds. In this case, enter 0,01 for the Factor.

### Using a Security in more than one Investment Account

Caution

It is possible to own shares of the same security in more than one investment account, such as a regular investment account and also a retirement account. In previous versions of &kmymoney; it was easy to unintentionally have &kmymoney; treat them as if each of the securities was a different underlying investment. That often caused confusion, as well as duplicate storage, such as having two copies of the entire price history of the equity. Currently, it is much easier to avoid this situation, but it is important to pay attention when creating new equities within an Investment Account.

When you add a security to an investment account, and that investment already exists in another investment account, you need to be careful if you want to reuse it rather than creating a new, duplicate entry. In the New Investment Wizard, after selecting the name and type of investment and clicking Next, when you select an existing Trading Symbol some of the other fields on the form will be filled in with the relevant information from the existing security, and the existing security will be used unless you select the "Create duplicate of symbol" checkbox.

## Editing an Investment

The Equities tab of the Investments View lists your current holdings in this Investment account. Right-click any of the investments to bring up the Investment Options context menu, where you can add, edit, or delete an individual investment from this account. Also, you can update the price of an investments here either manually or via its online source. In addition, it is possible to close an empty account, or to reopen a closed account.

If you choose to Edit an Investment, you will use the Investment detail wizard, which looks and functions just like the New Investment Wizard, as described in the previous section.

Right-clicking an entry in the Securities tab produces a Securities Options context menu, where you can edit or delete a security. Actually creating a security is done when you create an equity in an Investment account, and do not choose to reuse an existing security, as discussed above.

## Investment Transactions

investment transaction form
investment transaction form

Investment transactions are entered and edited in the Ledgers view, as with transactions in other types of accounts. However, the fields shown will be different, and vary depending on the activity or transaction type. Investment transactions have some additional elements, described below.

### Activity

The Activity for an investment transaction describes what type of action is happening to the security. The following activities are supported:

Buy/Sell

  Use to record the purchase or sale of an individual security. This action requires an account to transfer the funds from/to, which defaults to the Brokerage account, if one has been defined for this Investment account.

Dividend/Yield/Interest Income

  Also known as a Cash Dividend, this action is used when you receive an interest or dividend disbursement of cash from your security. This action also requires an account to transfer the funds to. The three terms are used interchangeably.

Reinvest dividend

  This is a dividend where the proceeds are used to purchase additional shares of the security.

Add/Remove shares

  A simple increase or decrease in the number of shares you own. This should be used very rarely, because it's uncommon for shares to just show up in your account (or to disappear) unless it's a purchase, sale, or dividend reinvestment. One use of these activities is for some situations &kmymoney; does not natively handle, such as the exchange of some number of shares of a security for a different number of shares of a different security or different class of the same security.

Split shares

  This is used when the stock is split. Enter the ratio of the split in the Split Ratio field. For example, in a 3:2 split, enter 1.5. Reverse splits, where the ratio is less than one, such as 2:3, although uncommon, are also allowed.

### Security

Each investment transaction must be associated with an individual security. The dropdown shows all securities you own in the current Investment account - select the one for this transaction.

### Account

For any transaction which generates or requires money, you must enter the account where the money is transferred to/from. If your investment account has an associated Brokerage account, it is usually best to transfer the funds there. This applies to funds for purchase or sale of the security, as well as for fees paid or interest or dividends earned.

### Shares, Price & Total Amount

For buy, sell, and reinvestment transactions, the number of shares, the price per share, and the total amount of the transaction must be established. You can enter any two of these, and &kmymoney; will calculate the third. It is usually best to enter just the total amount and the number of shares, because these are the known facts of the transaction. &kmymoney; will automatically calculate the price per share. Note that there is only one entry field for the price, and it will be labeled Transaction amount or Price/share depending on the setting of the Price entry option when the investment was set up.

### Fees

With many investment transactions you can include the fees (or commission) you paid the broker. If you enter a category for the fee, then a field will be shown to the right where you can enter the amount of the fee. If you need to enter more than one fee for the transaction, you can use the Split Transactions feature. In this case, when you complete entering all the splits, the total amount of the fees will be shown to the right.

### Interest

This is how you enter an interest or dividend payment from a security. As with fees, if you enter a category, then a field will be shown to the right where you can enter the amount. You can also use the split transaction feature, if required.

## Working With Foreign Investments

&kmymoney; supports multiple currencies, and there are situations where this can be very useful, if not essential. However, doing so requires extra care to assure accurate records. As noted above, when you add a security, you must specify its trading currency. This might not be the same as the base currency for your &kmymoney; file, and it also might not be the same as the base currency for the investment account in which you hold the security or for the account where you transfer your funds to/from for buys/sells/dividends.

Consider a hypothetical case, where your base currency is USD. You have an investment account in EUR, and a brokerage account also in EUR. In that investment account, you hold shares of TietoEnator, which is traded in SEK.

When you enter a buy transaction for this investment, use SEK as the currency. So if you buy 100 shares at a price of SEK 248.00, for a total of SEK 24,800.00, enter these values in the transaction.

When you choose the brokerage account to fund the transfer, you'll be warned that it's in a different currency.

investment transaction currency warning
investment transaction currency warning

When you finish entering the transaction, you will be prompted for a price update to the investment account's currency, in this case, SEK -> EUR. Review the documentation on Entering Prices Manually for more information on the price dialog.

exchange rate editor
exchange rate editor

If you then switch over to the brokerage account, you will see the transaction as EUR 2,254.54, assuming an exchange rate is 11.0000 SEK/EUR.

## Updating Security Prices

There are two ways of updating the prices for your investments. You can either enter the price manually or have &kmymoney; fetch it from the web.

### Manual Price Updates

You can enter prices for your investments using the same Price Editor as used for currencies.

### Online Price Quotes

&kmymoney; has the ability to download the latest prices for your securities and currencies via the web.

#### How Online Quotes Work

At your request, &kmymoney; will fetch a page from the web that contains the latest price for each security. By default, prices are fetched from finance.yahoo.com, and are subject to the terms and conditions of that site.

The online quote lookup uses the security's trading symbol to find the price. Therefore, it is important to set the symbol correctly. Yahoo supports stocks from most major world markets, so it is usually just a matter of finding the correct symbol. For example, TietoEnator trades on the Stockholm Stock Exchange market, and its Yahoo symbol is TIEN.ST.

To find the trading symbol for a security supported by Yahoo, use the Symbol Lookup feature at finance.yahoo.com. You should have set the trading symbol when initially entering the security into &kmymoney;.

#### Assigning a Quote Source

In order to get online price quotes, you first have to enable the feature for each security or currency you want updated, by setting an Online Quote Source. This is the name of the service from which the quote should be fetched. &kmymoney; ships with several sources to choose from. Yahoo is the recommended default source, and should work for most investments and all currencies.

To assign a quote source for an investment, navigate to the investment summary view for the account in which the security is held. Edit the security by right-clicking it and selecting Edit Investment .... In the Investment Detail Wizard, click Next twice, for the Online Update section. In the Online source dropdown box, select the online source for your needs.

Versions of &kmymoney; starting with 0.9 contain support for the Perl Finance::Quote package for obtaining online quotes. This is intended primarily as a convenience for those users converting from the &gnucash; finance package, which uses it as its native method. If you do select this option, you should see a different list of sources, those supported by Finance::Quote. If the list is empty, it suggests that the package is not properly installed. See their web site at http://finance-quote.sourceforge.net for more information.

#### Adjusting a quote

Some online sources do not report the price in a base quantity (⪚, EUR) but in a fraction (⪚, Cent). Using this information for a price will produce wrong values for your investments.

If this is the case for your online source, you can use the Factor field to enter an adjusting factor. For the above mentioned example the factor would be 0.01.

The Factor field is only available if a Quote Source has been selected.

#### Fetching Quotes

Typically, you will update the prices for all your securities and currencies as a single operation. Choose the Tools Update Stock and Currency Prices... menu item to bring up the online price quotes dialog. Press Update All to fetch quotes for all securities and currencies in your &kmymoney; file.

online update stock and currency prices
online update stock and currency price

#### Adding or Editing Quote Sources

Adding or editing quote sources is not recommended for anyone but the most technical user. You should feel comfortable reading HTML and writing complex regular expressions. If this doesn't sound like you, please use one of the suggested support channels if you are having problems with a particular source or if none of the quote sources work for you. If looking for a source for prices for a security not found by one of the existing sources, ideally, please point us to a web page where these prices can be obtained. Additionally you can consult with members of the KDE Community Forum for &kmymoney; as they may already have a solution available for your needs.

If you do feel up to the challenge, here's how it works. The quote sources are contained in the settings dialog. Choose the Settings Configure &kmymoney; menu item. From there, choose the Online Quotes section. You can choose an existing source to edit, or create a new one. When you are done with your changes, be sure to press the Update button before exiting the dialog. Your changes are not saved by default.

The first thing to consider in an online quote source is the URL. This is the page that is fetched from the web. You will see a %1 in all sources, and a %2 in currency sources. For investments, %1 is replaced by the trading symbol. For currencies, %1 is replaced by the From currency, and %2 is replaced by the To currency. This URL is then fetched, all HTML tags are (optionally) removed, and that stripped file is then sent to the page parser.

Note that the URL can also be a file: URL, which the quote fetcher takes to be the path to an executable script. It will pass any command-line arguments to it that you have specified, and feed the stdout of that script to the page parser. For example, you might have a script called getquote.sh that contains custom quote logic, taking the symbol as a single parameter. Your URL would be file:/path/to/getquote.sh %1.

The page parser looks for a symbol, a date, and a price. Regular expressions tell it how to extract those items from the page. Please review the documentation for the QRegularExpression class for the exact syntax regular expressions used by &kmymoney;. There should be exactly one capture expression, surrounded by parentheses, in each regexp field. The date format further tells the date parser the order of year, month, and day. This date format should always be in the form "%x %x %x". where x is y, m, or d. The date parser is very smart. %m %d %y will parse December 31st, 2005 as easily as 12/31/05. Two digit years are interpreted as being in the range of 1950-2049.

## Unimplemented Features

There are some features that are normally associated with investments which are not yet implemented in &kmymoney;. These include, but are not limited to derivatives, options, and futures. In addition, when you sell a security, &kmymoney; does not know which specific shares you are selling, &ie;, the oldest or the most recently purchased, so it cannot calculate return on investment. Finally, it has no direct knowledge about any country's specific tax reporting requirements, although these can usually be handled by marking as Tax related all the categories you use for transactions which might have tax consequences.

The &kmymoney; development team is aware of these and additional issues, and has been collecting requirements and notes for an eventual major re-write of how the program handles investments. When that process begins (there is no current schedule) there will be an opportunity for users to provide input on any additional needs and desires in this area.