Forked from https://src.d10.dev/lotter
Original author also wrote a nice tutorial which can be found here: https://www.d10.dev/blog/ledger-cli-trade
Lotter is a command-line tool that works with trade data in ledger-cli
format. While ledger-cli
is a fantastic calculator for double-entry
accounting, its support for lots, cost basis, and gains is rather limited.
This tool is meant to provide a handful of features which (to the best of my
knowledge) ledger-cli
does not provide on its own.
To best understand lotter
, it is recommended to first be familiar with
ledger-cli
. Also, read
background articles "Multiple Currencies with Currency Trading
Accounts",
and Peter Selinger's "Tutorial on Multiple Currency
Accounting".
Use lotter
by first entering trade information into ledger-cli
. Run
lotter
to add "lot" information, which enables ledger-cli
to calculate
cost basis and gains.
Let's say you purchased a cryptocurrency (we'll call it ABC), when it cost 2
cents. A ledger-cli
entry could look like:
2016-01-01 Bought ABC
Assets:Crypto 100 ABC @ 0.02 USD
Equity:Cash
Later, ABC trades at $1, and you sell some. In ledger-cli
:
2017-01-01 Sell some ABC
Assets:Crypto -1 ABC @ 1 USD
Assets:Exchange
The idea of lotter
is to add "splits" to these ledger entries. The added
information captures the cost basis when a "lot" is created, and gains
(losses) when inventory from a lot is sold. After lotter
, the ledger
entris look roughly like:
2016-01-01 Bought ABC
Assets:Crypto 100 ABC ; @ 0.02 USD
Equity:Cash
[Lot::2016/01/01:100ABC@0.02USD] -100 ABC
[Lot::2016/01/01:100ABC@0.02USD] 2 USD
2017-01-01 Sell some ABC
Assets:Crypto -1 ABC ; @ 1 USD
Assets:Exchange
[Lot::2016/01/01:100ABC@0.02USD] 1 ABC
[Lot::2016/01/01:100ABC@0.02USD] -0.02 USD
[Lot:Income:long term gain] -0.98 USD
If your wondering why the last line ("long term gain") shows a negative
number, when the actual gain is a positive 98 cents, recall that in
ledger-cli
's double-entry method, income is expressed in negative numbers
while expenses are positive. Similarly in lotter
, lot inventory and gain
are negative numbers, cost basis is positive. This follows ledger-cli
's
rules, and makes lotter
's splits net zero.
The transactions described above are in testdata/simple.ledger
. To see the
effects of lotter
on these transactions, compare the normal use of
ledger-cli
,
ledger -f testdata/simple.ledger bal
with the effects of lotter
,
lotter -f testdata/simple.ledger lot | ledger -f - bal
usage: lotter -f <filename> lot
The lot
operation adds "splits" to transactions, representing lot
inventory, cost basis, and gains.
Each lot is a ledger-cli
"account", named by convention with prefix "Lot",
followed by the date the lot was created, and inventory and cost
information. This naming convention is intended to provide unique lot names.
(It could fail to do so, if multiple purchases occur on the same day, for
the same amount and cost.)
lotter
considers a transaction to be a purchase when it finds a split for
a positive amount, with cost information associated with it. When
constructing your ledger entries, use for example "100 ABC @ 0.02 USD" or
"100 ABC @@ 2 USD".
Similarly, lotter
considers a transaction to be a sale when the amount is
negative and has a cost associated. To these transactions, lotter
adds
splits that "consume" inventory (and basis) acquired earlier.
To see options available, run lotter help lot
.