hledger-stockquotes

Generate HLedger Price Directives From Daily Stock Quotes.

https://github.com/prikhi/hledger-stockquotes#readme

LTS Haskell 23.27:0.1.3.2
Stackage Nightly 2025-07-13:0.1.3.2
Latest on Hackage:0.1.3.2

See all snapshotshledger-stockquotes appears in

BSD-3-Clause licensedbyPavan Rikhi
Maintained by[email protected]
This version can be pinned in stack with:hledger-stockquotes-0.1.3.2@sha256:58f8f3c6cbb9f9fea8f30c1ea286787fab0c0f76ea9f3b5bca13ac32ed27b986,3255

Module documentation for 0.1.3.2

Used by 1 package inlts-23.17(full list with versions):

hledger-stockquotes

hledger-stockquotes Build Status

hledger-stockquotes is a CLI addon forhledger thatreads a journal file and pulls the historical prices for commodities fromAlphaVantage. To use this application, you’llneed afree AlphaVantage API key.

Usage

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

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

At the bare minimum, you need to set anALPHAVANTAGE_KEY environmentalvariable 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 aprices.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 alreadyexists!

Excluding Commodities

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

hledger-stockquotes -a MY_API_KEY AUTO TA_VFFVX

NOTE: hledger defines anAUTO commodity if you use the default commoditydirective(D).

Cryptocurrencies

You can specify a list of cryptocurrencies that you wish to pull prices forwith the-c or--crypto flag. You can pass a comma-separated list ofcurrencies or pass the flag multiple times. We will split the commodities fromyour journal file into a list of equities & cryptocurrencies and hit theappropriate 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 runwill fetch 5 price histories, wait 60 seconds, fetch 5 more, etc. Runningmultiplehledger-stockquotes commands in sequence will not enforce this limitover multiple runs and may result in API errors. You can ignore the requestlimiting with the-n flag. To test a command without hitting the API, passthe--dry-run flag. This will simply print out the commodities and dateranges 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 isusually~/.config/).

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

rate-limit: falseapi-key: DeAdBeEf9001cryptocurrencies:    - BTC    - XMRexclude:    - USD    - AUTOcommodity-aliases:    MY_BTC_CURRENCY: BTC    401K_VTSAX: VTSAX

CLI flags & environmental variables will override config file settings.

Aliases

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

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

commodity-aliases:    MY_VTSAX: VTSAX    MY_BTC_CURRENCY: BTC

Renaming is done after commodity exclusion, but before bucketing them intoequities & cryptocurrencies so theexclude list should use your symbols whilethecryptocurrencies list should use AlphaVantage’s:

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

Specifying aliases via command line options or environmental variableis 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, soyou’ll have to clone this repository & compile/install the code yourself:

git clone https://github.com/prikhi/hledger-stockquotes.gitcd hledger-stockquotesstack install

This will put thehledger-stockquotes exe into your~/.local/bin/directory. Ensure that the directory is included in yourPATH environmentalvariable. Then you can run the application:

hledger-stockquotes --help

Since the executable has thehledger- prefix, you can also use it with thehledger 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, runstack haddock --open hledger-stockquotes

To install the executable to~/.local/bin, runstack install.

LICENSE

BSD-3

Changes

CHANGELOG

master

v0.1.3.2

  • Support breaking changes inhledger-lib v1.41.

v0.1.3.1

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

v0.1.3.0

  • ChangePrices volume field fromInteger toScientific to supportdecimal amounts returned by cryptocurrency routes.
  • AlphaVantage changed the information message field fromNote toInformation so we now attempt to parse both and throw anApiError ifeither exist. This usually occurs when you’ve run out of API calls for theday.
  • AlphaVantage changed theDIGITAL_CURRENCY_DAILY endpoint to return the sameprice fields as theTIME_SERIES_DAILY endpoint, so we dropped theCryptoPrices type and return thePrices type from both the stock & cryptoAPI calls.
  • AlphaVantage has swapped premium-only endpoints on us again - nowTIME_SERIES_DAILY is free andTIME_SERIES_DAILY_ADJUSTED is paid-only sowe had to switch back.

v0.1.2.2

  • Switch from the (now premium-only)TIME_SERIES_DAILY AlphaVantage endpointto the freeTIME_SERIES_DAILY_ADJUSTED endpoint.
  • Bump package dependencies.

v0.1.2.1

  • Fix breaking changes inhledger-lib v1.26.

v0.1.2.0

  • Add support for fetching cryptocurrency prices with the-c flag andcryptocurrencies config option.
  • Add support for config file at$XDG_CONFIG_HOME/hstockquotes/config.yamlwithapi-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 tostderr instead ofstdout.
  • Improve error messages when the AlphaVantage API returns arate-limit-exceeded error.
  • Improve documentation in README &--help flag.
  • Add trailing newline to generated files.

v0.1.0.0

  • Initial release