HackMDUsing Beancount to Record your Bitcoin Holdings
Blockchain Commons' beancounter.py is a Python program that interacts with a SpotBit server to help you to log the purchase, sales, and other transfers of Bitcoin.
Why Beancounting Your Bitcoin is Crucial (in the US)
WARNING: Please do not consider this overview to be specific tax information; you should consultant with an accountant specialized in taxes and cryptocurrency if you are unsure of how to deal with your own Bitcoin holdings.
Bitcoin is treated as property, not a currency in the United States. Think of it like stock. That typically means that when you buy and then sell Bitcoin, it generates a taxable event, resulting in capital gains taxes (or else a capital loss that can be applied to other gains).
That means that for purchase and sales of Bitcoin you need to carefully account for lots, knowing what was purchased, when it was sold, what the holding period was, and what the profit (or loss) was on that sales. Beancount can help you with accounting of this sort.
But, Bitcoin is even more complex than that because it is a currency, despite the United States' decision not to treat it as such for financial purposes. That means that you must not just report capital gains and losses when you sell Bitcoin, but also when you use it as currency, to buy other equities or even to pay someone for services! For this you need not just a beancount record of when Bitcoin was purchased, and then when it was used, but also knowledge of what the value of Bitcoin was when you made the later usage.
That's where beancounter.py comes in: it looks up all the transactions for a descriptor-based wallet and then it uses a SpotBit server to determine the value of Bitcoin when it was used, providing vital information for your accountant (or when you do your own taxes).
How to Setup Beancounter.py
The beancounter.py program is currently a part of the SpotBit repo. To access it requires cloning or otherwise downloading the repo.
(The following setup instructions show the process for a MacOS computer. Setting up beancounter.py on a Linux machine would be very similar.)
To start with, clone the repo:
(If you prefer, you can download a ZIP file from GitHub and unzip it.)
You must have Python 3.10 installed. If you do not already, it can be installed with Brew:
If you do not have HomeBrew for your Mac, you should install it, as it's a crucial package manager for acess programs like Python.
If you have a previous version of Python, you will need to uninstall it to ensure you are accessing Python 3.10.
When you're done, you can verify you are using the correct Python as follows:
You're now ready to finalize your SpotBit (and thus beancounter.py) setup.
First setup & use a virtual environment:
Then, install dependencies:
Your beancounter.py (and for that matter, SpotBit server) is now ready to go.
Running Beancounter
The beancounter.py program requires two arguments:
- A Spotbit server
- A descriptor for the account you will be accounting
It's run with those two arguments and with an optional --network argument.
The following example shows its use with a wallet containing a few small transactions, run against Blockchain Commons' main Spotbit server:
If the descriptor has an invalid checksum, beancounter.py will attempt to use the descriptor without the checksum. You will see this message:
Afterward, look for a new .bean file, which will contain the Beancount information generated from your wallet. Each Beancount file will have a unique file name:
If a file isn't generated yet no error is reported, try re-running the above python beancounter.py command with the --verbose flag which will generate detailed output that can be used when diagnosing/reporting the problem.
Running Your Own SpotBit Server
If you prefer to keep your price lookups off of the internet, you can instead run your own Spotbit server, and then do lookups there:
You can then run beancounter.py using that local server.
Reviewing Your Beancount File
After you have run beancounter.py, you should have a Beancount file that shows all your transactions related to the wallet:
[[TODO: Doublecheck this file still looks the same after next revisions]]
Critically, it shows not just Bitcoin transanctions, but also USD valuations, which will be crucial for tax purposes!
Using Your Beancount File
If you haven't already, you should at this point install beancount:
[TODO: bean-check currently shows an error]
[[There are also discrepancies in the balance:]]
[[SPARROW RESULTS A BALANCE OF 25,222 satoshis, worth $5.10 on this account]] [TODO: WRITE ABOUT HOW TO USE WHEN THESE ISSUES ARE RESOLVED.]
