MMM-CoinMarketCap

This is a module for the MagicMirror² smart mirror project.

This module displays cryptocurrency information from the Coin Market Cap website.

Status	Version	Date	Maintained?	Minimum MagicMirror² Version
Working	`2.4.2`	2022-02-02	Yes	`2.2.1`

Example

Notable Features

Get data for any currency (Coins and Tokens) listed on Coin Market Cap
Automatic download of currency logos
Line graph of value changes over 1 day, 1 week, or 1 month
Simple built-in view selection with highly customizable view configuration

Dependencies

The Coin Market Cap Pro API (v1): For the currency data
- A free API key is required, sign up on the Coin Market Cap Developers page
The Coin Market Cap website: For the graphs and downloading currency logos

Installation

To install the module, use your terminal to:

Navigate to your MagicMirror's modules folder. If you are using the default installation directory, use the command:
cd ~/MagicMirror/modules
Copy the module to your computer by executing the following command:
git clone https://github.com/glitch452/MMM-CoinMarketCap.git
Enter the 'MMM-CoinMarketCap' directory and Install the node modules:
cd MMM-CoinMarketCap && npm install

Using the module

Api Keys

CoinMarketCap has disabled their fully public API, so this module has been updated to use their Pro API. Unfortunately, this API requires an API key when accessing the data. Thankfully, there is a free tier called basic which should be sufficient for most users. To get your API Key, sign up on CoinMarketCap.

The new API does track and limit usage by a credit system. At this time, the limit for credit usage on the basic (Free) tier is a soft 333 per day and a hard 10,000 per month. This module uses 1 credit on startup to download the list of available currencies. Then, each udate request uses 1 credit per 100 currencies (rounded up to the nearest 100). Therefore, for a list of currencies that is less than 100, in a 31 day month, the update request rate should be less than or equal to 13 updates per hour (ie. an update approximately every 4.6 minutes).

A quick note: The updates are managed by the module instance on the front-end, so each additional instance of the module will perform its own API calls and consume credits. If you require multiple instances of the module, they should each get their own API key, or the update rate can be adjusted accordingly.

MagicMirror² Configuration

To use this module, add the following configuration block to the modules array in the config/config.js file:

var config = {
    modules: [
        ...
        {
            module: 'MMM-CoinMarketCap',
            position: "top_left",
            header: "Cryptocurrencies",
            config: {
                apiKey: 'your_api_key_here',
                currencies: ['bitcoin', 'ethereum', 'litecoin', 'ripple'],
                view: 'graphWithChanges',
                conversion: 'CAD',
                // See below for more Configuration Options
            }
        },
        ...
    ]
}

Configuration Options

Option	Details
`apiKey`	REQUIRED - A free API key for the CoinMarketCap Pro API. Sign up for your API Key Here. Type: `string`
`currencies`	Optional - A list of currencies to display. Each item in the list can be either the name, symbol, or id of the currency, or an object that contains specific configuration options for the currency. See the Coin Market Cap API for a list of available currencies. Type: `array` Default: `[ 'bitcoin', 'ethereum' ]` Array Item Types: - `number` The ID of the currency - `string` The name of the currency. (can be the full name, symbol [short name] or slug) - `object` An object containing formatting options specific to the individual currency. Either the `id` or `name` properties are required. The available properties for the object are: `fontSize`, `fontColor`, `percentChangeColored`, `significantDigits`, `decimalPlaces`, `usePriceDigitGrouping`, `showCurrencyWithPrice`, `logoSize`, `logoColored`, `graphSize`. See below for the details of each option. If an option is not provided for a currency entry, it will default to the value of the option of the same name from the main options list.
`view`	Optional - A pre-configured view, used to display the currencies. The view option can be used with or without other configuration options. The other configuration options will override the options configured by the selected view. See the View Examples section for an example of each view. Type: `string` Default: `'detailed'` Options: `'detailed'`, `'detailedSymbol'`, `'detailedWithUSD'`, `'graph'`, `'graphColored'`, `'graphWithChanges'`, `'logo'`, `'logoColored'`
`conversion`	Optional - The currency to convert the price into. See the Full List Type: `string` Default: `'USD'` Options (FIAT): `'AUD'`, `'BRL'`, `'CAD'`, `'EUR'`, `'GBP'`, ... Options (Crypto): `'BTC'`, `'ETH'`, `'XRP'`, `'LTC'`, `'BCH'`, ...
`columns`	Optional - A list of columns to display. The columns will be displayed in the order of the items in this array. Type: `array` Default: `[ 'name', 'price', 'change1h', 'change24h', 'change7d' ]` (depending on `view`) Options: - `'name'` The full name of the currency (ex: Bitcoin) - `'symbol'` The short name of the currency (ex: BTC or ETH) - `'price'` The price of the currency using the currency type specified by the conversion option - `'logo'` The image of the currency logo - `'change1h'` The percentage change of the currency value over 1 hour - `'change24h'` The percentage change of the currency value over 24 hours - `'change7d'` The percentage change of the currency value over 7 days - `'graph'` A line graph representing the changes in the currency value. The time period for the graph data can be set using the `'graphRange'` option - `'changes'` The percentage change of the currency value for all three time periods (stacked vertically) - `'priceWithChanges'` The price in the selected currency with the percentage changes below the price
`showColumnHeaders`	Optional - Show the table header row. Type: `boolean` Default: `true` (depending on `view`)
`columnHeaderText`	Optional - The text to be shown for the header of each column. The object is formatted as follows: `{ column_type: 'header_text' }` where the column_type can be any valid value for the `columns` option and the header_text is the text to be displayed for that column's header. For the price and priceWithChanges columns, the string `'{conversion}'` will be replaced with the value from the `conversion` option. For the graph column, the string `'{range}'` will be replaced with a short text representation of the selected `graphRange` option, and the string `'{days}'` will be replaced with the number of days selected in the `graphRange` option. Type: `object` Default: `{ name: 'Currency', symbol: 'Currency', price: 'Price ({conversion})', priceWithChanges: 'Price ({conversion})', logo: '', change1h: 'Hour', change24h: 'Day', change7d: 'Week', graph: 'Trend ({range})', changes: 'Changes' }`
`showRowSeparator`	Optional - Show a line to separate each currency. Type: `boolean` Default: `true`
`fullWidthMode`	Optional - Whether the table should fill the width of the region that it is assigned to. When true, the table width is set to `'100%'`. Type: `boolean` Default: `true` (depending on `view`)
`fontSize`	Optional - The main font size to use for the module text. Type: `string` Default: `'small'` (depending on `view`) Options: `'x-small'`, `'small'`, `'medium'`, `'large'`, `'x-large'`
`fontColor`	Optional - The colour to use for the module text. Type: `string` Default: MagicMirror's default color Options: Any valid CSS color value. See w3schools for more info.
`percentChangeColored`	Optional - Whether the change percentages should be coloured. When true, the negative values will be colored red and the positive values will be colored green. Type: `boolean` Default: `false` (depending on `view`)
`significantDigits`	Optional - The maximum number of significant digits to round the price to. (including digits after the decimal) Set to `0` to disable the filter. Type: `integer` Default: `0`
`decimalPlaces`	Optional - How many digits to display in the price after the decimal. Type: `integer` Default: `2`
`usePriceDigitGrouping`	Optional - Whether the digits in the price should be grouped. This is locale specific based on the MagicMirror language selected and the `conversion` option. (ex: $95,462 vs $95462) Type: `boolean` Default: `true`
`showCurrencyWithPrice`	Optional - Whether the currency type should be shown after the price. When true, the price value will be followed by the currency type selected in `conversion`. (ex: $56.25 USD) Type: `boolean` Default: `false` (depending on `view`)
`logoSize`	Optional - The size of image to be used in the `logo` column. Type: `string` Default: `'medium'` Options: `'small'`, `'medium'`, `'large'`, `'x-large'`
`logoColored`	Optional - Whether to show a color or black and white logo image. When true, the color logo will be used. Type: `boolean` Default: `false` (depending on `view`)
`cacheLogos`	Optional - Whether or not to download the logo images. When true the images will be downloaded, when false, they will be referenced from Coin Market Cap. Type: `boolean` Default: `true`
`graphRange`	Optional - The number of days to show for the `graph` column. Type: `number` Default: `7` Options: `1`, `7`, `30`
`graphSize`	Optional - The size of graph to display in the `graph` column. Type: `string` Default: `'medium'` Options: `'x-small'`, `'small'`, `'medium'`, `'large'`, `'x-large'`
`graphColored`	Optional - Whether or not to use colors for the sparkline graps. When true the 1 day and 7 day graphs will be green when the currency value has increased over the period, and red when it has decreased. If false or using 30 day graphs, the standard grey color will be used. Type: `boolean` Default: `false`
`updateInterval`	Optional - The number of minutes between data updates. The minimum value is `5`. Type: `number` Default: `10`
`retryDelay`	Optional - If a data update request fails, this is the number of seconds to wait before trying again. Type: `number` Default: `10`

View Examples

View Name	Example
`detailed`
`graph`
`graphColored`
`graphWithChanges`
`logo`
`logoColored`

Custom Views

Here is an example of a custom view created using the following configuration options:

    ...
    config: {
        currencies: [
            { decimalPlaces: 0, name: 'bitcoin', logoSize: 'large', logoColored: true, percentChangeColored: true, fontSize: 'medium', fontColor: 'yellow' },
            'ethereum',
            { name: 'Ripple', significantDigits: 0, decimalPlaces: 5 },
            'litecoin',
            'iota'
        ],
        showColumnHeaders: false,
        columns: [ 'logo', 'price', 'changes', 'graph' ],
        significantDigits: 3,
        decimalPlaces: 3,
    }
    ...

Custom Logo Images

By default, this module will download the logo image files for the requested currencies. It will save them into the logos folder located in the module's folder. Some logos for popular currencies have already been provided with this module. If you would like to use your own logo for a particular currency, simply replace the .png file in the logos folder with your custom logo file. New logo files will only be downloaded if there is NOT already an existing file in the logos folder.

When using black and white logo mode, this module actually loads the color logos and a CSS filter is applied to convert the image to grayscale. This looks great for most of the logos, but as you can imagine, there may be some that don't look as good as the rest. If you would prefer a better black and white logo for a particular currency, you can make your own image file and place it into the logos\bw folder. Note: the images from the logos\bw will be displayed as is, with no CSS filtering applied, so they need to be grayscale images.

The naming convention for the logos is as follows: {symbol}-{size}.png. {symbol} represents the currency's short name, usually 3 to 5 characters, which MUST be in lower case. {size} represents the size of the image in pixels. There are 4 sizes configured in this module: 16, 32, 64, and 128. These image files should be 16x16px, 32x32px, 64x64px, and 128x128px respectively. Example: btc-16.png

Updates

To update the module to the latest version, use your terminal to:

Navigate to your MMM-CoinMarketCap folder. If you are using the default installation directory, use the command:
cd ~/MagicMirror/modules/MMM-CoinMarketCap
Update the module by executing the following command:
git pull

If you have changed the module on your own, the update will fail.
To force an update (WARNING! your changes will be lost), reset the module and then update with the following commands:

git reset --hard
git pull

Manually Choose a Version

To use an older version of this module, use your terminal to:

Navigate to your MMM-CoinMarketCap folder. If you are using the default installation directory, use the command:
cd ~/MagicMirror/modules/MMM-CoinMarketCap
Fetch all the available tags
git fetch
Show all the available tags
git tag
Checkout one of the available tags
git checkout {tag_name}
Example: git checkout v1.0.0

To switch back to the latest version, use your terminal to:

Navigate to your MMM-CoinMarketCap folder. If you are using the default installation directory, use the command:
cd ~/MagicMirror/modules/MMM-CoinMarketCap
Checkout the master branch
git checkout master

License

The MIT License (MIT)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

The software is provided “as is”, without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software.

glitch452 / MMM-CoinMarketCap