k57-portfolio
Manage your cryptocurrencies
Free, open-source, no ad, no data theft.

Brief presentation of the application

If, like me, you're scattered all over the crypto world (multiple wallets, multiple blockchains, multiple protocols, dozens of different tokens, several centralized exchanges, ...), you may find it difficult to manage all of this. If Excel is no longer enough, then this program can help you. Bitcoin maximalists won't find much interest in it.

What does this program do ?

Serves as a register for all crypto holdings, with a simple and intuitive interface for creating, editing, or deleting positions.
Organizes your positions by wallet+blockchain or by centralized exchange.
Updates token prices using the CoinMarketCap API
Calculates the portfolio value.
Allows setting reminders for each position on when to "manage" them again (composition of interests, unlock date, balance updates, unbonding, claim, or any other events ...).
Filters positions based on certain criteria.
Displays doughnut charts on the entire portfolio or on a part of it.
Manages debts (negative balances).
Calculates the overall portfolio yield (APR).

What doesn't it do ?

Does not update balances automatically; this must be done manually from time to time (usually, this varies little).
Does not perform any transactions or access on-chain data.
Does not keep any price or balance history, nor any other type of history.
No language selection (everything is in English).
No currency selection (everything is represented in dollars).

Home

This page only displays the portfolio value, but it's also the only one that updates automatically at regular intervals. Prices are retrieved via the CoinMarketCap API.

Assets / Portfolio's composition

This page provides an overall summary of the portfolio's assets, taking all positions in account, including LP, debts, and derivative tokens. At the bottom of the table, in gray, are the derivative tokens (already counted in the underlying token).

Note: All dollar stablecoins can be grouped together as derivatives of the "USD token". Even though the USD token doesn't exist, it's a construct for tracking dollar-based stablecoins.

View positions / Search positions

This page allows you to filter the positions to be displayed and group them. Here's an overview of the many possibilities offered by this page.

Click on the grey boxes to reveal (then hide) the screenshots illustrating the examples. The screenshots are sometimes truncated in this guide.

■■■

Database : Create / Edit / Remove

This page allows you to create/modify/delete database items.

CEX: A list of trusted third parties that hold their clients' cryptocurrencies.
Wallet: A list of ways to store cryptocurrencies. A wallet typically corresponds to one of the following cases:
- A seed phrase
- A pair of private/public keys
- An account of a hot wallet
Each wallet can be "cold" or not.
Blockchain: Each blockchain may or may not belong to an ecosystem (another blockchain). This allows grouping together positions that are on "sister" blockchains.
Token: A list of tokens/coins. Each token may or may not be derived from another token. This allows grouping together positions that share the same underlying asset. For each token, you can define the number of decimals to display for balances. You can also specify the CoinMarketCap and/or CoinGecko slug for clickable links in the application.
Position: A position is a set of "token holdings" that are closely related and always displayed together in the application. Typically, they fall into one of the following cases:
- They are in the same section of the same CEX. For example, in "Binance earn".
- They are both on the same protocol, the same blockchain, and the same wallet. For example, a deposit and a loan on the same lending platform.
- They are two components of the same LP.
With each manual update of the position, you can set a date for the next update to return to it at the right time.
Tag: Each position can be associated with a list of tags. This allows creating new filtering possibilities.

Update prices and show variations

This page allows you to trigger an update of token prices and to see for each of them the percentage increase or decrease. Prices are retrieved via the CoinMarketCap API.

Sorted by performances:

Getting started

Download & Install

Download the sources or installer from the kalgon57 GitHub repository. There are 2 ways to install k57-portfolio:

Install with the windows installer : A single exe file that installs everything automatically.
Install from source code : Available for both Windows and Linux (tested on Windows 10 and Ubuntu 22.04). The zip file is provided with a detailled installation guide for both operating systems.

Once installed, you should be able to try the application with a demo database by accessing This Link (add it to favorites/markups !). Note that you will not be able to update prices until you have configured the CoinMarketCap API key (see next section).

Configure

Navigate to your installation folder. Copy portfolio_basic.db from the original databases subfolder to the application folder. Rename it, for example portfolio.db.
Obtain a free CoinMarketCap API key by creating an account on CoinMarketCap.
Open config.json with a basic text editor and change the following values:
- database_filename : Enter the name you chose in step 1 without the .db extension.
- api_key : Paste your API key obtained in step 2.
- price_update_on_server_start : Set to true.
Restart your computer or simply restart the k57-portfolio service with nssm.exe.

When you modify your config.json file, to ensure it takes effect, you need to restart the k57-portfolio service with nssm.exe. If you are unsure how to do this, it's better to simply restart your computer.

Advanced topics

Configuration through config.json

Navigate to your installation folder and open config.json with a basic text editor. Here you can change the app's parameters.

port : The port for accessing the app with the browser. You may not need to change that value.
database_filename : References the database to use, which is stored in a single file in your installation folder. The installation folder also contains 3 databases in the original databases subfolder:
- portfolio_empty : Structure only, empty tables. You have to insert blockchains, tokens, etc.
- portfolio_basic : Some blockchains, tokens, and CEX are already filled. Of course you can remove or add whatever you want to fit your needs.
- portfolio_demo : Includes examples of positions, for testing the app's purpose.
You can copy one of them to the installation folder, rename it, and change the parameter accordingly. My advice is to start with a copy of portfolio_basic.db but you could also start a new one from scratch with portfolio_empty.db. Don't forget to back up your database frequently in order to be able to restore it in case of damage.
api_provider : There is no other choice than cmc. Keep this value.
api_key : To enable the price updating feature, you need an API key from CoinMarketCap. You can get one for free by creating an account on CoinMarketCap.
price_update_on_server_start : Specify whether you want the program to update prices upon startup (i.e., when you turn on your computer).
percent_small_variation : Variation threshold (in percentage) above which a line is colored in light green or light red in the Update Prices page.
percent_big_variation : Variation threshold (in percentage) above which a line is colored in green or red in the Update Prices page.
token_viewer : The two possible values are "cmc" for CoinMarketCap and "cg" for CoinGecko. This indicates to the program which website you prefer to consult for token information by clicking on them.

Special cases in the View page

Sorting for display

Groups are in the order defined by Order by except:
- If Group by is Update: Chronological.
- If Group by is Custody: Cold, then Hot, then Third-party.
- The Other group is always last (for example, if grouping by blockchain, third-party positions don't have one and will go into Other).
Positions are always in descending order of value whithin groups.
Components are always in alphabetical order within positions.

Filters Token and Underlying

If the filter is Token X or Underlying X :

Groups and the diagram only consider the quantity of X they contain, ignoring other tokens.
Positions, however, are always displayed in full (not just the X portion).

As a result :

The value of groups does not correspond to the sum of the values of their positions. Therefore, group values are not displayed to avoid confusion.
The APR of groups does not have a concrete meaning since not all positions are considered. Therefore, group APR is not displayed either.
If sorting is done by value, groups are sorted by the number of token X they contain rather than the total value of their positions.

Example :

With the Underlying filter, only ETH values are counted to rank the groups :

9080 $ of ETH on Ethereum
1597 $ of ETH on Optimism
338 $ of ETH on Polygon
126 $ of ETH on Starknet

These values are displayed in the diagram but not in the groups because they do not reflect the sum of positions. For example, the two positions on Polygon are worth much more than 338 $. It can also be seen that the groups are in the same order as in the diagram and not in the order of their total value.

Miscellaneous

Negative values are represented in black and shades of gray in the doughnut charts.
The criteria from the form are passed in the page's address (URL), so it's possible to bookmark/favorite searches.

Database management

Dependencies

Records cannot be deleted from the database if they have dependencies. For example, a token cannot be deleted if it is used in a position. This measure ensures a consistent database at all times.
Exception: A tag can be deleted even if it is used in positions; it will then be removed from all relevant positions.

No hierarchy or cycles

For each token, you can specify an Underlying Token. Similarly, for each blockchain, you can specify an Ecosystem. It is important to avoid creating cyclic or hierarchical structures. There can only be two levels of tokens: top-level underlyings and derivatives. There can only be two levels of blockchains: top-level ecosystems and non-ecosystems.

Examples of what not to do:

X is the underlying of Y, and Y is the underlying of Z. The application will not understand that X is the ultimate underlying of Z.
X is the underlying of Y, and Y is the underlying of X. This is nonsensical and can cause bugs.

Concurrent Access to the Database

The database is stored in SQLite format.

Writing:
The program is designed to work locally only, without concurrent access. It is not recommended to manually modify the database or use a third-party program while the application is running, as it reloads data into its memory each time it modifies them and not when they are modified by a third party. This could lead to inconsistencies between the actual data and the data loaded into memory.

Reading:
Reading access by a third-party program does not pose any issues.

Negative Balance, Negative APR

A negative balance represents a loan/debt.
A positive APR increases the balance in absolute value, while a negative APR decreases the balance in absolute value.

	Positive balance	Negative balance
Positive APR	Balance Increasing Over Time	Debt Increasing Over Time
Negative APR	Balance Decreasing Over Time	Debt Decreasing Over Time