BSD-3-Clause licensed by Pavan Rikhi
Maintained by [email protected]
This version can be pinned in stack with:hledger-stockquotes-0.1.3.1@sha256:d9d9584c997f3a819b7468ef4edcc8cdc5fa338fea77173c8e6d59fedee5964d,3222

Module documentation for 0.1.3.1

hledger-stockquotes

hledger-stockquotes Build Status

hledger-stockquotes is a CLI addon for hledger that reads a journal file and pulls the historical prices for commodities from AlphaVantage. To use this application, you’ll need a free AlphaVantage API key.

Usage

hledger-stockquotes parses your journal file, determines what commodities are defined, and queries AlphaVantage for prices on the date range present in the journal file.

By default, the program will use the HLedger default file location of ~/.hledger.journal. A LEDGER_FILE environmental variable can be used to override the location. The -f flag can be used to override both the default and LEDGER_FILE locations.

At the bare minimum, you need to set an ALPHAVANTAGE_KEY environmental variable or use the -a switch to specify your AlphaVantage key:

hledger-stockquotes -a MY_API_KEY -f accounting.journal

This will print out price directive to a prices.journal file.

Custom Output Files

The output file can be set with the -o flag:

hledger-stockquotes -a MY_API_KEY -o prices/2021.journal

NOTE: the contents of the output file will be overwritten if the file already exists!

Excluding Commodities

By default, we query AlphaVantage for all non-USD commodities included in your journal file. We do not currently support AlphaVantage’s FOREX API route, so if you have those commodities, stockquotes will print an error when fetching them. You can exclude commodities by passing them as arguments to hledger-stockquotes:

hledger-stockquotes -a MY_API_KEY AUTO TA_VFFVX

NOTE: hledger defines an AUTO commodity if you use the default commodity directive(D).

Cryptocurrencies

You can specify a list of cryptocurrencies that you wish to pull prices for with the -c or --crypto flag. You can pass a comma-separated list of currencies or pass the flag multiple times. We will split the commodities from your journal file into a list of equities & cryptocurrencies and hit the appropriate AlphaVantage route for each.

hledger-stockquotes -a MY_API_KEY -c BTC,ETH --crypto XMR -c BNB

API Limits

AlphaVantage has an API request limit of 5 requests per minute. hledger-stockquotes enforces this limit on a per-command basis. A single run will fetch 5 price histories, wait 60 seconds, fetch 5 more, etc. Running multiple hledger-stockquotes commands in sequence will not enforce this limit over multiple runs and may result in API errors. You can ignore the request limiting with the -n flag. To test a command without hitting the API, pass the --dry-run flag. This will simply print out the commodities and date ranges that would be queried instead of making requests to AlphaVantage.

Configuration File

hledger-stockquotes can also be configured via a YAML file at $XDG_CONFIG_HOME/hledger-stockquotes/config.yaml($XDG_CONFIG_HOME is usually ~/.config/).

You can set the api-key, rate-limit, cryptocurrencies, exclude, & commodity-aliases options via this file:

rate-limit: false
api-key: DeAdBeEf9001
cryptocurrencies:
    - BTC
    - XMR
exclude:
    - USD
    - AUTO
commodity-aliases:
    MY_BTC_CURRENCY: BTC
    401K_VTSAX: VTSAX

CLI flags & environmental variables will override config file settings.

Aliases

By specifying the commedity-aliases option in your configuration file, you can rename the commodities used in your journal to the commodities expected by AlphaVantage.

Keys in the map should be your journal commities while their values are the AlphaVantage ticker symbols:

commodity-aliases:
    MY_VTSAX: VTSAX
    MY_BTC_CURRENCY: BTC

Renaming is done after commodity exclusion, but before bucketing them into equities & cryptocurrencies so the exclude list should use your symbols while the cryptocurrencies list should use AlphaVantage’s:

journal -> exclude -> commodity-aliases -> cryptocurrencies

Specifying aliases via command line options or environmental variable is not currently supported.

Additional Documentation

The --help flag provides more thorough documentation on all available flags:

hledger-stockquotes --help

Build / Install

This project has not yet been packaged for any OSes or Linux distributions, so you’ll have to clone this repository & compile/install the code yourself:

git clone https://github.com/prikhi/hledger-stockquotes.git
cd hledger-stockquotes
stack install

This will put the hledger-stockquotes exe into your ~/.local/bin/ directory. Ensure that the directory is included in your PATH environmental variable. Then you can run the application:

hledger-stockquotes --help

Since the executable has the hledger- prefix, you can also use it with the hledger command:

hledger stockquotes -- --help

Development/Manual Builds

You can build the project with stack: stack build

For development, you can enable fast builds with file-watching, documentation-building, & test-running: stack test --haddock --fast --file-watch

To build & open the documentation, run stack haddock --open hledger-stockquotes

To install the executable to ~/.local/bin, run stack install.

LICENSE

BSD-3

Changes

CHANGELOG

master

v0.1.3.1

  • AlphaVantage changed the message field for API errors to Error Message so we now try to parse this field out of the response as well.

v0.1.3.0

  • Change Prices volume field from Integer to Scientific to support decimal amounts returned by cryptocurrency routes.
  • AlphaVantage changed the information message field from Note to Information so we now attempt to parse both and throw an ApiError if either exist. This usually occurs when you’ve run out of API calls for the day.
  • AlphaVantage changed the DIGITAL_CURRENCY_DAILY endpoint to return the same price fields as the TIME_SERIES_DAILY endpoint, so we dropped the CryptoPrices type and return the Prices type from both the stock & crypto API calls.
  • AlphaVantage has swapped premium-only endpoints on us again - now TIME_SERIES_DAILY is free and TIME_SERIES_DAILY_ADJUSTED is paid-only so we had to switch back.

v0.1.2.2

  • Switch from the (now premium-only) TIME_SERIES_DAILY AlphaVantage endpoint to the free TIME_SERIES_DAILY_ADJUSTED endpoint.
  • Bump package dependencies.

v0.1.2.1

  • Fix breaking changes in hledger-lib v1.26.

v0.1.2.0

  • Add support for fetching cryptocurrency prices with the -c flag and cryptocurrencies config option.
  • Add support for config file at $XDG_CONFIG_HOME/hstockquotes/config.yaml with api-key, exclude, & rate-limit options.

v0.1.1.0

  • Don’t write out a journal file if no prices were successfully fetched.
  • Log API errors to stderr instead of stdout.
  • Improve error messages when the AlphaVantage API returns a rate-limit-exceeded error.
  • Improve documentation in README & --help flag.
  • Add trailing newline to generated files.

v0.1.0.0

  • Initial release