From 824d10b40640bfeaa13101cf8faeb2e203c65be0 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Fri, 19 Dec 2025 08:31:21 -1000 Subject: [PATCH] ;doc:cctax: updates --- examples/csv/cctax/README.md | 65 ++++++++++++++++++++---------------- 1 file changed, 36 insertions(+), 29 deletions(-) diff --git a/examples/csv/cctax/README.md b/examples/csv/cctax/README.md index 457384571..d11d9786b 100644 --- a/examples/csv/cctax/README.md +++ b/examples/csv/cctax/README.md @@ -1,10 +1,5 @@ ## Cryptocurrency tax reporting -
- - -
- (This is the README in the hledger repo's `examples/csv/cctax/` directory, also published as the [Cryptocurrency tax reporting] page on hledger.org.) @@ -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, ) + - [RP2] - does not support US yet () + - [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.