{"id":19916849,"url":"https://github.com/srackham/cryptor","last_synced_at":"2026-05-13T04:36:24.057Z","repository":{"id":65095660,"uuid":"571407526","full_name":"srackham/cryptor","owner":"srackham","description":"Cryptor valuates cryptocurrency asset portfolios.","archived":false,"fork":false,"pushed_at":"2025-03-01T02:11:03.000Z","size":341,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-01T03:19:05.286Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","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/srackham.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-11-28T03:52:24.000Z","updated_at":"2025-03-01T02:11:07.000Z","dependencies_parsed_at":"2025-01-11T23:31:03.381Z","dependency_job_id":"de531e24-154e-414f-af81-d11980c7efad","html_url":"https://github.com/srackham/cryptor","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srackham%2Fcryptor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srackham%2Fcryptor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srackham%2Fcryptor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srackham%2Fcryptor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/srackham","download_url":"https://codeload.github.com/srackham/cryptor/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241347256,"owners_count":19948123,"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":[],"created_at":"2024-11-12T21:47:48.701Z","updated_at":"2026-05-13T04:36:24.052Z","avatar_url":"https://github.com/srackham.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cryptor\n\nCryptor valuates cryptocurrency asset portfolios.\n\n-   Processes multiple asset portfolios.\n-   Reports the current value and performance of cryptocurrency assets.\n\n## Installation\n\nIf you have [Go](https://go.dev/) installed on your system then you can download and compile the latest version with this command:\n\n    go install github.com/srackham/cryptor@latest\n\nPre-compiled binaries are also available on the [Cryptor releases page](https://github.com/srackham/cryptor/releases). Download the relevant release and extract the `cryptor` executable.\n\n## Quick Start\n\n1. Install an example configuration using the `cryptor init` command. For example:\n\n    ```\n    $ cryptor init\n    creating configuration directory: \"/home/srackham/.config/cryptor\"\n    installing example config file: \"/home/srackham/.config/cryptor/config.yaml\"\n    installing example portfolios file: \"/home/srackham/.config/cryptor/portfolios.yaml\"\n    creating cache directory: \"/home/srackham/.cache/cryptor\"\n    creating data directory: \"/home/srackham/.local/share/cryptor\"\n    ```\n\n2. Edit the [`portfolios.yaml` configuration file](#portfolios-configuration-file) to match your portfolios.\n\n3. Use the `cryptor valuate` command to calculate the current value the portfolios and their assets. For example:\n\n    ```\n    $ cryptor valuate\n\n    NAME:  personal\n    DATE:  2025-02-10\n    TIME:  19:08:45\n    VALUE: 55202.96 USD\n    COST:  10000.00 USD\n    GAINS: 45202.96 USD (452.03%)\n                AMOUNT            VALUE    PERCENT       UNIT PRICE\n    BTC         0.5000     48522.29 USD     87.90%     97044.58 USD\n    ETH         2.5000      6580.68 USD     11.92%      2632.27 USD\n    USDT      100.0000        99.99 USD      0.18%         1.00 USD\n    ```\n\n## Command Options\n\nRun the `cryptor help` command to view all the commands and command options:\n\n```\n$ cryptor help\n\nUsage:\n    cryptor COMMAND [OPTION]...\n\nDescription:\n    Cryptor valuates crypto currency asset portfolios.\n\nCommands:\n    init     create configuration directory and install default config and\n             example portfolios files\n    valuate  valuate, print and save portfolio valuations\n    history  Print saved portfolio valuations\n    help     display documentation\n\nOptions:\n    -aggregate                  Include aggregated portfolios in printed valuation\n    -aggregate-only             Only include aggregated portfolios in printed valuation\n    -confdir CONF_DIR           Directory containing config, data and cache files\n    -currency CURRENCY          Print fiat currency values denominated in CURRENCY\n    -notes                      Include portfolio notes in the valuations\n    -save                       Update the valuations file\n    -portfolio PORTFOLIO        Print named portfolio valuation (default: all portfolios)\n    -price SYMBOL=PRICE         Override the asset price of SYMBOL with PRICE (in USD)\n    -format FORMAT              Set the valuate command output format (\"json\" or \"yaml\")\n\nConfig directory: /home/srackham/.config/cryptor\nCache directory:  /home/srackham/.cache/cryptor\nData directory:   /home/srackham/.local/share/cryptor\n\nVersion:    v0.3.0 (-)\nGit commit: -\nBuilt:      -\nGithub:     https://github.com/srackham/cryptor\n```\n\n## Implementation and Usage Notes\n\n-   The `valuate` command values portfolio assets specified in the [`portfolios.yaml` configuration file](#portfolios-configuration-file).\n-   All values are saved in USD (the `-currency` option can be used to display printed values in non-USD currencies).\n-   Fiat currency exchange rates are cached locally and refreshed daily.\n-   Asset and currency symbols are case insensitive and are converted to uppercase.\n-   Saved portfolio valuations include the valuation's local `date` and `time`.\n-   Dates are saved as `YYYY-DD-MM` formatted strings.\n-   Times are saved as `hh:mm:ss` formatted strings.\n-   Cryptocurrency prices are fetched using the [Binance HTTP ticker price](https://github.com/binance/binance-spot-api-docs/blob/master/rest-api.md#symbol-price-ticker) API.\n-   Fiat currency exchange rates are fetched using the [Open Exchange Rates](https://openexchangerates.org/) API.\n-   By default valuations are printed in a human-friendly text format; use the `-format` option to print in JSON or YAML formats.\n-   Currency values in JSON and YAML formats are always in USD.\n\n-   The `-portfolio` option can be specified multiple times.\n-   The `-price` option allows the user to override current asset prices in order to evaluate \"what if\" scenarios. Example:\n\n        cryptor valuate -price btc=50000    # Price Bitcoin at $50,000 USD\n\n-   The `-price` option can be specified multiple times.\n-   The `-price` option could be used to include non-crypto assets, e.g. gold, in the portfolios.\n\n-   Cryptor processes the following configuration, cache, and data files:\n\n    -   `$HOME/.config/cryptor/config.yaml`: YAML formatted cryptor options\n    -   `$HOME/.config/cryptor/portfolios.yaml`: YAML formatted portfolios\n    -   `$HOME/.cache/cryptor/exchange-rates.json`: JSON formatted cached fiat currency exchange rates\n    -   `$HOME/.local/share/data/cryptor/valuations.json`: JSON formatted valuations\n\n-   Default locations for configuration, cache, and data files conform to the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/latest/).\n-   An alternate single directory for all files can be specified using the `-confdir` command option.\n-   Use the `-confdir` option if you want to separate portfolios or groups of portfolios.\n\n## Portfolios Configuration File\n\nAsset portfolios are specified the [YAML](https://yaml.org/) formatted `portfolios.yaml` file in `$HOME/.config/cryptor/`). There are two portfolio file formats:\n\n### Single-portfolio assets-only format\nContains a list of assets, one asset per line formatted like `\u003csymbol\u003e: \u003camount\u003e`.\nFor example:\n\n```yaml\nBTC: 0.5\nETH: 2.5\nUSDT: 100\n```\n\n### Multi-portfolio format\nContains one or more portfolios each containing a list of assets along with optional portfolio name, notes and cost.\n\n-   Portfolio names are unique and can only contain alphanumeric characters, underscores and dashes; the name `aggregate` is reserved.\n-   If you specify a portfolio's `cost` amount (the total amount paid for the portfolio assets) then portfolio gains (or losses) are calculated.\n-   The portfolio `cost` value is formatted like `\u003camount\u003e\u003csymbol\u003e`. The amount is mandatory; the currency symbol is optional and defaults to `USD`; dollar, comma and space characters are ignored; case insensitive. Examples:\n\n        $5,000.00 NZD     # Five thousand New Zealand dollars.\n        1000aud           # One thousand Australian dollars.\n        .5                # Fifty cents USD.\n\nExample multi-portfolios configuration file containing two portfolios:\n\n```yaml\n- name: personal\n  notes: Personal portfolio notes.\n  cost: $10,000.00 USD\n  assets:\n      BTC: 0.5\n      ETH: 2.5\n      USDT: 100\n\n- name: business\n  notes: |\n      Business portfolio notes\n      over multiple lines.\n  cost: $20,000.00 USD\n  assets:\n      BTC: 1.0\n```\n\n## Valuations\n\n-   If the `-save` option is specified the `valuate` command appends portfolio valuations to the `valuations.json` file located in the data configuration directory.\n-   The `valuate` command prints and saves valuations in the same order that they occur in the portfolios configuration file.\n-   The printed output can be customised using the `-portfolio`, `-aggregate` and `-aggregate-only` options.\n-   The aggregate valuation is appended after the portfolio valuations with the portfolio name `aggregate`.\n-   Saved valuations always include all portfolio valuations plus the aggregate valuation.\n-   The `aggregate` portfolio is the aggregate of all portfolios, not just those specified by `-portfolio` options.\n-   The `-portfolio`, `-aggregate` and `-aggregate-only` options apply to printed outputs.\n\n## Post-processing Valuation Data\n\nThe [jq](https://github.com/jqlang/jq) command is useful for munging and extracting valuation data:\n\n-   The following command pipes JSON output from the `valuate` command through a `jq` filter transforms it into CSV asset records:\n\n          cryptor valuate -format json | jq -r '.[] | . as $p | .assets[] | [$p.name, $p.date,$p.time,.symbol,.amount,.value,.allocation] | @csv'\n\n-   This command lists all saved portfolio valuations, includes a CSV header, and rounds numbers to two decimal places:\n\n          cryptor history | jq -r '[\"NAME\",\"DATE\",\"TIME\",\"VALUE\",\"ROI\"], (.[] | select(.cost\u003e0) | [.name, .date, .time, (.value*100 | floor | ./100), ((.value-.cost)/.cost*100*100 | floor | ./100)]) | @csv'\n\n-   The next command pipes the saved `personal` portfolio valuations through a `jq` filter to generate per-day CSV ROI (return on investment) records by selecting the first portfolio record of the day:\n\n          cryptor history -portfolio personal | jq -r 'group_by(.date) | map(. | map(select(.cost \u003e 0)) | sort_by(.time) | first) | .[] | select(.) | [.name, .date, .value, (.value-.cost)/.cost*100] | @csv'\n\n## Plotting Portfolio Valuation Data\n\nThe cryptor repository includes an `examples` folder which contains bash scripts for plotting portfolio valuations. The scripts read the `cryptor` output on `stdin` and use [jq](https://stedolan.github.io/jq/) (to generate CSV plot data) and [gnuplot](http://www.gnuplot.info/) (to plot the CSV data).\n\n### Portfolio valuation pie chart\nThe bash script `examples/plot-valuation.sh` plots a `cryptor` valuation. For example:\n\n    cryptor valuate -portfolio personal -format json | examples/plot-valuation.sh\n\n![Portfolio valuation pie chart](valuation-plot.png)\n\n### Portfolio history chart\nThe bash script `examples/plot-history.sh` plots `cryptor` history data. For example:\n\n    cryptor history -portfolio personal | examples/plot-history.sh\n\n![Portfolio history chart](history-plot.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsrackham%2Fcryptor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsrackham%2Fcryptor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsrackham%2Fcryptor/lists"}