Lotter is a command-line tool that works with trade data in
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 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
and Peter Selinger's "Tutorial on Multiple Currency
lotter by first entering trade information into
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
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
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
entries look like:
2016-01-01 Bought ABC Assets:Crypto 100 ABC ; @ 0.02 USD Equity:Cash [Lot::2016/01/01:100ABC@0.02USD] -100 ABC ; :BUY: (inventory) [Lot::2016/01/01:100ABC@0.02USD] 2 USD ; :BUY: (basis) 2017-01-01 Sell some ABC Assets:Crypto -1 ABC ; @ 1 USD Assets:Exchange [Lot::2016/01/01:100ABC@0.02USD] 1 ABC ; :SELL: (inventory consumed) [Lot::2016/01/01:100ABC@0.02USD] -0.02 USD ; :SELL: (basis consumed) [Lot:Income:long term gain] -0.98 USD ; :GAIN:LONGTERM:
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
rules, and makes
lotter's splits net zero.
The transactions described above are in
testdata/simple.ledger. To see the
lotter on these transactions, compare the normal use of
ledger -f testdata/simple.ledger bal
with the effects of
lotter -f testdata/simple.ledger lot | ledger -f - bal
lotter [-base <currency>] -f <filename> base
The base operation modifies transaction splits, converting costs and amounts into the base currency. This is intended to be a pre-processor for the lot operation, allowing trades to be accounted for in terms of the base currency, even when the trades are for other currencies.
This operation observes prices in the ledger file. When a split has a cost expressed in a currency other than base, and a price conversion to base is available on the same day as the transaction, this operation rewrites the transaction splits converting the original cost currency into the base.
lotter [-base <currency>] -f <filename> lot
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".
lotter considers a transaction to be a sale when the amount is
negative and has a cost associated. To these transactions,
splits that "consume" inventory (and basis) acquired earlier.
To see options available, run
lotter help lot.