hledger-stockquotes
Generate HLedger Price Directives From Daily Stock Quotes.
https://github.com/prikhi/hledger-stockquotes#readme
LTS Haskell 22.37: | 0.1.3.1 |
Stackage Nightly 2024-10-11: | 0.1.3.1 |
Latest on Hackage: | 0.1.3.1 |
hledger-stockquotes-0.1.3.1@sha256:d9d9584c997f3a819b7468ef4edcc8cdc5fa338fea77173c8e6d59fedee5964d,3222
Module documentation for 0.1.3.1
- Hledger
- Web
hledger-stockquotes
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 fromInteger
toScientific
to support decimal amounts returned by cryptocurrency routes. - AlphaVantage changed the information message field from
Note
toInformation
so we now attempt to parse both and throw anApiError
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 theTIME_SERIES_DAILY
endpoint, so we dropped theCryptoPrices
type and return thePrices
type from both the stock & crypto API calls. - AlphaVantage has swapped premium-only endpoints on us again - now
TIME_SERIES_DAILY
is free andTIME_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 freeTIME_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 andcryptocurrencies
config option. - Add support for config file at
$XDG_CONFIG_HOME/hstockquotes/config.yaml
withapi-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 ofstdout
. - 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