src.d10.dev/lotter

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 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.

Simple Example

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 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 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

Operation base

Usage:

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.

Operation lot

Usage:

lotter [-base <currency>] -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.