;examples: csv/cctax: notes on exporting to cryptocurrency tax calculators

bin/README.md

@@ -7,8 +7,8 @@
 
 (This is the README in the hledger repo's `bin/` directory,
 also published as the [Scripts and add-ons] page on hledger.org.)
-
 <!-- This page can be viewed on github or hledger.org, so use absolute urls here: -->
+
 [Scripts and add-ons]: https://hledger.org/scripts.html
 [Scripting hledger]:   https://hledger.org/scripting.html
 [bin]:                 https://github.com/simonmichael/hledger/tree/master/bin

examples/csv/cctax/README.md

@@ -0,0 +1,63 @@
+## 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 -->
+[Cryptocurrency tax reporting]: https://hledger.org/cctax.html
+
+In this directory we are not concerned with importing to hledger,
+but with exporting from hledger to cryptocurrency tax calculators.
+
+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.
+There are several aspects to this:
+
+1. Calculating income.
+2. Calculating capital gains. 
+3. Calculating actual taxes owed.
+
+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
+- tracking their movements/splits/merges
+- selling/disposing them in a precise mandated order
+- 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:
+
+1. Calculate gains using only hledger,
+   by keeping track of each lot and lot movement with subaccounts,
+   and selecting the appropriate lots/costs in disposal transactions.
+   This is intuitive and robust. But also tedious, and above a certain level of activity it becomes unmanageable.
+
+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.
+
+3. Online cryptocurrency tax calculators (Bitcoin.Tax, Cointracker, Coinledger, Koinly, Summ, TokenTax..)
+   These let you upload transaction history from all of your cryptocurrency activities.
+   Then they analyse this data, identify what happened (you may need to add configuration here), and provide gains reports.
+   These apps are convenient and featureful, eg they may understand your country's tax rules; but they also add rather serious privacy risk.
+   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)
+
+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.
+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.

examples/csv/cctax/bittytax/README.md

@@ -0,0 +1,2 @@
+https://github.com/BittyTax/BittyTax UK version
+https://github.com/BittyTax/BittyTax/wiki/USA US version

examples/csv/cctax/bittytax/_BittyTax-example.csv

@@ -0,0 +1,61 @@
+Type,Buy Quantity,Buy Asset,Buy Value in GBP,Sell Quantity,Sell Asset,Sell Value in GBP,Fee Quantity,Fee Asset,Fee Value in GBP,Wallet,Timestamp,Note
+Deposit,870,GBP,,,,,,,,LocalBitcoins,2013-05-24 20:16:46,from Bank
+Trade,10,BTC,,870,GBP,,,,,LocalBitcoins,2013-05-24 20:17:40,
+Withdrawal,,,,10,BTC,,,,,LocalBitcoins,2013-05-24 20:20:49,to Desktop wallet
+Deposit,10,BTC,,,,,,,,Desktop wallet,2013-05-24 20:20:49,from LocalBitcoins
+Deposit,2693.8,USD,,,,,,,,Bitstamp,2014-05-29 08:33:00,from Bank
+Spend,,,,0.002435,BTC,0.80,,,,Desktop wallet,2014-06-26 11:25:02,
+Gift-Sent,,,,0.02757,BTC,,,,,Desktop wallet,2014-07-18 13:12:47,
+Trade,0.41525742,BTC,,257.53,USD,,1.29,USD,,Bitstamp,2014-07-23 10:58:00,
+Trade,0.58474258,BTC,,362.63,USD,,1.82,USD,,Bitstamp,2014-07-23 10:58:00,
+Trade,0.86,BTC,,521.16,USD,,2.51,USD,,Bitstamp,2014-07-24 13:08:00,
+Trade,0.9,BTC,,545.7,USD,,2.51,USD,,Bitstamp,2014-07-24 13:08:00,
+Trade,1.64037953,BTC,,994.07,USD,,4.58,USD,,Bitstamp,2014-07-24 13:09:00,
+Withdrawal,,,,4.40027953,BTC,,0.0001,BTC,,Bitstamp,2014-07-24 21:01:00,to Desktop wallet
+Deposit,4.40027953,BTC,,,,,,,,Desktop wallet,2014-07-24 21:53:37,from Bitstamp
+Income,3,BTC,450.00,,,,,,,Desktop wallet,2015-05-22 10:34:18,
+Withdrawal,,,,6,BTC,,0.0001259,BTC,,Desktop wallet,2016-01-27 21:01:03,from Poloniex
+Deposit,6,BTC,,,,,,,,Poloniex,2016-01-27 21:15:41,to Desktop wallet
+Trade,77.41195874,ETH,,0.48789661,BTC,,0.15482391,ETH,,Poloniex,2016-01-27 22:04:21,
+Trade,366.5243149,ETH,,2.30979957,BTC,,0.73304862,ETH,,Poloniex,2016-01-27 22:04:21,
+Trade,70,ETH,,0.44058,BTC,,0.14,ETH,,Poloniex,2016-01-27 22:04:21,
+Trade,329.9038463,ETH,,2.07925198,BTC,,0.65980769,ETH,,Poloniex,2016-01-27 22:05:12,
+Trade,0.85909824,ETH,,0.00541455,BTC,,0.00171819,ETH,,Poloniex,2016-01-27 22:09:19,
+Trade,0.01202613,BTC,,1.81296224,ETH,,0.00002405,BTC,,Poloniex,2016-01-29 13:51:01,
+Trade,0.07591833,BTC,,11.44480809,ETH,,0.00015183,BTC,,Poloniex,2016-01-29 13:51:01,
+Trade,0.00000016,BTC,,0.00002554,ETH,,0,BTC,,Poloniex,2016-01-29 13:51:19,
+Trade,0.331671,BTC,,50.,ETH,,0.00066334,BTC,,Poloniex,2016-01-29 13:51:34,
+Trade,0.00000001,BTC,,0.00000292,ETH,,0,BTC,,Poloniex,2016-01-29 13:51:36,
+Trade,0.00601426,BTC,,0.90666181,ETH,,0.00001202,BTC,,Poloniex,2016-01-29 13:51:39,
+Trade,2.3987246,BTC,,361.6120503,ETH,,0.00479744,BTC,,Poloniex,2016-01-29 13:51:39,
+Trade,2.52372665,BTC,,385.8909256,ETH,,0.00504745,BTC,,Poloniex,2016-01-29 14:12:31,
+Trade,0.2049795,BTC,,31.34238327,ETH,,0.00040995,BTC,,Poloniex,2016-01-29 14:12:31,
+Withdrawal,,,,7,BTC,,0.0002,BTC,,Desktop wallet,2017-03-24 22:57:44,to Poloniex
+Deposit,7,BTC,,,,,,,,Poloniex,2017-03-24 22:57:44,from Desktop wallet
+Trade,1.00000013,ETH,,0.03729998,BTC,,0.0015,ETH,,Poloniex,2017-04-12 19:38:26,
+Trade,7.03854165,ETH,,0.26253746,BTC,,0.01759635,ETH,,Poloniex,2017-04-12 19:38:26,
+Trade,1.04194963,ETH,,0.03885951,BTC,,0.00260487,ETH,,Poloniex,2017-04-12 19:38:26,
+Trade,240.1501338,ETH,,8.95639684,BTC,,0.60037533,ETH,,Poloniex,2017-04-12 19:38:26,
+Income,1.0003,BTC,,,,,,,,Desktop wallet,2017-05-10 09:26:31,
+Gift-Received,0.24,BTC,,,,,,,,Desktop wallet,2017-08-08 13:21:29,
+Charity-Sent,,,,5,BTC,,,,,Desktop wallet,2017-08-08 18:37:20,
+Trade,102.423163,XRP,,0.00508223,BTC,,0.15363474,XRP,,Poloniex,2017-09-09 21:34:15,
+Trade,315.6206719,XRP,,0.01566109,BTC,,0.473431,XRP,,Poloniex,2017-09-09 21:34:41,
+Trade,0.36900443,XRP,,0.0000183,BTC,,0.0005535,XRP,,Poloniex,2017-09-09 21:34:47,
+Trade,0.07537283,XRP,,0.00000373,BTC,,0.00011305,XRP,,Poloniex,2017-09-09 21:34:52,
+Trade,12928.31362,XRP,,0.64150292,BTC,,19.39247042,XRP,,Poloniex,2017-09-09 21:38:08,
+Trade,6043.711874,XRP,,0.29988898,BTC,,9.06556781,XRP,,Poloniex,2017-09-09 21:38:09,
+Trade,0.06932688,XRP,,0.00000343,BTC,,0.00010399,XRP,,Poloniex,2017-09-09 21:38:27,
+Trade,6.87404272,XRP,,0.00034108,BTC,,0.01031106,XRP,,Poloniex,2017-09-09 21:38:27,
+Trade,708.641246,XRP,,0.03516277,BTC,,1.06296186,XRP,,Poloniex,2017-09-09 21:39:34,
+Trade,47.06572815,XRP,,0.0023354,BTC,,0.07059859,XRP,,Poloniex,2017-09-09 21:39:42,
+Withdrawal,,,,2,BTC,,0.0001,BTC,,Poloniex,2017-12-24 12:01:33,to Coinfloor
+Deposit,2,BTC,,,,,,,,Coinfloor,2017-12-24 13:53:19,from Poloniex
+Trade,10063.92,GBP,,0.999,BTC,,30.19,GBP,,Coinfloor,2017-12-24 16:09:09,
+Trade,10062.93,GBP,,0.999,BTC,,30.19,GBP,,Coinfloor,2017-12-24 16:09:14,
+Trade,10.07,GBP,,0.001,BTC,,0.03,GBP,,Coinfloor,2017-12-24 16:09:26,
+Trade,10.08,GBP,,0.001,BTC,,0.03,GBP,,Coinfloor,2017-12-24 16:09:33,
+Withdrawal,,,,20086.56,GBP,,,,,Coinfloor,2017-12-29 23:00:05,to Bank
+Mining,12.5,BTC,,,,,,,,Desktop wallet,2018-01-02 14:26:12,
+Spend,,,,2000,XRP,,,,,Poloniex,2018-04-01 12:57:11,
+Trade,917.1344668,XRP,,0.03037549,BTC,,2.29283616,XRP,,Poloniex,2018-04-05 15:06:49,

examples/csv/cctax/koinly/README.md

@@ -0,0 +1,3 @@
+https://koinly.io
+
+See ../README.md.

examples/csv/cctax/koinly/_Koinly Custom CSV - Advanced - Sheet1.csv

@@ -0,0 +1,4 @@
+Date,Sent Amount,Sent Currency,Received Amount,Received Currency,Fee Amount,Fee Currency,Net Worth Amount,Net Worth Currency,Label,Description,TxHash
+2018-01-01 14:25 UTC,1000,USD,1,BTC,5,USD,,,,my first crypto!,
+2018-01-02 14:25 UTC,0.5,BTC,,,,,,,,,
+2018-01-03 14:25 UTC,,,1,BTC,,,,,mining,,0x12345

examples/csv/cctax/rotki/README.md

@@ -0,0 +1,3 @@
+https://rotki.com
+https://docs.rotki.com/usage-guides/pnl.html
+https://github.com/rotki/rotki

examples/csv/cctax/rotki/_address_book_entries.csv

@@ -0,0 +1,5 @@
+address,name,blockchain,location
+0xa83114a443da1cecefc50368531cace9f37fcccb,harvey,,
+0x388c818ca8b9251b393131c08a736a67ccb19297,donna,,global
+0xdac17f958d2ee523a2206206994597c13d831ec7,mike,arbitrum_one,
+bc1q2t0ad9cqars69ge9v7v7td7rpg3p7etgqfe0zn,rachel,btc,private

examples/csv/cctax/rotki/_blockchain-accounts.csv

@@ -0,0 +1,13 @@
+address,address extras,chain,label,tags
+0x99A91871b93E13F53D8209529B5E390664bf25d8,,evm,eth with validators,eth-1;eth-with-validators
+0x9DBE4Eb4A0a41955E1DC733E322f84295a0aa5c0,,evm,hahaha,evm-tag
+0xc37b40ABdB939635068d3c5f13E7faF686F03B65,,evm,,
+bc1qdf3av8da4up78shctfual6j6cv3kyvcw6qk3fz,,btc,bitcoin-1,bitcoin-1
+qz5hccuhr036drq7m3mah3qf5x3f5phv05v5rtu5z2,,bch,bitcoin-cash-1,bitcoin-cash-1
+EbEjgkw4Z2jFtaDad7zj59LrfmyuznXJzCmQh2qUfMvjiUj,,ksm,kusama-1,kusama-1
+14rw69gBpjYwdiw5MzvsZCSYVnHqubpUSHC5QPNBY5MPAoRi,,dot,polkadot-1,polkadot-1
+xpub6CcGTthbwnbxsMRuEF3XoYdekGtnGTsbiZ4ZKeqMC1UuqPYqh2xQj9hbEQj8AB9EuGeFHz4o3hWayZm5ahr5fyV2SNfNyA6htsZngM1DFBz,,btc,xpub-1,xpub-1
+0x80858247aa14f2c23e9a83b65d2a3e3de22f16ddaaf3fad0fee52601d3f67f71ccb72b196a4789a9d0aa057721745996,,eth2,,
+0x918583458bae9b00cfb9d78497d58f9678cf91755a08682410756909de021666208ecf84e97ac5abddbf5f17af5fb11d,ownershipPercentage=50.00,eth2,,
+0xab423fb58c3498a8014bcc115be96bea77c99004fb59d3580d75fff0054e113d126ee6dd65faa027732f7cf38fdb4dd2,ownershipPercentage=22.00,eth2,,
+0xa49152b5babd0130d9e5e3480eb9d17dfad5c090e6a7b6849e14b6baba0d47444fdd454303bfd202b6ae895654f678c0,ownershipPercentage=33.00,eth2,,

examples/csv/cctax/rotki/_import-csv-generic.md

@@ -0,0 +1,68 @@
+## rotki Generic Import
+
+You can import data (trades & events) from exchanges not supported by rotki by clicking "Import Data" on the left sidebar, selecting `Custom Import` and following the prompt. This involves the user converting the source (a not directly supported exchange, protocol, etc.) data to match the import format of rotki.
+
+> **Note**: Keep in mind that all assets that you enter are identified by their asset identifier and not the symbol, as symbols are not unique. The identifier differs per asset and at the moment for ERC20 tokens follows the [CAIP-19](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-19.md) format, and for others, it's just the asset symbol or a random string for manually input tokens.
+
+For the CAIP-19 format, it's essentially calculated by knowing the chain ID and the address of your token. So for mainnet (chain ID 1) and USDT (0xdAC17F958D2ee523a2206206994597C13D831ec7), it's `eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7`.
+
+You can easily find the identifier of each asset by going to `Manage Assets > Assets` section and copying the identifier of the asset in question.
+
+The import is split into two types:
+
+### rotki Generic Trades Import
+
+This is solely for importing generic trades. The expected file format is **CSV** with the following headers and descriptions as a guide:
+
+1. **Location**: This is the source of the data. It should be one of rotki's [supported locations](#supported-locations). If it is not supported, use `"external"`.
+2. **Spend Currency**: The currency you spent in the trade, can be a token address (e.g., `eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7`) or symbol (e.g., `BTC`).
+3. **Spend Amount**: The amount of currency you spent.
+4. **Receive Currency**: The currency you received in the trade, can be a token address or symbol.
+5. **Receive Amount**: The amount of currency you received.
+6. **Fee**: The amount charged for the trade. This is optional.
+7. **Fee Currency**: The currency in which the fee was charged. This is optional.
+8. **Description**: A description of the trade if any. This is optional.
+9. **Timestamp**: The UTC Unix timestamp at which the trade took place. This is a milliseconds timestamp.
+
+A sample generic trades template can be found below:
+
+<CsvTable title="rotki Generic Trades Template" csvUrl="/files/rotki_generic_trades.csv" />
+Location,Spend Currency,Receive Currency,Receive Amount,Spend Amount,Fee,Fee Currency,Description,Timestamp
+binance,eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48,ETH,1.0000,1875.64,,,Trade USDC for ETH,1659085200000
+kraken,LTC,BTC,4.3241,392.8870,,,Trade LTC for BTC,1659171600000
+kucoin,eip155:1/erc20:0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984,eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F,880.0000,20.0000,0.1040,USD,Trade UNI for DAI,1659344400000
+luno,ADA,BCH,16.3444,4576.6400,5.1345,USD,Trade ADA for BCH,1659344900000
+bisq,eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7,eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F,0,4576.6400,5.1345,USD,Trade USDT for DAI,1659345600000
+
+### rotki Generic Events Import
+
+This is for importing generic events. Supported events are `"Deposit"`, `"Withdrawal"`, `"Income"`, `"Loss"`, `"Spend"` and `"Staking"`. The expected file format is **CSV** with the following headers and descriptions as a guide:
+
+1. **Type**: The event type. It can be one of `"Deposit"`, `"Withdrawal"`, `"Income"`, `"Loss"`, `"Spend"` or `"Staking"`.
+2. **Location**: This is the source of the data. It should be one of rotki's [supported locations](#supported-locations). If it is not supported, use `"external"`.
+3. **Currency**: The currency used during the specified event.
+4. **Amount**: The amount of the currency used by the event.
+5. **Fee**: The amount charged for the event. This is optional.
+6. **Fee Currency**: The currency in which the fee was charged. This is optional.
+7. **Description**: A description of the event that was carried out, if any. This is optional.
+8. **Timestamp**: The UTC Unix timestamp at which the event took place. This is a milliseconds timestamp.
+
+A sample generic events template can be found below:
+
+<CsvTable title="rotki Generic Events Template" csvUrl="/files/rotki_generic_events.csv" />
+Type,Location,Currency,Amount,Fee,Fee Currency,Description,Timestamp
+Deposit,kucoin,EUR,1000.00,,,Deposit EUR to Kucoin,1658912400000
+Withdrawal,binance,eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7,99.00,1.00,eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7,,1658998800000
+Withdrawal,kraken,eip155:1/erc20:0xB8c77482e45F1F44dE1745F52C74426C631bDD52,1.01,,,,1659085200000
+Staking,luno,ETH,0.0513,,,ETH Staking reward from QRS,1659340800000
+Loss,coinbase,BTC,0.0910,,,,1659430800000
+Income,cex,eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F,1000.00,,,,1659513600000
+Invalid,bisq,BCH,0.3456,,,,1659686400000
+
+### Supported Locations
+
+A list of supported locations in rotki are `"external"`, `"kraken"`, `"poloniex"`, `"bittrex"`, `"binance"`, `"bitmex"`, `"coinbase"`, `"banks"`, `"blockchain"`, `"gemini"`, `"equities"`, `"realestate"`, `"commodities"`, `"cryptocom"`, `"uniswap"`, `"bitstamp"`, `"binanceus"`, `"bitfinex"`, `"bitcoinde"`, `"iconomi"`, `"kucoin"`, `"balancer"`, `"loopring"`, `"ftx"`, `"nexo"`, `"blockfi"`, `"independentreserve"`, `"gitcoin"`, `"sushiswap"`, `"shapeshift"`, `"uphold"`, `"bitpanda"`, `"bisq"`, `"ftxus"` and `"okx"`.
+
+> **Note**: In the columns where an asset is expected, you will need to use the identifier that such asset has in rotki; otherwise, the row won't be read.
+
+> **Note**: If at any point, you're confused about the CSV format, feel free to send us a message on [Discord](https://discord.rotki.com).

examples/csv/cctax/rotki/_rotki_generic_events.csv

@@ -0,0 +1,8 @@
+Type,Location,Currency,Amount,Fee,Fee Currency,Description,Timestamp
+Deposit,kucoin,EUR,1000.00,,,Deposit EUR to Kucoin,1658912400000
+Withdrawal,binance,eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7,99.00,1.00,eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7,,1658998800000
+Withdrawal,kraken,eip155:1/erc20:0xB8c77482e45F1F44dE1745F52C74426C631bDD52,1.01,,,,1659085200000
+Staking,luno,ETH,0.0513,,,ETH Staking reward from QRS,1659340800000
+Loss,coinbase,BTC,0.0910,,,,1659430800000
+Income,cex,eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F,1000.00,,,,1659513600000
+Invalid,bisq,BCH,0.3456,,,,1659686400000

examples/csv/cctax/rotki/_rotki_generic_trades.csv

@@ -0,0 +1,6 @@
+Location,Spend Currency,Receive Currency,Receive Amount,Spend Amount,Fee,Fee Currency,Description,Timestamp
+binance,eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48,ETH,1.0000,1875.64,,,Trade USDC for ETH,1659085200000
+kraken,LTC,BTC,4.3241,392.8870,,,Trade LTC for BTC,1659171600000
+kucoin,eip155:1/erc20:0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984,eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F,880.0000,20.0000,0.1040,USD,Trade UNI for DAI,1659344400000
+luno,ADA,BCH,16.3444,4576.6400,5.1345,USD,Trade ADA for BCH,1659344900000
+bisq,eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7,eip155:1/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F,0,4576.6400,5.1345,USD,Trade USDT for DAI,1659345600000

examples/csv/cctax/rp2/README.md

@@ -0,0 +1 @@
+https://github.com/eprbell/rp2