slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

;doc:cctax: updates

Browse Source
This commit is contained in:
Simon Michael 2025-12-19 08:31:21 -10:00
parent fc34c76eda
commit 824d10b406
1 changed files with 36 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
examples/csv/cctax/README.md
View File

@ -1,10 +1,5 @@
## Cryptocurrency tax reporting
<div class=pagetoc>
<!-- toc -->
</div>
(This is the README in the hledger repo's `examples/csv/cctax/` directory,
also published as the [Cryptocurrency tax reporting] page on hledger.org.)
<!-- This page can be viewed on github or hledger.org, so use absolute urls -->
@ -12,27 +7,38 @@ also published as the [Cryptocurrency tax reporting] page on hledger.org.)
In this directory we are not concerned with importing to hledger,
but with exporting from hledger to cryptocurrency tax calculators.
The information here was last updated in 2025-12.
Why do this ? In most countries, the revenue and capital gain or loss incurred from
receiving/selling/trading cryptocurrencies is taxable and must be itemised and reported.
Why do this ?
In most countries, the revenue and capital gain from receiving/selling/trading cryptocurrencies (cc) is taxable and must be reported.
There are several aspects to this:
1. Calculating income.
2. Calculating capital gains.
3. Calculating actual taxes owed.
- Calculating income. This is easy - at least, once you have recorded all transactions in hledger.
- Calculating capital gains. This can be hard, and depends on your country's rules.
- Calculating taxes owed. This also depends on your country's rules, and is often handled by specialised tax preparation software.
1 (income) is relatively easy to do with hledger.
3 (tax owed) requires knowledge of current tax rules and is often handled by specialised tax preparation software.
2 (gains) can be complex. Depending on your country's tax rules, it may require
- tracking the original cost, date, and wallet of every purchase/acquisition over your lifetime
Centralised exchanges will calculate gains for you, but self-custodied wallets, decentralised exchanges, or other defi apps won't;
with those, you are responsible for calculating gains.
In some countries, such as the USA, this requires:
- tracking the acquisition date, cost, and wallet of every purchase/acquisition over your lifetime
- tracking their movements/splits/merges
- selling/disposing them in a precise mandated order
- disposing (selling/spending) them in a required order, such as:
- FIFO - first in first out
- LIFO - last in first out
- HIFO - highest cost first out
- LOFO - lowest cost first out
- SpecId - specific identification of lots
- and thereby calculating the capital gains or losses.
Centralised exchanges will calculate gains for you,
but self-custodied wallets, decentralised exchanges, or other defi apps won't;
there you are responsible for calculating gains.
There are several ways you could tackle this:
In the US, before 2025 universal cost tracking was used to determine the disposal order;
this means you consider the acquisition costs/dates of all your holdings of an asset (cryptocurrency), across all wallets.
From tax year 2025, per-wallet cost tracking is required, which means you apply the disposal order separately within each wallet.
The "Safe Harbor" rule allows you to allocate pre-2025 lots to specific wallets (once), which could help optimise taxes in some cases.
In the UK, it's easier: you use each asset's average cost across all wallets.
There are several ways you could calculate gains. Eg, assuming the worst case (US taxes), you could:
1. Calculate gains using only hledger,
by keeping track of each lot and lot movement with subaccounts,
@ -41,6 +47,7 @@ There are several ways you could tackle this:
2. Calculate gains using the built-in lot tracking syntax of Ledger or Beancount. Beancount's is more robust.
These may be too limited to calculate gains accurately, eg when there are inter-wallet transfers.
There may be additional plugins which help.
3. Online cryptocurrency tax calculators (Bitcoin.Tax, Cointracker, Coinledger, Koinly, Summ, TokenTax..)
These let you upload transaction history from all of your cryptocurrency activities.
@ -49,15 +56,15 @@ There are several ways you could tackle this:
When they are hacked or infiltrated, potentially your entire past, present and future cryptocurrency activities can be analysed.
4. Offline cryptocurrency tax calculators. These tend to be more private.
- rotki - AGPL/freemium, featureful, does not support US yet (wallet-based cost tracking, https://github.com/rotki/rotki/issues/2438)
- RP2 - Apache, does not support US yet (https://github.com/eprbell/rp2/issues/135)
- BittyTax - AGPL, UK and US variants (can do wallet-based cost tracking by using multiple configs)
- [rotki] - freemium, featureful, does not support US yet (wallet-based cost tracking, <https://github.com/rotki/rotki/issues/2438>)
- [RP2] - does not support US yet (<https://github.com/eprbell/rp2/issues/135>)
- [BittyTax] - UK and US variants (can do wallet-based cost tracking by using multiple configs)
So the main focus here is exporting to offline tools.
These require CSV data in a specific format; examples are collected here.
Each record represents an event in a particular cryptocurrency wallet.
[rotki]: http://rotki.com
[rp2]: https://github.com/eprbell/rp2
[bittytax]: https://github.com/BittyTax/BittyTax
The main focus in this directory is exporting to offline calculators.
Examples of their CSV import format are collected here.
Each record represents an event in a particular cryptocurrency "wallet" (on an exchange or on a blockchain).
There are basic events like deposit, withdrawal, buy, sell, expense, income; and some more specialised event types.
These tools usually provide general gains reports, which you must interpret or adjust according to your country's tax rules.
In the US, universal cost tracking was used through 2024; from tax year 2025, per-wallet cost tracking is required.
The "Safe Harbor" rule allows you to allocate pre-2025 lots to specific wallets (once), which could help optimise taxes in some cases.