{"id":15019033,"url":"https://github.com/cytopia/coinwatch","last_synced_at":"2025-08-12T02:43:59.865Z","repository":{"id":54745502,"uuid":"119202191","full_name":"cytopia/coinwatch","owner":"cytopia","description":"Coinmarketcap console client to keep track of your crypto currency trades - are you winning or losing?","archived":false,"fork":false,"pushed_at":"2021-02-01T05:40:03.000Z","size":3229,"stargazers_count":83,"open_issues_count":2,"forks_count":16,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-12-30T15:07:38.711Z","etag":null,"topics":["bitcoin","coinmarketcap","coinmarketcap-api","cryptanalysis","crypto-trades","cryptocoins","cryptocurrencies","cryptocurrency","ethereum","monero","trading"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cytopia.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-01-27T21:00:33.000Z","updated_at":"2024-10-04T17:22:45.000Z","dependencies_parsed_at":"2022-08-14T01:30:51.899Z","dependency_job_id":null,"html_url":"https://github.com/cytopia/coinwatch","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cytopia%2Fcoinwatch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cytopia%2Fcoinwatch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cytopia%2Fcoinwatch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cytopia%2Fcoinwatch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cytopia","download_url":"https://codeload.github.com/cytopia/coinwatch/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235209006,"owners_count":18953004,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bitcoin","coinmarketcap","coinmarketcap-api","cryptanalysis","crypto-trades","cryptocoins","cryptocurrencies","cryptocurrency","ethereum","monero","trading"],"created_at":"2024-09-24T19:52:48.494Z","updated_at":"2025-01-23T01:07:14.456Z","avatar_url":"https://github.com/cytopia.png","language":"Python","readme":"# coinwatch\n\n**[Installation](#installation)** |\n**[Usage](#usage)** |\n**[Screenshots](#screenshots)** |\n**[Features](#features)** |\n**[Columns](#columns)** |\n**[Configuration](#configuration)** |\n**[Options](#options)** |\n**[API](#api)** |\n**[Requirements](#requirements)** |\n**[License](#license)**\n\n\n[![](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![PyPI](https://img.shields.io/pypi/v/coinwatch)](https://pypi.org/project/coinwatch/)\n[![PyPI - Status](https://img.shields.io/pypi/status/coinwatch)](https://pypi.org/project/coinwatch/)\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/coinwatch)](https://pypi.org/project/coinwatch/)\n[![PyPI - Format](https://img.shields.io/pypi/format/coinwatch)](https://pypi.org/project/coinwatch/)\n[![PyPI - Implementation](https://img.shields.io/pypi/implementation/coinwatch)](https://pypi.org/project/coinwatch/)\n\n[![Build Status](https://travis-ci.org/cytopia/coinwatch.svg?branch=master)](https://travis-ci.org/cytopia/coinwatch)\n[![Build Status](https://github.com/cytopia/coinwatch/workflows/linting/badge.svg)](https://github.com/cytopia/coinwatch/actions?workflow=linting)\n[![Build Status](https://github.com/cytopia/coinwatch/workflows/testing/badge.svg)](https://github.com/cytopia/coinwatch/actions?workflow=testing)\n\n\nCoinwatch is a low-dependency python-based console client client to keep track of your crypto trades and easily let's you see if you are winning or losing.\n\nAll you have to do is enter all of your purchases: **When**, **How many** coins and **price per coin**. Then each time you launch `coinwatch`, it will show your current status and will make you happy or sad.\n\n\n## Installation\n```bash\npip install coinwatch\n```\n\n\n## Usage\n```bash\n# Default run\ncoinwatch\n\n# Specify different profile/config\ncoinwatch -c ~/path/to/conf.yml\n\n# Different columns and order\ncoinwatch -r \"name buyprice nowprice wealth invest profit\"\ncoinwatch -r \"name date nowprice wealth profit percent\"\n\n# Specify sort and order\ncoinwatch -s profit -o desc\n\n# Sort and group by name\ncoinwatch -s name -g name\n\n# Disable colorized output\ncoinwatch -n\n\n# Different table border\ncoinwatch -t ascii\ncoinwatch -t thin\ncoinwatch -t thick\n\n# Alternative number format\ncoinwatch -h\n\n# Text output wrapped in watch\nwatch --interval=10 'coinwatch -n'\n```\n\n\n## Screenshots\n\nThe example shows the usage of an alternative configuration file.\n![normal](screenshot/screen-01.png)\n\nThe example shows an alternative number format\n![normal](screenshot/screen-03.png)\n\nThe example shows how it looks in text mode\n![normal](screenshot/screen-02.png)\n\nThe example shows coinwatch wrapped into `watch` and refresh every 10 seconds.\n![watcher](screenshot/screen-04.png)\n\n\n## Features\n\n* Keep track of all of your trades\n* Trades are grouped by each crypto currency\n* Different trading profiles can be used by specifying different configuration files\n* Pure text-based output is available for further processing in other tools\n\n\n## Columns\n\n`coinwatch` offers many columns that can be displayed in any order. A sane limited default is set in the configuration file which does not display all columns. You are free to alter that and adjust `coinwatch` to your needs directly in the configuration file (see **[Configuration](#configuration)**) or quickly enabled/disable columns via command arguments (`-r`). Sorting, ordering and grouping will also work on columns that are not being displayed. Have a look at the following table which shows you all available columns:\n\n| Column name | Default display | Description |\n|-------------|-----------------|-------------|\n| `name`      | no              | Name of the cryptocurrency. |\n| `symbol`    | yes             | Abbreviation name of the cryptocurrency. |\n| `buyprice`  | yes             | Price in USD at which the currency was bought. |\n| `diffprice` | yes             | Price difference in USD between buy time and now. |\n| `nowprice`  | yes             | Current price in USD of the currency. |\n| `amount`    | yes             | Total number of coins you have bought. |\n| `invest`    | yes             | Total amount in USD you have invested for all coins bought. |\n| `wealth`    | yes             | Current amount in USD your coins are worth now. |\n| `profit`    | yes             | How much profit in USD did you make on that currency. |\n| `percent`   | yes             | Percent of profit between buy time and now. |\n| `percent1h` | no              | Percent of price change in the last hour of that currency. |\n| `percent24h`| no              | Percent of price change in the last 24 hours of that currency. |\n| `percent7d` | no              | Percent of price change in the last 7 days of that currency. |\n| `vol_24h`   | no              | Volume in USD in the last 24 hours. |\n| `marketcap` | no              | Market capacity in USD.\n| `supply_a`  | no              | Currently available supply of coins. |\n| `supply_t`  | no              | Total supply of coins. |\n| `supply_m`  | no              | Maximum supply of coins. |\n| `cust1`     | no              | Custom field (see **[Configuration](#configuration)**)|\n| `cust2`     | no              | Custom field (see **[Configuration](#configuration)**)|\n| `cust3`     | no              | Custom field (see **[Configuration](#configuration)**)|\n\n**Note about custom fields:**\n\nHeadline and column width of custom fields can be set in the configuration file. The values itself can be added to your trade array and can contain any information you wish to display for a given trade. As an example they could contain information such as:\n* At what date did you buy that currency\n* At what market did you buy that currency\n* The wallet address where the coins are\n* Are the coins still online or already downloaded to a cold wallet\n\n\n## Configuration\nWhen starting `coinwatch` for the first time, it will create a default configuration file in `~/.config/coinwatch/config.yml` with no trades to watch. To get a quick overview, have a look at the [example config](example/config.yml).\n\nConfiguration is done in yaml format. If you have never heard about yaml before, have a look at its official example: http://yaml.org/start.html\n\n### Structure\nThe configuration file is build up like this:\n```yml\n# Configure coinwatch\nconfig:\n  # Specify the default column to sort this table by or leave empty for unsorted.\n  # Overwrite via -s \u003ccolumn\u003e\n  sort:\n  # Specify the sort order (asc or desc)\n  # Overwrite via -o desc\n  order: asc\n  # Configure what columns to display and in what order.\n  # To see all available columns view help: $ coinwatch --help\n  # Columns specified via command line (-r) take precedence\n  #\n  # There are also three other columns which are off by default: 'cust1', 'cust2' and 'cust3'.\n  # Enable them here or via (-r).\n  # Those three columns can be added to your trades in order to display custom information,\n  # such as which market they were bought from or on what date they were bought.\n  columns: name symbol date buyprice diffprice nowprice amount invest wealth profit percent\n  # Define your custom columns here.\n  # Set column headline and width.\n  cust:\n    cust1:\n      headline: BUY DATE\n      width: 10\n    cust2:\n      headline: MARKET\n      width: 10\n    cust3:\n      headline: EXAMPLE\n      width: 10\n  # Specify your table border style\n  # Available values: thin, thick and ascii\n  # Use ascii if you want to further process the output of this application\n  table: thin\n\n# Configure your purchases\ntrades:\n  # CURRENCY_ID is found by looking up the 'id' key from\n  # https://api.coinmarketcap.com/v1/ticker/?limit=0\n  CURRENCY_ID:  # \u003c-- [array]       Each currency will hold a list of trades\n    - amount:   # \u003c-- [decimal]     [1] How many coins for that currency were bought\n      invest:   # \u003c-- [decimal]     [1] How much money in total was invested\n      price:    # \u003c-- [decimal]     [1] Price for 1 coin of that currency\n      cust1:    # \u003c-- [string]      Custom column\n      cust2:    # \u003c-- [string]      Custom column\n      cust3:    # \u003c-- [string]      Custom column\n```\n\n**`[1]`** `amount`, `invest` and `price` at the same time? Yes that's right there is duplication, however only always two of those three can be specified at the same time. This gives the possibility to record you trades in three different ways:\n\n#### Option-1: amount and invest\nHow many coins did you buy and how much money in total did you spent on that?\n\nThis option is most useful when having done a real purchase. Enter the total money spent and the coins received. That way you don't have to calculate any market fees or transaction fees yourself.\n```yml\n# Bought 0.4 coins\n# Total cost of that: 3742.35 $\ntrades:\n  bitcoin:\n    - amount: 0.4\n      invest: 3742.35\n```\n#### Option-2: amount and price\nHow many coins did you buy and how much did one coin cost?\n\nThis option is most useful when doint dry-run trades - *What would have happened if*. Enter how many coins you had bought at what price per coin.\n```yml\n# Bought 0.4 coins\n# 1 Bitcoin had a price of: 9355.875 $\ntrades:\n  bitcoin:\n    - amount: 0.4\n      price:  9355.875\n```\n#### Option-3: invest and price\nHow much money in total did you spend and how much did one coin cost?\n\nThis option is most useful when doint dry-run trades - *What would have happened if*. Enter how much money you would have spent and what the price per coin was.\n```yml\n# Total cost of that: 3742.35 $\n# 1 Bitcoin had a price of: 9355.875 $\ntrades:\n  bitcoin:\n    - invest: 3742.35\n      price:  9355.875\n```\n\n### Get currency names\n\nWhen adding new cryptocurrencies, you need to make sure that you use the correct name to add to the configuration file. Names can be retrieved from https://api.coinmarketcap.com/v1/ticker/?limit=0.\n\n| Screenshot | Explanation |\n|------------|-------------|\n| ![api](screenshot/api.png) | When visiting the coinmarketcap API page, look for the `id` field of a currency and use its value to add to the configuration file.\u003cbr/\u003e\u003cbr/\u003eIn case you wanted to add Ethereum and Bitcoin as seen in the example screenshot, you would use `ethereum` and `bitcoin` as names to put into your configuration file. |\n\n\n### Example\nAn example file could look like this. It shows three bitcoin trades (with each different option to specify your purchases), one ethereum trade and an empty place holder for iota. When specifying an empty array, it serves only as a reminder for you to fill that out later and will not be shown in the stats.\n\nAdditionally two custom fields have been configured to add more information to each trade. It is used to display the buy date as well as the market where it was bought from. Then in order to actually show those columns, the `columns` configuration has been changed to also add these two fields.\n```yml\nconfig:\n  columns: name symbol cust1 cust2 buyprice diffprice nowprice amount invest wealth profit percent\n  cust:\n    cust1:\n      headline: BUY DATE\n      width: 01\n    cust2:\n      headline: MARKET\n      width: 10\n\ntrades:\n  bitcoin:\n    # Option-1: Invested 500.00$ and got 0.0425 coins\n    - amount: 0.4\n      invest: 3742.35\n      cust1:  2017-12-03\n      cust2:  binance\n    # Option-2: bought at 10,010.50 and bought 0.5 coins\n    - amount: 0.4\n      price:  9355.875\n      cust1:  2017-12-04\n      cust2:  binance\n    # Option-3: invested 500.00$ at 11,043.12 price/coin\n    - invest: 3742.35\n      price:  9355.875\n      cust1:  2017-12-05\n      cust2:  binance\n  ethereum:\n    - amount: 20\n      price:  1070\n      date:   2017-12-05\n  # Note in this case 'iota' is defined as an empty array\n  # and will not be shown in the stats.\n  iota: []\n```\nThe following does not show any trades, it might however serve as a reminder for you to actually trade later and already have that info present:\n```yml\ntrades:\n  bitcoin: []\n  ripple:  []\n  cardano: []\n  iota:    []\n  qtum:    []\n  omisego: []\n```\n\n\n## Options\nThis shows the output of `coinwawtch --help`.\n```bash\nUsage: coinwatch [-crtnhv]\n       coinwatch [--help]\n       coinwatch [--version]\n\ncoinwatch is a low-dependency python[23] client to keep track of your crypto trades\nand easily lets you see if you are winning or losing.\n\nOPTIONS:\n  -c, --config   Specify path of an alternative configuration file.\n                 Examples:\n                   -c path/to/conf.yml\n  -r, --row      Specify the order and columns to use in a row.\n                 In case you dont need all columns to be shown or want\n                 a different order of columns, use this argument to specify it.\n                 Examples:\n                   -r \"name date profit percent\"\n                   -r \"name buyprice nowprice amount wealth\"\n                 Default:\n                   -r \"name symbol date buyprice nowprice amount invest wealth profit percent\"\n  -s, --sort     Specify the column name to sort this table.\n                 See above for available columns.\n                 The table can also be sorted against columns that are not displayed.\n                 The default is unsorted.\n  -o, --order    Specify the sorting order.\n                 Valid orders: 'asc' and 'desc'.\n                 The default order is 'asc'.\n  -g, --group    Group by column name (visually).\n                 Grouping is applied after sorting and only equal vertical rows of\n                 the specified group column are grouped.\n  -t, --table    Specify different table border.\n                 Available values: 'thin', 'thick' and 'ascii'.\n                 The default is 'thin'.\n                 In case you need to process the output of this tool use 'ascii'.\n                 Examples:\n                   -t thin\n                   -t thick\n                   -t ascii\n  -n, --nocolor  Disable shell colors. This is useful if you want to further\n                 process the output of this program.\n  -h, --human    Alternative human readable number format.\n  -v, --verbose  Be verbose.\n\nNOTE:\n  No financial aid, support or any other recommendation is provided.\n  Trade at your own risk! And only invest what you can effort to lose.\n\nAPI:\n  Currently supported remote price and coin APIs are:\n    - coinmarketcap\n\nCONFIGURATION:\n  When starting coinwatch for the first time a base configuration file will be\n  created in ~/.config/coinwatch/config.yml.\n  You should edit this file and add your trades:\n    - What currency\n    - When bought\n    - How much bought\n    - Price for 1 coin of currency at that date\n```\n\n\n## API\n\nCurrently supported remote API's are:\n  - [coinmarketcap](https://api.coinmarketcap.com/v1/ticker/?limit=0)\n\n\n## Requirements\n\n`coinwatch` itself requires `PyYaml`. Apart fromt that, only one of the following Python versions is required:\n\n* Python 2.7 (requires `future` for Python 3 compat)\n* Python 3.2\n* Python 3.3\n* Python 3.4\n* Python 3.5\n* Python 3.6\n\n\n## License\n\n**[MIT License](LICENSE.md)**\n\nCopyright (c) 2018 [cytopia](https://github.com/cytopia)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcytopia%2Fcoinwatch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcytopia%2Fcoinwatch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcytopia%2Fcoinwatch/lists"}