# Investments

## Investments in &kmymoney;

### Investments

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, or income such as interest or dividends. 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.

### Base Currency

Each security has a 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 default currency for the Investment account holding that security.

### Investment Accounts

An 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;, and it might be changed in a future version. 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 (from a sell or dividend) cash, 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.

## Creating an Investment Account

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

To work with the new investment account, navigate to the Investments view, and choose the account you have just created from the Select Account dropdown box.

## 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 drop-down box. Investment View, Equities Tab Investment View, Equities Tab

Right-click the mouse in the 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'll be asked to enter is the type of investment, whether it's a stock, bond, &etc;

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

- Trading Symbol. A trading or ticker symbol is an abbreviation used to identify a publicly traded security of a particular instrument on a particular stock market 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.

- Full name. The friendly, readable name of the investment you're creating, ⪚, 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. 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 stock trades. This is an optional field which is provided for your convenience. This information is not used anywhere else within &kmymoney;.

- Identification. An optional field to enter additional identification information you might like to keep track of. Again, this information is not used anywhere else.

- Trading currency. The market exchange currency in which this investment trades. This is typically 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. Choose whether the price will be entered as the price per share or as the total for all shares when entering a transaction.

If you are using Online Quotes, 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.

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

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

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

## Editing an Investment

The Equities tab of the Investments view window lists your current holdings in this account, along with their symbol, value, quantity, and price. Right-click the mouse on any of the investments to bring up the Investment Options context menu, where you have the option to add, edit, or delete individual investments from this account. Also, you can update the price of your investments here either manually or via their online source. In addition, it is possible to close an empty account, or to reopen a closed account. The order for value, quantity and price can be changed on the screen by selecting any of them by left clicking on the item in the top bar and dragging it to the left or right.

## Investment Transactions

Investment Transaction Form Investment Transaction Form

Investment transactions are entered and edited in the Ledger view, as with other kinds of accounts. However, the fields will appear different, and vary depending on the transaction type or activity. Investment transactions have some additional elements:

- Activity

- Security

- Account

- Shares, Price, & Total Amount

- Fees

- Interest category

### Activity

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

Buy/Sell

- Use to record purchases or sales of individual securities. This action requires an account to transfer the funds from/to, which defaults to the Brokerage account, if one has been created.

Dividend/Yield

- Also known as a Cash Dividend, this action is used when you receive an interest or dividend disbursement from your security. This action also requires an account to transfer the funds to.

Reinvest Dividend

- 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 disappear) unless it's a purchase or a sale. 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 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 ration is less than one, such as 2:3, although uncommon, are also allowed.

### Security

Each investment transaction must be associated with an individual security. Choose the security name when adding or editing a transaction. The symbol will be displayed when viewing it.

### 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's 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 account 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 securities, and you may want to combine the two. 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 default currency for the investment account in which you hold the stock or the account where you transfer your funds to/from for buys/sells.

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.

Currency Warning Currency Warning

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

Exchange Rate Editor Exchange Rate Editor

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.

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 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's 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.

#### Assigning a Quote Source

In order to get online price quotes, you first have to enable it for each security or currency you want updated, by setting a 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 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 as 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 option to bring up the online price quotes dialog. Press Update All to fetch quotes for all securities and currencies in your &kmymoney; file.

Update Stock and Currency Prices Online Stock and Currency Price Update

#### 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, we recommend writing to the developer's list if none of the quote sources work for you. Ideally, please point us to a web page where these quotes 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 Settings Configure &kmymoney;. 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 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 QRegExp 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, but these can usually be handled by marking as Tax related all the categories you use for transactions which might have tax consequences.