rotki Usage Guide

Introduction

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

First time sign-up

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

Creating a new account

For creating an account press “Create New Account” and provide a username and a password:

  • Username: it is just an identifier for your database; a local user.

  • Password: Do not forget this password. It is used to encrypt all your local files.

If you want to restore an account using premium sync during the account creation, then you can Enable premium, and insert your API Key and the secret here.

For a completely new account it is suggested to add your premium API key and secret using Set up rotki Premium after logging in with the new account.

Creating a new account

All accounts are created in the rotki directory, see the section rotki data directory to know where it is located.

Create a new account that restores a backed up database (premium user only)

If you have a premium subscription and you want to create a new local account that restores the backed up database, for example in a different device, you must add the API key/secret and use the same password. If the password is not the same, opening the database will fail.

Sign-up with existing premium subscription using a wrong password

See the section Sync data with rotki Server to know more about how the premium subscription will behave with multiple accounts/devices and how to sync your data with Roki Server (this option is disabled by default).

Sign-in

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

Set up 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

Sync data with rotki Server

To back up your data in the rotki Server switch on “Allow data sync with rotki Server”. This allows you to restore it later on in any account/device as long as the same API Key/secret and account password are used.

Sync data with rotki Server

Bear in mind that in case of using multiple accounts/devices with the data sync enabled, the one with the most recent login will upload the most up-to-date data to rotki Server. After that, using the same account from another device may ask you whether you want to replace your local database with the remote one.

Replace local database with remote backup

You can manually move the global DB that contains the assets from one system to the other too. Find the rotki data directory in the source system. Assuming it’s linux it will be ~/.local/share/rotki/data. The global db is then ~/.local/share/rotki/data/global_data/global.db. Manually move it to the equivalent location in the new system.

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 total profit/loss during the PnL 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 general app settings

General Settings

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.

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. One such format is %m/%d/%Y %H:%M:%S. That means month/day/year hour:minutes:seconds. For possible valid formats check here.

Display in local time

Choose whether local time or UTC should be shown in the CSV exports, user logs in the backend and other locations.

BTC Derivation gap limit

This is the derivation gap limit that will be used when trying to derive addresses from a bitcoin xpub. For more information check here.

Amount Settings

Customizing the app's amount settings
Floating precision

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

Main currency

Same as changing the profit currency.

Thousands separator

This is the symbol that will be separating the numbers every 3 digits for big numbers. For example in 1,000,000, the symbol is ,.

Decimal separator

This is the symbol that will be separating the floating part of the number. For example in 5.42 the symbol is ..

Currency location

This setting chooses if the currency symbol will be shown before ($1,000) or after(1,000$) the number.

Amount Rounding

This setting modifies the rounding mechanism choosing from Round up, Round down and Half even (rounds to the nearest value). It can be individually modified how amounts and values are rounded.

Local nodes

Customizing the app's connection to local nodes
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.

Connecting to a Kusama Client

Just like with ethereum you can set the rpc endpoint of a kusama node you would like to connect to here.

Price Oracle settings

Customizing the app's price oracle settings

Here you can customize the precedence of querying that price oracles will have. That means which price source to check first, which second and so on and so forth both for current but also for historical prices.

Frontend only settings

Customizing the app's frontend only settings
Data scrambling

When turned on this setting allows you to randomize a lot of amount numbers, dates and other data in the app so that you can share screenshots without leaking real data. This setting does not persist across sessions!

Dashboard graph default timeframe

Set the default time frame for the dashboard graph. This timeframe will be pre-selected upon login. By default it will remember the previous session’s selection.

Graph basis

Configure whether the graph y-axis will start at 0 or the minimum amount for the period.

Automatic balance refresh

This enables/disables automatic refresh of balances. Also sets the distance in time between each refresh. Automatic balance refresh is disabled by default because balance querying can get really slow and also get you rate limited.

Periodic status query

The rotki frontend continuously queries the backend for various data and updates. This is an inexpensive operation that is set by default to 5 seconds. You can customize the frequency of that query here.

Customizing the app's frontend only settings
Blockchain explorer customization

You can customize in which explorer the transaction and addresses links open.

Theme [Premium]

Premium users can customize the color them for either light or dark mode.

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.

Trade settings

Customizing the accounting trade 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.

Asset movements fees

Specify whether deposit/withdrawal fees should count as expenses during the profit/loss report.

Calculate past cost basis

When creating a profit/loss report we also need to figure out where and when all of the assets that the user is using were acquired from. Which is why we also go through all past events, even before the start of the period.

This behavior can be disabled by turning this setting off.

Asset settings

Customizing the accounting asset settings
Ignored assets

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

Ledger action settings

Customizing the accounting ledger action settings

Here you can choose which types of historical actions should be considered taxable and which not. For example in Germany airdrops are considered windfall profits and are not taxed, so you can specify that here.

CSV Export settings

Customizing the CSV export settings
Export formulas

Specify whether formulas should be exported as formulas in the CSV export or if the actual value should be simply exported.

Have summary

Specify whether at the end of the all_events CSV export there should be a summary of all events and the total profit/loss or not. Additionally at this summary there would be the rotki version and the settings used during the PnL report so it’s easy to reproduce a report run.

Customizing data & security settings

Changing password

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

Changing the user's password

Database Info & User Database Backups

By visiting the database info section you can see information about your user and global database, such as the user database directory, size and version.

Creating database backups

You can create new database backups by pressing the Create new backup button. To delete a backup you can press the trash can icon on the database row.

The download button provides an easy way to save the backups locally, and it can be especially helpful if you run the docker instance on a remote machine.

Purging data

rotki keeps a lot of data cached locally in the user’s DB. There may be the need to clean some of these data from time to time. You can do so from the “Manage Data” section of the settings, by clicking on the dropdown list, selecting the type of data you want to delete and then pressing the Trash button.

Purging user data

Manage historical price oracle cache

Querying historical prices from oracles such as cryptocompare and coingecko is slow and can get slower as a result of rate limiting. That is why rotki creates historical price caches during idle time of the application.

You can request the creation of such a cache by going to the Oracle cache section, selecting the oracle, the from asset of the pair, the to asset of the pair and then pressing the Cache pair prices.

Creating a historical price cache

Users can also manage the existing historical price cache entries. They can inspect when does the historical price data start, when does it end and if they want they can delete the cache by pressing the trash button.

Managing the historical price cache

Customizing the Module settings

By choosing the “Module” section of the settings you can customize the enabled modules and the queried addresses for each module for the application.

The benefit of enabling only the modules you use, and specifying the addresses, is that rotki will only query the specified addresses for the enabled modules. This can considerably improve the querying speed.

Managing module settings

Activating/Deactivating Modules

You can activate a module by selecting it from the dropdown menu that appears when you search in the “Select modules” input field. An active module will be visible in the input. In the screenshot above for example the Compound and MakerDAO DSR modules are active.

To disable a module you need to press the (x) button at the end of the entry.

After enabling or disabling a module you need to re-login again for the changes to take effect.

Selecting Addresses

In order to limit the querying only to selected addresses instead of all the eligible ones you can go to the “Select Accounts” and click on the module you are interested in (3). The module address selection (4) for this module should be visible.

Search for each address you are interested and then select each one from the dropdown menu. The selected addresses should be visible in the same way as the modules above. To remove an address you need to press the (x) button at the end of the entry.

If no addresses are selected for a module this means that rotki will check all the eligible addresses which can add to the total query duration and considerably slow down retrieving data from the app.

Changing the backend settings

Users of the desktop app can change the default data directory, and log directory. This can be done via the login screen. You can click the cog wheel at the bottom right corner to view the backend settings dialog.

Change the backend settings

After selecting a new data directory, log directory etc you can press the save button to save your settings.

Keep in mind that any accounts that were created in the previous directory will not be accessible anymore and you will have to manually move them to the new location.

In the advanced section of the backend settings you can also modify the following settings:

  • Logging from other modules: If enabled then logging will also include log entries from other dependent libraries and not only rotki. It is disabled by default.

  • Main Loop sleep: This is the amount of seconds that the main loop of rotki sleeps for. It is set to 20 seconds by default.

  • Max log size: This is the maximum size in megabytes all logs of a single run can have.

  • Max num of log files: This is the maximum number of backup (rotated) logs a single run can have.

Disabling the tray icon

Users can disable the application tray icon by clicking the View menu entry in the application menu bar. There you can select Display Tray Icon to enable or disable the application tray icon.

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

Adding exchanges

You can integrate many different exchanges with rotki. Currently supported exchanges are: Kraken, Poloniex, Bittrex, Bitmex, Bitfinex, Binance, Binance US, bitcoin.de, Coinbase, Coinbase Pro, Gemini, Iconomi, Bitstamp, KuCoin, FTX.

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. Press the plus button to open the exchange addition menu.

Add API keys for a new exchange

Then copy and paste the API Key and the API Secret in the respective text fields and press Save.

If all went well, you should be able to see your newly added exchange. If not please doublecheck that the key and secret are correct.

Add API keys for a new exchange

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.

Binance / Binance US

Binance API is engineered in a way that makes it really slow to query information for trades since every possible market pair has to be queried. This process can also fail since many requests have to be made to binance servers and rate limits may apply. To avoid having to query all existing trade pairs, it is possible to select what markets should be queried. This will considerably increase the speed as the amount of queries to binance will be reduced to only the markets you specify. To select which what markets you want to query edit your binance exchange instance

Edit binance in the exchanges section

And choose the markets in the Filter market pair(s) search.

Edit binance in the exchanges section

Once finished click on save.

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

ShapeShift.com

You can import trade CSV data exported from shapeshift.com. Transactions will come from adding your Blockchain Accounts used with ShapeShift to rotki.

Import data in the same section as the image above in the prior heading. When exporting trades from ShapeShift, the selected wallet may show DEX trades in the user interface. If it is not the Native wallet, DEX trades may not show up in the user interface, but they still export to CSV. This importer ignores DEX trades, as they are covered by premium support for Uniswap and SushiSwap.

uphold.com

You can import transaction history CSV data exported from the uphold.com activity page. Transactions will be created when the row’s origin currency and destination currency are the same. Trades will be created if the currencies differ and a rate will be determined automatically.

Loopring balances

To have your loopring balances detected you will need an API Key from loopring. To get one visit https://exchange.loopring.io/ and unlock your account. In the right panel you need to click in Export Account

Get loopring keys

Then in rotki you need to add the API key. Go to API Keys > External Services > Loopring and paste the key that you obtained in the loopring website.

Add loopring key

After following this steps your balances in the dashboard will be updated including the loopring information

Loopring balances in the UI

The loopring account balances are also visible in the blockchain accounts view.

Loopring balances for an account

Moving data to another system

If you want to move your data to another system then you will need to do some manual steps. First identify the rotki data directory in both the source and the destination system. Then move the entire data directory from the source system to the destination system and make sure that the same rotki version is used in both syste

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, Ethereum, Kusama, Polkadot and Avalanche chains are supported). Then type or paste the address in the “Account” textbox and press the “Save” Button. When scrolling through the page the “+” will automatically switch the pre-selected chain based on the context. For example if the table displaying the screen center is the BTC table then BTC will be pre-selected when pressing “+”.

Add a blockchain account

To stop tracking one or more accounts you can check the corresponding box in the accounts table and click the “Delete” button.

Delete a blockchain account

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.

For Bitcoin you can add addresses manually or let rotki discover them using an xpub. From this key rotki can generate your addresses and query the Bitcoin blockchain for each one of them until it finds unused addresses. There are also different types of xpubs. P2PKH xpubs generate addresses that have “1” as a prefix, P2SH_P2WPKH xpubs generate addresses that start with a “3” and WPKH xpubs generate addresses that start with “bc1”. You will need to know what type of xpub your bitcoin wallet generates in order to choose the correct type at the dropdown menu. If your wallet generates an xpub prefixed with ypub or an xpub prefix with zpub rotki can deduce the type for you automatically. An xpub does not allow spending your coins but provides information about your wallet. In rotki this information is stored safely encrypted in your local database.

Add a bitcoin account using XPUB

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.

NFTs

Rotki provides an NFT gallery where you can view the NFTs owned by your accounts.

NFT Gallery

You have an overview of the total value of your NFTs in the application dashboard, on the NFTs table.

NFT Value Dashboard

An estimation of the value of the NFTs you own is counted into your total net worth. The estimation strategy is currently the maximum of either the floor price of the collection or the last sale of the NFT. If a manual price has been given this is always preferred.

NFT Value Dashboard

If a price cannot be found for an NFT asset or if you want to change the calculated price estimate you can easily set the price for an NFT asset manually. You can do this by either clicking on the > in the NFTs table in the dashboard or by going to Blockchains & Accounts -> Non-fungible balances. And then click on the pen icon for the NFT you are interested in.

ETH2 Staking

If you are an ETH2 staker you can see the total value earned both in the current ETH price (2) but also counting the price of the daily payouts of ETH2 staking (3).

See ETH2 value earned

Moreover you can see a breakout of daily stats of validating. How much ETH was earned per day, attestation stats, block proposing stats and more.

See ETH2 value earned

Finally this can also be taken into account in the profit/loss report for any given period of time and also exported via CSV to a spreadsheet.

See ETH2 value earned

Liquity Staking

If you stake LQTY in the protocol you can see the amount staked and the changes in the staked amount.

See ETH2 value earned

Airdrops

rotki can detect some airdrops for you

rotki airdrops detection

The list of currently supported airdrops is:

  • Uniswap

  • 1INCH

  • Tornado

  • Cornichon

  • Grain

  • Furocombo

  • Lido

  • Curve

  • ENS

  • ParaSwap

Snapshots

The application will on login snapshot to disk the information about balances from all the tracked sources every 24 hours (by default. The number of hours is configurable). This information is saved directly to your local database. You can force a snapshot taking by clicking in the floppy disk icon at the top bar and then on Force Save

Force snapshots saves

Snapshots won’t be saved if there is any error querying information for external sources. If you want to force the snapshot to be saved when an external source is reporting an error you can select the option Ignore Errors.

Historical events

Adding manual trades

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 History and then the Trade button from the dropdown menu. This will take you to the Trades page. Clicking on the + symbol will open a menu like the following.

Add an external trade

To add a new trade, fill in all the fields and press the “Save” button.

In the amount field you can register the amount of the base asset bought or sold. The rate field represents the rate of quote asset per base asset that was bought or sold. 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. This field is optional so if the Fee was 0 you can leave this field empty. You can optionally provide additional notes or even links to blockchain explorers for each trade.

In the Trades page you can see a table of all your external 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.

Currently rotki tracks your balance by querying the different supported protocols, exchanges and blockchains. If you manually add information about a trade your balances will not be updated since trades are not consulted when updating the accounts’ balances. If you want to manually update your balance for an asset please refer to the manual balances section.

Adding ledger actions

With ledger actions you can add events that represent incomes, losses, expenses, etc. On the left sidebar click on History and then the Ledger Actions button from the dropdown menu. You can provide a location, for example an exchange, a bank, a blockchain or others. For the action type you can select from:

  • Income

  • Loss

  • Donation Received

  • Expense

  • Dividends Income

  • Airdrop

  • Gift

  • Grant

Add a ledger action

For ledger actions you can optionally specify a rate and a asset for the rate. This is the rate linked to the asset for this action. If no rate is provided, the historical price at the date of the action is used.

When generating a profit and loss report some ledger actions might be taxable in your jurisdiction and some not. To customize the list of taxable actions refer to the ledger actions settings section.

Filtering trades

Rotki supports filter your trades with a combination of filters. All of the filters are applied at the same time limiting the trades to the ones that satisfy all the applied filters.

Filtering trades

You can filter using the following keys:

  • base: the base asset of the trades 1.

  • quote: the quote asset of the trades 1.

  • action: it can be buy or sell 2.

  • start: will only filter any trades from that date an onwards 2.

  • end: will only filter any trades that happened before the selected date 2.

  • location: the location of tha trade, e.g. kraken, uniswap etc 1.

Trade filter suggestions

When selecting a filter, by clicking or typing the filter you will get some suggestions based on the available data.

Note

At the moment it is not possible to navigate select the available filters using the keyboard arrows or tab. This is a feature that will become available in the future.

When a suggestion appears you can navigate to the next available suggestion using the tab button or you can also change the select suggestion using the up/down arrows in your keyboard. You can submit the selected filter by pressing enter.

Multiple trade filters applied

After adding your filters you can press enter to close the menu.

Filtering deposits & withdrawals

You can filter your deposits and withdrawals int he same say you can filter your trades.

Deposit filters

For deposits you can use the following filters:

  • asset: the asset that was deposited or withdrawn 1.

  • action: the actions (withdrawal or deposit) 1.

  • start: will only filter any trades from that date an onwards 2.

  • end: will only filter any trades that happened before the selected date 2.

  • location: the location of tha trade, e.g. kraken, uniswap etc 1.

1(1,2,3,4,5,6)

Suggestions will appear for this field based on the available data.

2(1,2,3,4,5)

The date filter has to be in the DD/MM/YYYY HH:mm:ss format. You can completely skip the time part or just the seconds part, thus making DD/MM/YYYY or DD/MM/YYYY HH:mm acceptable.

Customization of the list of supported assets

Inspecting list of assets

You can now manage the list of supported assets by your local rotki instance. At the moment only ethereum tokens are modifiable but from next releases you will be able to add all kind of assets.

You can inspect the list of all supported assets, edit them, delete them or add new ones.

Manage the list of assets

Adding/editing an asset

Add or edit a custom token

When you press the + button on the top right, or edit an existing token you can see the Asset form.

You can fill in the following fields:

  1. The token address. This is required.

  2. The token name. This is required.

  3. The token symbol. This is required.

  4. The token decimals. This is required.

  5. Coingecko identifier. This is optional, but highly recommended. If the asset is supported by coingecko you should get its coingecko identifier. This will allow the usage of coingecko as a price oracle and also will automatically pull the asset icon from coingecko. You can get the coingecko identifier for an asset by searching this list: https://api.coingecko.com/api/v3/coins/list . It may also be the same as the last part of the coingecko url. For example from https://www.coingecko.com/en/coins/ethereum we have ethereum as the identifier for ETH.

  6. Cryptocompare identifier. This is optional but recommended. At least one of coingecko or cryptocompare should be given so that prices can be queried. If not given, the symbol of the asset will be used. If that fails, then cryptocompare is not used. To get the cryptocompare identifier, search for the coin in cryptocompare, visit its url and take it from there. For example for https://www.cryptocompare.com/coins/eth/overview/USD the identifier is ETH. It’s always what comes after coins.

  7. You can upload an icon for the asset. Any of the common image extensions is accepted (png, jpg, jpeg, webp). The custom icon always takes precedence over the one auto-detected by coingecko.

When you input the address of the token rotki will try to fetch its name, symbol and decimals and use them if they are available.

There is also some other fields that are completely optional and expand if you press the (7) Optional Fields section.

Optional information when adding a custom token
  1. You can specify a timestamp at which the asset started to exist. This should be the token deployment timestamp for tokens.

  2. If the asset is part of a protocol, specify it here. For example ‘uniswap’ for uniswap pool tokens, ‘aave’ for aTokens etc.

  3. If the token is swapped for another token, specify it here. For example LEND was swapped for AAVE.

  4. A token can have underlying tokens. Like a pool, or a token set. Here add the underlying token’s address.

  5. And here add the underlying token’s weight.

  6. Here you can edit or delete underlying token address/weights. Note: The weight of the underlying tokens should add up to 100%.

Merging two assets

There are two possible situations where you might need to merge two assets into one.

1. You added a custom asset that was later officially supported on rotki. In this case you should merge your custom asset to the the officially supported one. If you don’t do this might split balances between entries, especially for supported exchanges that will use the officially supported entry.

  1. There was an issue and an Unknown asset notification is now visible. This can happen if you somehow end up deleting your global DB of assets. This way all your custom assets will be unknown. In this case you would need to re-add the deleted assets, and merge the old asset id that errors to the new one that you created.

Optional information when adding a custom token

To merge two assets you can use the merge dialog by pressing the Merge Asset button in the Asset Management screen. In the dialog you can put the identifier of your custom or missing asset in the source field. For a custom asset, you can get the identifier using the copy button in the asset table. If you have a missing asset then you can copy it from the notification message

Then you can go to the target field and search for the asset into which the source will be merge to. When both the source identifier and target asset are selected you can press the merge button.

On a successful merge you will be notified to to either re-login or refresh the balances manually to see the changes on the frontend.

Adding missing prices

Some times rotki might be unable to retrieve a historical price for an asset from CoinGecko or CryptoCompare. In this case you can use the price management interface to insert your own price entries.

Price management

To add a new price you have to press the plus button. This will open the add form.

Adding a new price

There you can specify the assets, the price and the date of the price. Then you can proceed to save the entry. After saving you should be able to see the new entry.

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.

Overview

Rotki provides an overview of your assets in the different Defi protocols.

Defi Overview

Deposits

In the deposits section you can see the status of your different Defi lending protocols. You can see the status of your Yearn Vaults, Aave lending, Compound supply along with your DAI in MakerDAO DSR.

The accounts are auto-detected from your given blockchain accounts. However you can, and most probably should, manage the different modules and addresses that are queried to make the retrieval faster. For more information you can check Customizing the Module settings.

You can see how much of each asset you have locked over all of your accounts and how much of each is locked for each account across the different protocols.

DSR without premium

You can also filter by account and protocol and you can see how the assets are locked in the various protocols.

Defi Deposits with premium

You can see details about the assets locked in your Yearn vaults and check the profit/loss per asset.

Defi Deposits Yearn Vaults

You can also get a detailed list of historical actions performed in the supported Defi protocols such as deposits withdrawals etc.

Defi Deposits history

Finally you need to have a premium subscription in order for the total amount of earned or lost value per asset in a given time period to be counted in the profit/loss report.

Liquidity Pools

Defi Liquidity Pools

Rotki allows it’s users to keep track of their Uniswap v2 and Balancer and Sushiswap liquidity pools With the exception of Uniswap v2 lp balances this feature is only available to premium users.

Defi Sushiswap

The liquidity pool support allows premium users to see their balances, the per pool profit/loss and any events (such as mint/burn) performed.

Liabilities

In the liabilities section you can find information on your Aave Borrowing, Compound Borrow, Liquity troves and MakerDAO Vaults. These collateralized loans can be autodetected from your ethereum accounts and information about each one of them is displayed. However you can manage the different modules and addresses that are queried to make the retrieval faster. For more information you can check Customizing the Module settings.

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

MakerDAO vaults without a premium account

The information displayed for a Liquity trove shows as in this capture

Liquity troves information

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

in the case of troves with a premium subscription you can see the history of events and the changes in collateral and debt

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 vault watchers

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

DEX trades

DEX trades

In the DEX Trades section you can monitor all trades made in the supported decentralized exchanges. Each trade is also broken down to the separate swaps that it is comprised of.

The currently supported DEXes are:

  • Uniswap v2

  • Uniswap v3

  • Balancer

  • Sushiswap

Creating a profit/loss report

rotki creates a profit/loss report (called PnL for short) for you based on your trades and other events and the provided accounting settings. This is essentially a calculation of profit or loss for all your events based on the given dates. Before getting into the details of generating a report, here’s a few important details regarding the 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”).

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

How to run the PnL report

To create a PnL report click on the “Profit and Loss Report” button from the left menu. Choose a period for the report (or click on Custom to set a custom time range) and press on “Generate” to start the report.

Overview of the profit/loss report

The calculation may take some time. You can also see a summary of the accounting setting the report is running with in the “Accounting settings” section.

If you encounter any problems during the profit/loss report check out the PnL report creation problems section.

Results of the PnL report

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 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 profit/loss 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 all_event 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.

  • location is a string describing the location the event occured at. For example “kraken” for kraken trades.

  • 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 number specifying the amount of paid_asset involved in an event, e.g. in “I bought 1 ETH for 100 EUR”, 100 is the paid_in_asset.

  • taxable_amount: is a number specifying the amount of paid_asset needed to be taken into consideration for tax purposes according to the accounting settings, 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 number specifying the amount of received_asset 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 number specifying the amount of profit or loss an event accounts for given the selected accounting strategy. 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 is a virtually generated event. Only appears if the crypto to crypto setting is set. In many jurisdictions, crypto to crypto trades are taxable at the rate of the equivalent fiat currency. So an additional virtual buy is always generated for a crypto to crypto sell and the opposite for a crypto to crypto buy. So for example selling BSV for BTC would also make the user buy BTC with EUR as a virtual event, assuming EUR is the set profit currency.

  • paid_in_XXX, where XXX is the user’s customized profit_currency is a number 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 number 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_XXX 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.

  • cost_basis If this is a spending event, this field contains information about where the amount that is spent came from according to the user’s setting. Which buys contributed to this spend. If not enough information is known then this is also stated.

Note

To learn more about profit_currency or to adjust it, see the section Changing the Profit Currency

Cost basis

Cost basis is a really important aspect of accounting. For each sell event it lets you know what was the price at which the sold asset was acquired depending on a number of settings.

Cost basis is calculated in rotki for all trades/events we support. Trades/events that rotki recognizes are:

  • All trades performed in our supported centralized exchanges

  • All trades done in our supported AMMs. As of this writing this is uniswap, sushiswap, balancer.

  • All manual trades inserted by the user.

  • Not strictly trades, but income/expense events by manual inserted ledger actions.

For all those trades you can see the cost basis when you create a profit loss report by:

  1. Either navigating to the trade in the generated table after the PnL report and pressing the arrow to show more details.

Cost basis in PnL report table
  1. Export the report to CSV and import it in a spreadsheet tool. We have tested it works with google spreadsheets and libreoffice. The cost basis column contains the info you seek.

Cost basis in PnL report spreadsheet

PnL report creation problems

No documented acquisition found

It’s possible that rotki is not able to find an acquisition event for a sale. In which case it will warn you and ask you to fix it.

Example warning:

No documented acquisition found for asset

This can happen for many reasons. The asset may have been acquired in a non-supported exchange/protocol, some event not detected etc.

The way to fix it is to add either a manual trade or a manual income/expense event to tell rotki how you acquired that asset.

Timeout or price not found for timestamp

Figure out which asset caused the price not found. Then check the historical price caches and make sure you have the historical price cache for that asset pair created. For example if you are creating a GBP profit/loss report and the asset is GNO then make sure to create the GNO -> GBP historical price cache. See Manage historical price oracle cache on how to do it.

Analytics

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

Note

The starting point of the for these analytics will be when you started using the application as rotki takes balance snapshots daily. We also plan to provide analytics on data before that in a best effort basis as detailed in this issue.

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

We have introduced an option in the asset graphs to select the Missing snapshot multiplier. It sets after how many hours between two snapshots the graph will display zero balances. This allows to improve graphs for periods where the balance of an asset was zero.

Multiplying option in assets graphs

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

Gitcoin Grants

As a premium user you can also keep track of your Gitcoin grants and generate reports for them.

Gitcoin grant events

You need to first find the id ofthe grant you are interested in. When you visit the grant, the id is what comes after the grants/ part of the url. For example for rotki (https://gitcoin.co/grants/149/rotki) the id is 149.

You type the grant id, select a period you are interested in and press the fetch button to retrieve the events for this period. After the the retrieval completes you should be able to see the list of the events for this Grant.

Gitcoin grant events

With the events retrieved you can also generate reports for specific periods. In these reports you can see a breakdown of the assets received for the specified grant over the selected period.

Warning

The report depends on the already fetched events. If any events are missing during the selected report period then they will not be included in the generated report.

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,
    "log-dir": "/path/to/dir",
    "data-dir": "/path/to/dir",
    "sleep-secs": 20,
    "max_size_in_mb_all_logs": 500,
    "max_logfiles_num": 2
}

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.

  • log-dir: The name for the log directory.

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

  • max_size_in_mb_all_logs: This is the maximum size in megabytes all logs of a single run can have

  • max_logfiles_num: This is the maximum number of backup (rotated) logs a single run can have.

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

Out of gas error during eth_call

If you see an error like the following:

[17/12/2020 18:31:29 CET] WARNING rotkehlchen.chain.ethereum.manager: Failed to query own node for <bound method EthereumManager._call_contract of <rotkehlchen.chain.ethereum.manager.EthereumManager object at 0x7f4b16b8bc90>> due to Error doing call on contract 0x06FE76B2f432fdfEcAEf1a7d4f6C3d41B5861672: {'code': -32000, 'message': 'out of gas'}

while rotki is querying your local geth node for something then it means that the query has hit the gas limit cap.

You can fix this by simply adding the --rpc.gascap 0 argument to your geth node. This will have an unlimited gascap. Be careful if it’s a node exposed to the public as this may allow a malicious eth_call to crash your node.

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.

Restoring backed up database at new account creation fails

Please, make sure you are using your premium subscription API keys/secret and the same password.

Data with multiple accounts/devices is not synced

Please, make sure all your accounts have the “Allow data sync with rotki Server” switched on, and that on each log-in you make the appropriate choice when prompted to replace the local database. See the section Sync data with rotki Server for more information about how to sync data with multiple accounts/devices.