crypto-portfolio-viewer

Crypto Portfolio Viewer

View your aggregated cryptocurrency portfolio automagically, no matter where the assets are located:

• exchanges ✅
• ETH wallets ✅
• anywhere else, no problem! ✅
• Polkadot parachains (soon)
• BSC & Heco (someday)

Basic Usage

install

$ yarn add crypto-portfolio-viewer
$ npm install crypto-portfolio-viewer --save

import

const {
  getPortfolio,
  printPortfolioNicely,   // optional
} = require('./crypto-portfolio-viewer');

eth + erc20 assets

we can easily view all ETH and ERC20 tokens using ETH addresses.

const addresses = [                         
  '0x0000000000000000000000000000000000011111',
  '0x00000000000000000000000000000000000fffff',
  // ......
];

(async () => {
  const portfolio = await getPortfolio({ addresses });
  printPortfolioNicely(portfolio);
})();

exchange assets

we can easily view all exchanges assets using exchange api keys. Exchange namings please refer to ccxt.

const keys = {                               
  binance: {
    apiKey: "xxxxxxxxxx",
    secret: "yyyyyyyyyy"
  },
  ftx: {
    apiKey: "aaaaaaaaaa",
    secret: "bbbbbbbbbb",
  },
  // ......
};

(async () => {
  const portfolio = await getPortfolio({ keys });
  printPortfolioNicely(portfolio);
})();

any other assets

we can easily view any other assets by hard coding their counts.

const othertokens = {                        
  "BTC": [8.5],         // in mysterious wallet
  "BNB": [200],         // in BSC
  "ETH": [10, 30],      // uni-LP, sushi-LP
  "USDT": [
    1000,               // borrowed by Alex
    2000,               // borrowed by Kate
    5000,               // my mining machine's value
  ],
  // ......
};

(async () => {
  const portfolio = await getPortfolio({ othertokens });
  printPortfolioNicely(portfolio);
})();

ALL assets

Being able to aggregate all assets is the soul of a portfolio viewer. -- Aristotélēs

we can easily view all of our assets across many different places, by combining the usages above.

const keys = {                               
  binance: {
    apiKey: "xxxxxxxxxx",
    secret: "yyyyyyyyyy"
  },
  ftx: {
    apiKey: "aaaaaaaaaa",
    secret: "bbbbbbbbbb",
  },
};

const addresses = [                         
  '0x0000000000000000000000000000000000011111',
  '0x00000000000000000000000000000000000fffff',
];

const othertokens = {                        
  "BTC": [8.5],         // in cold wallet
  "BNB": [200],         // in BSC
  "ETH": [10, 30],      // uni-LP, sushi-LP
  "USDT": [
    1000,               // borrowed by Alex
    2000,               // borrowed by Kate
    5000,               // my mining machine's value
  ],
};

(async () => {
  const portfolio = await getPortfolio({
    keys,
    addresses,
    othertokens,
  });

  printPortfolioNicely(portfolio);
})();

example result

$ node getPortfolio.js
started to fetch portfolio data ...
(1/5) fetching exchange token counts ...
(2/5) fetching ERC20 token counts ...
(3/5) fetching other token counts ...
(4/5) fetching all token prices ...
(5/5) calculating all token values ...
finished!! Let's go Bitcoin!!

----------------------------------------------------------
₿                    Binance tokens                      ₿
----------------------------------------------------------
| name  | USD value | ratio | BTC value | price  | count |
|-------|-----------|-------|-----------|--------|-------|
| TOTAL | $25000    | 100%  | ₿2.5      | $0     | 0     |
| BTC   | $10000    | 40%   | ₿1        | $10000 | 1     |
| ETH   | $10000    | 40%   | ₿1        | $1000  | 10    |
| BNB   | $5000     | 20%   | ₿0.5      | $100   | 50    |

----------------------------------------------------------
₿                      FTX tokens                        ₿
----------------------------------------------------------
| name  | USD value | ratio | BTC value | price  | count |
|-------|-----------|-------|-----------|--------|-------|
| TOTAL | $15000    | 100%  | ₿1.5      | $0     | 0     |
| BTC   | $10000    | 66%   | ₿1        | $10000 | 1     |
| ATOM  | $10000    | 66%   | ₿1        | $20    | 500   |
| USDT  | $-5000    | -33%  | ₿-0.5     | $1     | -5000 |
// negative value means borrowed from contract or margin
// this can be disabled or customized

----------------------------------------------------------
₿                  ETH + ERC20 tokens                    ₿
----------------------------------------------------------
| name  | USD value | ratio | BTC value | price  | count |
|-------|-----------|-------|-----------|--------|-------|
| TOTAL | $30000    | 100%  | ₿2        | $0     | 0     |
| UNI   | $20000    | 66%   | ₿2        | $50    | 400   |
| ETH   | $10000    | 33%   | ₿1        | $1000  | 10    |

----------------------------------------------------------
₿                     other tokens                       ₿
----------------------------------------------------------
| name  | USD value | ratio | BTC value | price  | count |
|-------|-----------|-------|-----------|--------|-------|
| TOTAL | $50000    | 100%  | ₿5        | $0     | 0     |
| DOT   | $30000    | 60%   | ₿3        | $100   | 300   |
| KSM   | $20000    | 40%   | ₿2        | $1000  | 20    |

----------------------------------------------------------
₿                      all tokens                        ₿
----------------------------------------------------------
| name  | USD value | ratio | BTC value | price  | count |
|-------|-----------|-------|-----------|--------|-------|
| TOTAL | $120000   | 100%  | ₿12       | $0     | 0     |
| DOT   | $30000    | 25%   | ₿3        | $100   | 300   |
| KSM   | $20000    | 16.7% | ₿2        | $1000  | 20    |
| UNI   | $20000    | 16.7% | ₿2        | $50    | 400   |
| BTC   | $20000    | 16.7% | ₿2        | $10000 | 2     |
| ETH   | $20000    | 16.7% | ₿2        | $1000  | 20    |
| ATOM  | $10000    | 8.3%  | ₿1        | $20    | 500   |
| BNB   | $5000     | 4.1%  | ₿0.5      | $100   | 50    |
| USDT  | $-5000    | -4.1% | ₿-0.5     | $1     | -5000 |

Advanced Usage

custom printer

Viewing result nicely is the soul of a portfolio viewer. --Shakespeare

we can easily print the result in your favorite fashion:

const myFavoritePrinter = portfolio => { ... };

(async () => {
  const portfolio = await getPortfolio({
    keys,
    addresses,
    othertokens,
  });

  myFavoritePrinter(portfolio);
})();

combine results

by default we view each exchange and each ETH address separately:

----------------------------------------------------------
₿                    Binance tokens                      ₿
----------------------------------------------------------
......
----------------------------------------------------------
₿                      FTX tokens                        ₿
----------------------------------------------------------
......
----------------------------------------------------------
₿                 0x1234...5678 tokens                   ₿
----------------------------------------------------------
......
----------------------------------------------------------
₿                 0x9876...5432 tokens                   ₿
----------------------------------------------------------

to simplify our portfolio, we can combine them as a whole

(async () => {
  const portfolio = await getPortfolio({
    keys,
    addresses,
    othertokens,
    combineExchanges: true,     // <--here
    combineAddresses: true,     // <--here
  });

  printPortfolioNicely(portfolio);
})();

----------------------------------------------------------
₿                    exchange tokens                     ₿
----------------------------------------------------------
all exchange tokens combined print here ......

contract/future accounts

For contract/future/margin assets in exchanges, since the ccxt library that we rely on doesn't yet provide unified interfaces for these accounts, there is no automatted way to catch them into the exchange result.

But don't worry, we have 2 different ways to inlcude them into our portfolio:

1) hard code

We can hard code these assets in othertokens. (from example above) This is pretty convenient, but we will have to manually update othertokens whenever assets change in future accounts.

2) custom fetcher

We can also provide a custom fetcher for each exchange. This is more flexible and powerful. One huge advantages is being able to include contract positions as assets, which enables us to more precisely calculate portfolio details (which I personally use A LOT!!).

For example, if we have 1000 USDT collateral, as well as a contract position of BTC long (2000 USDT worth), then technically our 'real' portfolio should look like

{
  USDT: { USD_value: -1000, ... },    // 1000 (collateral) - 2000 (borrowed)
  BTC:  { USD_value: 2000, ... },
}

with method 1 (hard code), on the other hand, our 'fake' portfolio looks like

{
  USDT: { USD_value: 1000, ... },    // 1000 (collateral) 
  BTC:  { USD_value: 0, ... },       // totally ignores contract positions!
}

available fetchers

There are already 2 fetchers that I personally use, feel free to use them directly. You can also reference them to write your own, or even better, contribute your custom fetchers : )

const {
  getPortfolio,
  printPortfolioNicely,
  fetchers,
} = require('./crypto-portfolio-viewer');

const {
  fetchBinanceContractBalances,
  fetchFTXContractBalances,
} = fetchers;

(async () => {
  const portfolio = await getPortfolio({
    keys,
    addresses,
    othertokens,
    extraFetchers: {
      binance: fetchBinanceContractBalances,
      ftx: fetchFTXContractBalances,,
    },
  });

  printPortfolioNicely(portfolio);
})();

APIs Summary

available parameters for getPortfolio():

param	type	default	required?	description
keys	object	{}	no	exchange api keys
addresses	array	[]	no	erc20 addresses
othertokens	object	{}	no	other tokens
extraFetchers	object	{}	no	customized fetcher for exchanges
combineExchanges	bool	false	no	combine exchange assets in result
combineAddresses	bool	false	no	combine erc20 assets in result

Special Thanks

Really appreciate all the fantastic works by ccxt and coingecko-api, which provide super useful utilities supporting this library.

Bugs? Questions? Contributions?

Feel free to open an issue, or create a pull request!

UI

coming soon