Rotki Usage Guide

Introduction

In this section we are going to see how to use various parts of the Rotki application.

Sign-in/Signup

When you start Rotki you are greeted with a sign-in/signup prompt.

Creating a new account

If you have never created an account before press “Create New Account”. Provide a username and a password. Don’t forget this password. It will be used to encrypt all your local files. The username is just an identifier for your database. It’s a local user.

Creating a new account with a premium Rotki API key/secret pair

If you have purchased a premium subscription you can also add the API Key and the secret here. This will essentially populate the new account with the data saved in the server for your premium subscription. Important thing to note here is that the password of the new account must be the same as the data saved in the server. If not, opening the database will fail.

If you already have an account just write the name and the password at the sign in prompt.

All accounts are created in the rotki directory which is located in: $HOME/.rotkehlchen. Each user has their own subdirectory.

Rotki Premium

If you decide to purchase Rotki Premium at a later time, you can set it up via API Keys -> Rotki Premium.

Set up Rotki premium API key/secret pair in an existing account

If after you have set up premium you wish to replace or disassociate keys with the currently logged-in account, you can do so via the same page.

Delete up Rotki premium API key/secret pair in a premium account

Customizing

This section contains information about how to customize the application through the settings. By clicking on the user icon on the top right and choosing settings you can customize some basic settings for the application.

Changing the Profit Currency

Rotki calculates everything, including your profit/loss for your tax report into a given fiat currency. This is what we call the profit_currency. By default this is USD. You can easily change this setting by clicking on the currency icon the top right menu and changing it to the currency you are using.

Changing the profit currency

Customizing the application settings

By choosing the “General” settings button you can customize some general application settings.

Customizing the app settings

Floating precision

Set how many decimal points should be shown in the UI for floating point numbers.

Anonymized logs

Specify whether logging functionality should be anonymized. That has a small cost in performance but makes sure that all logs that would otherwise contain sensitive tradeinformation have them anonymized with random values.

Anonymous usage analytics

Specify whether the application is allowed to submit anonymous usage analytics. As a local application Rotki has no other way to measure how many active users it has other than submitting some form of analytics. The data that are submitted are completely anonymized and contain no sensitive information.

Date from when to count historical data

A date before which historical data is not counted.

Main currency

Same as changing the profit currency.

Connecting to an Ethereum Client

When Rotki begins it tries to connect to a local ethereum node running with an rpc port set at the default port 8545. If no client is running then all blockchain queries will use an external service such as etherscan and this will be rather slower.

If you want to connect to another ethereum client you can set the URL and port through the settings. Click the person icon on the top right menu and select “Settings” from the drop down menu. This will take you to the settings page. Write the desired url/port in the ETH RPC endpoing textbox.

Balance data saving frequency

Set how often (in hours) the data of all balances will be saved. This data is used to calculate statistics and other historical data to show to the user.

Date display format

Set the display format of the dates in the Rotki user interface.

Customizing the accounting settings

By choosing the “Accounting” settings button you can customize some application settings that pertain to accounting calculations.

You should understand what each setting does, consult with a tax accountant for your jurisdiction and then set them appropriately.

The default settings are at the moment set for the German tax jurisdiction. For example all profit/loss calculation is done for trades on a first-in/first-out basis and profits from selling crypto assets after 1 year are non taxable. These settings can be adjusted.

Customizing the accounting settings

Crypto to crypto trades

Specify whether crypto to crypto trades are taxable and should be taken into account. If yes then each crypto to crypto trade also creates a “virtual” trade that sells or buys the crypto asset for fiat and then sells or buys the fiat for the other crypto asset.

Ethereum gas costs

Specify whether ethereum transaction gas costs should be counted as loss. If this is set then all ETH spent on gas will be deducted from your profits and count as an expense.

Tax free period

Specify whether there is a period of time and if yes how many days, after which holding a crypto asset is considered not taxable.

Ignored assets

Specify which assets you own and would like to completely ignore from all calculations. Any actions that involve these assets are ignored.

Customizing user & security settings

By choosing the “user & security” section of the settings you can change the user password.

Changing the user's password

Importing data

In this section we will explain how you can import data by integrating with external services such as crypto exchanges

Adding an exchange

Add API keys for a new exchange

You can integrate many different exchanges with Rotki. Currently supported exchanges are: Kraken, Poloniex, Bittrex, Bitmex, Binance, Coinbase, Coinbase Pro and Gemini.

To do so you have to go to your exchange and create an API key (see the section API key permissions).

Click on the “API keys” on the left sidebar. This will take you to the place where you can add new exchange API keys. Select the exchanges panel and select your exchange from the dropdown menu. Then copy and paste the API Key and the API Secret in the respective text fields and press submit.

If all went well, then you will get a confirmation that the connection was successful. If not please doublecheck that the key and secret are correct.

API key permissions

Rotki only needs read-only permissions for your accounts. As a general rule, exchanges (e.g. Binance, Coinbase Pro) group all the read-only permissions as “read” or “view”.

Simple API key permissions

In case of an exchange providing a more granular permissions scheme (e.g. Coinbase, Kraken) or having additional options (e.g query limits, passphrase), refer to the exchange documentation or get in touch via their customer support channel.

Granular API key permissions

You may as well try creating an API key with the minimum read-related permissions, then adding it in Rotki and finally checking that the connection was successful and data was loaded as expected. Otherwise, try again adding more read-related premissions.

Adding an external service API Key

Rotki relies on various external services for data such as historical crypto prices or ethereum transactions. To get that data some of these services require API keys. So you should go to their webpage, create a free account and generate an API key. Once this is done you can enter the API key in the section of the API keys page.

Add API keys for an external service

At the moment there is no compulsory API key. But if you don’t use your own node etherscan queries without an API key are really slow. So if you don’t already have an account with them please create one here and then generate a free API key and set it in the app as explained above. It’s free of charge.

Cointracking.info

You can also import data from cointracking.info into Rotki by clicking on “Import Data” on the left sidebard and then following the instructions.

Rotki can import any trade CSV data exported from cointracking.info. But in general it’s not recommended to utilize cointracking as their exported data are missing a lot of information.

Importing data from cointracking.info

Tracking accounts and balances

To manage Accounts & Balances (Blockchain Balances, Exchange Balances, and Manual Balances including fiat) you need to visit the “Accounts & Balances” section from the left sidebar.

Accounts & Balances page

Adding Manual Balances

With Rotki you can also add balances/accounts for any type of asset and location that may not be supported at the moment. For example real estate, equity holdings or holdings in a not yet supported blockchain or exchange.

To add or modify a manually tracked balance navigate to the “Manual Balances” sub-page and click the large “+” icon. There choose the asset from the dropdown menu, input a unique label for the account, decorate it with any number of tags and choose an amount and location.

The manually tracked balances

Adding and Removing Blockchain Accounts

Rotki allows to track balances of blockchain accounts.

To add or modify an account navigate to the “Blockchain Balances” sub-page and click the large “+” icon. Now choose the blockchain on which you want to add an account (for now only Bitcoin and Ethereum chains are supported). Then type or paste the address in the “Account” textbox and press the “Save” Button.

Add a blockchain account

To stop tracking a particular account scroll down to the accounts tables and click the “Delete” icon (trashcan) under Actions.

If an ethereum account also contains tracked tokens you can click on the arrow under “Actions” in order to expand its view and show the balance breakdown for the account over all assets it holds.

Adding and Removing Ethereum Tokens

Rotki will autodetect what tokens you have in your ethereum accounts thanks to Alethio. If the query to alethio fails for some reason then you can provide a list of tokens to be tracked and whose balances to query your ethereum node or etherscan for. This list can be provided and modified by you.

To do so scroll down to the “Blockchain Balances” section and look for the “Owned Tokens” fields.

Add a new owned ethereum token

In order to add a token to the tracked tokens start typing its name and the auto-completion of the widget should show it to you. If it does not it may mean that it’s not supported by Rotki. Try to make an issue in our github repository to add it.

In order to stop tracking a token simply click the [X] next to the token’s name from the list of owned tokens.

All account balances will be updated after addition or removal of tokens.

Checking Exchange Balances

You can check all of the asset balances that you have in each connected exchange in the “Exchange Balances” sub-page. Clicking the large “+” icon takes you to the API Keys page where you can manage your exchange connections ( see Adding an exchange).

Exchange Balance

Adding/Editing Labels and tags

You can edit any of your blockchain accounts and add a label. The label is unique to the account and will show up in the accounts tables instead of the address. You will still be able to see the address if you hover over the label in the tables.

Add a label and create a tag

By pressing the edit button for the account you can also add tags to the blockchain account. If you want to create a new tag or edit an existing one you can open the tag manager and choose the name, description and colors of the tag.

Filtering by tags

You can filter the tables by a combination of tags.

Filter the accounts by tag

Simply add the tags you wish to filter by in the filter textbox above the tables.

Manually adding trades or other events

Rotki will pull all your trade history from the exchanges whenever it needs it. But most of us have probably also done some OTC trades or taxable events at some point. Such events could even just be mining tokens, depending on your jurisdiction, participating in an ICO or getting paid in crypto.

On the left sidebar click on the trades button and select “OTC Trades” from the dropdown menu. This will take you to the OTC Trades page.

Add an external trade

To add a new trade or taxable event, fill in all the fields and press the “Add Trade” button.

Some very important things to note. All pairs should be in the form of BASECURRENCY_QUOTECURRENCY. For a buy this means you are buying amount of the BASE currency at a price of rate QUOTE currency per BASE. For a sell this means you are selling amount of the BASE currency at a price of rate QUOTE currency per BASE.

If there was a fee for the trade you should input it in the corresponding box and also enter the currency the fee was paid in. Fee can also be 0.

You can optionally provide additional notes or even links to blockchain explorers for each trade.

At the bottom of this page you can see a table of all your OTC trades. You can edit or delete a trade by clicking on the appropriate icon at the rightmost part of each trade under the “Actions” column.

Decentralized Finance

To track and analyze your DeFi actions use the Decentralized Finance tab from the left side menu. You can choose from the different types of DeFi actions presented in the submenu.

Lending

In the lending section you can see the status of your DAI in the DAI Savings Rate (DSR). The accounts that use DSR are auto-detected from your given blockchain accounts. You can see how much DAI you have locked over all of your accounts and how much DAI is locked for each account in the DSR.

DSR without premium

You can also filter by account and see how much DAI is locked in the DSR for each account.

If you have a premium subscription you can also see how much DAI you have gained in total or over each account, the history of deposits/withdrawals and how much DAI was earned at the point in time for each action.

DSR with premium

Finally you need to have premium in order for the total amount of DAI earned in a given time period to be counted in the profit/loss statements of the tax report.

Below you can see a small demonstration of the usage of DSR by a premium account.

DSR premium demo

Borrowing

In the borrowing section you can find information on your makerdao vaults. The vaults are autodetected from your ethereum accounts and information about each one of them is displayed.

As a normal non-premium user you can see all your vaults, and for each one inspect the locked collateral, collateralization, debt generated and the liquidation price.

Makerdao vaults without a premium account

With a premium subscription you can also see additional information such as the creation time of the vault, list of historical activities, total interest owed and liquidation events.

Makerdao vaults with a premium account

Premium users can also have makervault interest taken into account in the profit/loss report.

Finally premium users can create watchers for their vaults.

Makerdao vaults with a premium account

They can add a target collateralization ratio they would like rotki to watch for in a vault. If the collateralization ratio becomes less/greater than that ratio then an alert is sent to your email. This watcher service runs on the rotki server so you don’t even need to leave the application open.

Below you can see a small demonstration of the usage of makerdao vaults by a premium account.

Makerdao vaults premium demo

Creating a tax report

Rotki creates a tax report for you based on your trades and the provided accounting settings. This is essentially a calculation of profit or loss for all your trades based on the given dates. Before getting into the details of generating a tax report, here’s a few important details regarding the tax report generation algorithm:

  • By default, rotki uses an accounting strategy called “First In - First Out” (short: FIFO). There are plans to implement other strategies (e.g. “Last In - First Out” (short: LIFO)).

  • Rotki allows users in jurisdictions offering a tax free holding period (e.g. Germany with 1 year) to specify the period in days. To adjust this value, see the section Customizing the account settings.

  • When generating a report for a custom period, where rotki is aware of the user’s previous crypto holdings (e.g. we trade BTC between the years 2017 - 2019 but we ask for a report between 2018 - 2019), it takes all prior crypto holdings into account to calculate a starting balance for the given period. For example, say you traded BTC between 2017 - 2019 with a balance of 0.1 BTC on December 31, 2017. When generating a tax report for 2018 - 2019, rotki will take the 0.1 BTC from December 31, 2017 as a start balance for its calculations in the period of 2018.

To create a tax report click on the “Tax Report” button from the left menu. Choose a start and an end date for the report and then click the “Generate Report” button.

Overview of the tax report

The calculation may take some time. Once done you have an overview of the profit/loss for the given period, how much of that is taxable, and how much each taxable event category contributes to the total.

Additionally below the overview you get a table containing all of the taxable events that were taken into account in the calculation along with how much of the profit_currency you lost or gained through that event.

Event list of the tax report

Finally you can get a CSV export by pressing the “Export CSV” button. This export is meant to be imported into Google Sheets. Press the button and then choose a directory to write the CSV files to. Once done you can import the CSV files into Google Sheets via its import menu. Following are definitions for the document’s columns

  • type is a string describing the type of event a user engaged in, e.g. in “I buy ETH for EUR”, buy is the type.

  • paid_asset is a string identifying the asset an event was paid in, e.g. in “I bought 1 ETH for 100 EUR”, EUR is the paid_asset.

  • paid_in_asset is a float specifying the amount of paid_asset`s involved in an event, e.g. in “I bought 1 ETH for 100 EUR”, `100 is the paid_in_asset.

  • taxable_amount: is a float specifying the amount of paid_asset needed to be taken into consideration when generating a tax report, e.g. “I sold 1 ETH for 120 EUR”, 1 ETH is the taxable_amount.

  • received_asset is a string identifying the asset of an event’s yield, e.g. in “I bought 1 ETH for 100 EUR”, ETH is the received_asset.

  • received_in_asset is a float specifying the amount of received_asset`s involved in an event, e.g. in “I bought 1 ETH for 100 EUR”, `1 is the received_in_asset.

  • net_profit_or_loss is a float specifying the amount of profit or loss an event accounts for given the selected accounting strategy (currently there’s only FIFO). Note that its value is based on a spreadsheet formula.

  • time is a string containing the date and time an event was executed.

  • is_virtual is a boolean describing if an event’s paid_asset and received_asset are both crypto assets. As in many jurisdictions, crypto to crypto trades are taxable, the is_virtual column allows us to calculate the event’s taxable amount given the crypto coin’s rate against rotki’s default currency, also known as profit_currency (e.g. EUR).

  • paid_in_XXX, where XXX is the user’s customized profit_currency is a float describing the amount of paid_in_asset converted to the user`s profit_currency.

  • taxable_received_in_XXX where XXX is the user’s customized profit_currency is a float describing the amount of received_in_asset`converted to the user’s `profit_currency. Note that rotki additionally subtracts an exchange’s trading fees from this number.

  • taxable_bought_cost_in_EUR, where XXX is the user’s customized profit_currency is a float simulating the total amount of paid_in_asset given the user’s customized accounting strategy in the user’s profit_currency.

Note

To learn more about profit_currency or to adjust it, see the section Changing the Profit Currency <#changing-the-profit-currency>`.

Analytics

If you have a premium subscription you can get analytics on your all your assets and trades.

Click on the analytics page on the left sidebar to go to your analytics page.

Since Rotki is tracking all your assets over time the first thing you can see is a value/time graph of your entire net value.

Netvalue over time graph

Following that you can see a graph of quantity of an asset superimposed on its USD value over time.

Asset amount and value over time

Furthermore you can see a piechart of the distribution of your netvalue across different locations. So you can determine how exposed you are to having a big part of your net value in exchanges, in banks e.t.c.

Distribution of networth by location

Finally you can see a piechart of the distribution of your netvalue across all of the assets you own. This is an important analytics tool as it can help you determine your exposure on each asset and if some rebalancing of your portfolio is in order.

Distribution of networth by asset

Set the backend’s arguments

Rotki runs a python daemon on the backend. Most times you won’t need to customize its arguments but if you need to do so, especially for debugging purposes this is how you can.

Create or edit if it exists a file with the name rotki_config.json in the same directory as the rotki executable. Add to the json object any arguments that are also arguments of rotki. Then when rotki starts these will be passed as arguments to the backend. An example rotki_config.json follows:

{
    "loglevel": "debug",
    "logfromothermodules": false,
    "logile": "filenameforthelogs",
    "data-dir": "/path/to/dir"
    "sleep-secs": 20
}

The above arguments are:

  • loglevel: Set the loglevel for the application. Valid values are: 'debug', 'info', 'warn', 'error', 'critical'.

  • logfromothermodules: If this argument appears then logging will also include log entries from other dependent libraries and not only rotki. Default is false.

  • logfile: The name for the logfile. Default is: rotkehlchen.log.

  • data-dir: The path to the directory where all rotki data will be saved. Default depends on the user’s OS. Check next section

  • sleep-secs: This is the amount of seconds that the main loop of rotki sleeps for. Default is 20.

Rotki data directory

Rotki saves user data by default in a different directory per OS. For each OS data is stored in the respective standards compliants equivalent directory.

  • Linux: ~/.local/share/rotki/data/

  • OSX: ~/Library/Application Support/rotki/data

  • Windows: %LOCALAPPDATA%/rotki/data

Before v1.6.0 Rotki was saving data in $USER/.rotkehlchen. From v1.6.0 that directory got migrated to the OS equivalent standard directory and it should be safe for the users to delete the old directory as long as the new directory contains the migrated DB.

A very good idea about the rotki data directory would be to be making frequent backups of it as it contains all of the data of all of your rotki accounts and cache data for historical price queries.

Troubleshooting

Local system clock is not synchronized

Some remote servers (e.g. exchanges) require your local system clock synchronized with theirs. In case of not having it synchronized the request will fail and Rotki will either display a specific error message (i.e. 409 status code and a local system clock is not sync message) or the generic 500 error one (please, report it to us).

Follow your OS official guidelines about how to synchronize the clock with an Internet Time Server and try again.