Cryptocurrency Tools

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`](https://www.ledger-cli.org/3.0/doc/ledger3.html). Also, read background articles ["Multiple Currencies with Currency Trading Accounts"](https://github.com/ledger/ledger/wiki/Multiple-currencies-with-currency-trading-accounts), and Peter Selinger's ["Tutorial on Multiple Currency Accounting"](https://www.mathstat.dal.ca/~selinger/accounting/tutorial.html). 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: Later, ABC trades at $1, and you sell some. In `ledger-cli`: 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: 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`, with the effects of `lotter`, Usage: 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_. Usage: 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`.