Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/glitch452/MMM-CoinMarketCap
A MagicMirror² module that displays cryptocurrency information from the Coin Market Cap website.
https://github.com/glitch452/MMM-CoinMarketCap
Last synced: 3 months ago
JSON representation
A MagicMirror² module that displays cryptocurrency information from the Coin Market Cap website.
- Host: GitHub
- URL: https://github.com/glitch452/MMM-CoinMarketCap
- Owner: glitch452
- License: mit
- Created: 2018-05-16T03:48:29.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2022-12-12T10:38:54.000Z (almost 2 years ago)
- Last Synced: 2024-06-29T09:35:37.273Z (5 months ago)
- Language: JavaScript
- Size: 822 KB
- Stars: 36
- Watchers: 4
- Forks: 11
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
- awesome-mmm - **MMM-CoinMarketCap**
README
# MMM-CoinMarketCap
This is a module for the [MagicMirror²](https://github.com/MichMich/MagicMirror/) smart mirror project.
This module displays cryptocurrency information from the [Coin Market Cap](https://coinmarketcap.com) website.
| Status | Version | Date | Maintained? | Minimum MagicMirror² Version |
| :------ | :------ | :--------- | :---------- | :--------------------------- |
| Working | `2.4.2` | 2022-02-02 | Yes | `2.2.1` |
### Example
### Notable Features
1. Get data for any currency (Coins and Tokens) listed on [Coin Market Cap](https://coinmarketcap.com)
2. Automatic download of currency logos
3. Line graph of value changes over 1 day, 1 week, or 1 month
4. Simple built-in view selection with highly customizable view configuration
### Dependencies
1. The [Coin Market Cap Pro API (v1)](https://coinmarketcap.com/api/): For the currency data
- A free API key is required, sign up on the [Coin Market Cap Developers](https://pro.coinmarketcap.com/signup/) page
2. The Coin Market Cap website: For the graphs and downloading currency logos
## Installation
To install the module, use your terminal to:
1. Navigate to your MagicMirror's modules folder. If you are using the default installation directory, use the command:
`cd ~/MagicMirror/modules`
2. Copy the module to your computer by executing the following command:
`git clone https://github.com/glitch452/MMM-CoinMarketCap.git`
3. 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](https://coinmarketcap.com/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](https://pro.coinmarketcap.com/signup/).
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:
```js
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](https://pro.coinmarketcap.com/signup/).
**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](https://api.coinmarketcap.com/v2/listings/) 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](#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](https://coinmarketcap.com/api/documentation/v1/#section/Standards-and-Conventions)
**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](https://www.w3schools.com/cssref/css_colors_legal.asp) 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:
```js
...
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:
1. Navigate to your MMM-CoinMarketCap folder. If you are using the default installation directory, use the command:
`cd ~/MagicMirror/modules/MMM-CoinMarketCap`
2. 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:
1. Navigate to your MMM-CoinMarketCap folder. If you are using the default installation directory, use the command:
`cd ~/MagicMirror/modules/MMM-CoinMarketCap`
2. Fetch all the available tags
`git fetch`
3. Show all the available tags
`git tag`
4. 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:
1. Navigate to your MMM-CoinMarketCap folder. If you are using the default installation directory, use the command:
`cd ~/MagicMirror/modules/MMM-CoinMarketCap`
2. Checkout the master branch
`git checkout master`
## License
### The MIT License (MIT)
Copyright © 2018 David Dearden
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.**