beanprice: Price quotes fetcher for Beancount

Description

A script to fetch market data prices from various sources on the internet and render them for plain text accounting price syntax (and Beancount).

This used to be located within Beancount itself (at v2) under beancount.prices. This repo will contain all future updates to that script and to those price sources.

Changelog

• v2.1.1: All source files are merged into a single ledger before price jobs are generated, fixing duplicate jobs and cross-file commodity directive visibility
• Streaming output writes each fetched entry immediately, so interrupted runs keep already-written results
• --update-fill-gaps can backfill missing dates across the full lifetime of each commodity
• A Financial Times price source is available
• Cache-skip handling avoids re-fetching missing or clobbered price data

Documentation

Some documentation is still part of Beancount. More about how to use this can be found on that mailing-list. Otherwise read the source.

Quick start

To install beanprice, run:

pip install git+https://github.com/beancount/beanprice.git

You can fetch the latest price of a stock by running:

bean-price -e 'USD:yahoo/AAPL'

To fetch the latest prices from your beancount file, first ensure that commodities have price metadata, e.g.

2000-01-01 commodity AAPL
  price: "USD:yahoo/AAPL"

Then run:

bean-price ledger.beancount

To update prices up to the present day, run:

bean-price --update ledger.beancount

Appending new prices to a file

Output is streamed to stdout one entry per fetch, so it is safe to append directly — already-written entries survive an interrupted run:

bean-price --update ledger.beancount >> prices.beancount

After multiple runs, deduplicate and sort the file in-place:

sort -u -o prices.beancount prices.beancount

Backfilling gaps in price history

By default --update only fetches prices forward from the latest recorded date. Use --update-fill-gaps to also fetch any missing dates within the full lifetime of each commodity:

bean-price --update --update-fill-gaps ledger.beancount >> prices.beancount
sort -u -o prices.beancount prices.beancount

This is useful when:

• previous runs were interrupted and left holes in the history
• a commodity was added retrospectively with an early start date
• the ledger was imported from another tool with sparse price data

For more detailed guide for price fetching, read https://beancount.github.io/docs/fetching_prices_in_beancount.html.

Price source info

The following price sources are available:

Name	Module	Provides prices for	Base currency	Latest price?	Historical price?
Alphavantage	beanprice.alphavantage	Stocks, FX, Crypto	Many currencies	✓	✕
Coinbase	beanprice.coinbase	Most common (crypto)currencies	Many currencies	✓	✓
Coincap	beanprice.coincap	Most common (crypto)currencies	USD	✓	✓
Coinmarketcap	beanprice.coinmarketcap	Most common (crypto)currencies	Many Currencies	✓	✕
European Central Bank API	beanprice.ecbrates	Many currencies	Many currencies (Derived from EUR rates)	✓	✓
Financial Times	beanprice.ft	Stocks	Many currencies	✓	✓
OANDA	beanprice.oanda	Many currencies	Many currencies	✓	✓
Quandl	beanprice.quandl	Various datasets	Various datasets	✓	✓
Rates API	beanprice.ratesapi	Many currencies	Many currencies	✓	✓
Thrift Savings Plan	beanprice.tsp	TSP Funds	USD	✓	✓
Yahoo	beanprice.yahoo	Many currencies	Many currencies	✓	✓
EastMoneyFund(天天基金)	beanprice.eastmoneyfund	Chinese Funds	CNY	✓	✓

More price sources can be found at awesome-beancount.com website.

Creating a custom price source

To create a price source, create a package (i.e. my_package) with a module (i.e. my_module) that contains the Source class which inherits from the beanprice.Source class:

from beanprice import source

class Source(source.Source):
  def get_latest_price(self, ticker) -> source.SourcePrice | None:
    pass

  def get_historical_price(self, ticker, time):
    pass

Implement the logic for fetching the prices. At a minimum, the get_latest_price() is required.

Then use your price source in the commodities

1900-01-01 commodity XYZ
  price: "AUD:my_package.my_module/XYZ"

AUD just being an example of a currency specification.

Testing

Run tests:

pytest beanprice

Lint:

pylint beanprice

Type checker:

mypy beanprice

Copyright and License

Copyright (C) 2026 Roman Medvedev Copyright (C) 2007-2020 Martin Blais. All Rights Reserved.

This code is distributed under the terms of the "GNU GPLv2 only". See COPYING file for details.