{"id":15428952,"url":"https://github.com/timdaub/taxtool","last_synced_at":"2025-04-19T16:36:32.941Z","repository":{"id":151389337,"uuid":"348787648","full_name":"TimDaub/taxtool","owner":"TimDaub","description":"Embrace the pain of filing your sweet crypto gainz; do it with this lame JS accounting tool!","archived":false,"fork":false,"pushed_at":"2021-08-12T16:18:03.000Z","size":260,"stargazers_count":10,"open_issues_count":4,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-29T10:12:09.152Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TimDaub.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-03-17T17:01:10.000Z","updated_at":"2023-06-27T12:05:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"5cf92c41-1995-4ede-a17d-ab963492462c","html_url":"https://github.com/TimDaub/taxtool","commit_stats":{"total_commits":31,"total_committers":1,"mean_commits":31.0,"dds":0.0,"last_synced_commit":"f1e438896d6fb40992d30b49dafc51d9d5effdff"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimDaub%2Ftaxtool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimDaub%2Ftaxtool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimDaub%2Ftaxtool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimDaub%2Ftaxtool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TimDaub","download_url":"https://codeload.github.com/TimDaub/taxtool/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249739070,"owners_count":21318507,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-01T18:08:11.244Z","updated_at":"2025-04-19T16:36:32.917Z","avatar_url":"https://github.com/TimDaub.png","language":"JavaScript","readme":"# taxtool\n\n[![npm version](https://badge.fury.io/js/taxtool.svg)](https://badge.fury.io/js/taxtool)\n[![Node.js CI](https://github.com/TimDaub/taxtool/actions/workflows/node.js.yml/badge.svg)](https://github.com/TimDaub/taxtool/actions/workflows/node.js.yml)\n\ntaxtool is a tool that can help you file your crypto currency taxes. It's NOT\nan all-encompassing tool that will accompany throught your annual tax life\ncycle. Instead, its aim is to provide tools that do a single job well to help\nyou and your accountant to file your taxes in time.\n\n## Data Acquisition\n\ntaxtool won't help you collect your data from exchanges. I had to go through\nthat pain myself and I don't think I'm in a position to automate that yet.\nHowever, most exchanges allow you to download some sort of CSV file. Take that\nCSV file and try to map it onto the data format specified in the next section\nand your tax accountant will thank you.\n\n## Why Use taxtool?\n\nThere's many \"better\" tools on the internet. They allow you to create\nconnections to exchanges and they do \"all the hard work\" to make filling taxes\nfor crypto less complex. However, they all had problems that lead me to create\nthis small set of tools. Some problems I encountered in other tools:\n\n- They did not respect my privacy by e.g. uploading my tax data into a cloud.\n- They did impose an opinionated approach towards calculating my tax return.\n- They were so huge/complex/properietary that it was impossible for me or my\n  tax accountant to verify that their calculations were correct.\n\nThat's why I ended building `taxtool` myself. My goal is to build a tool that\nsupports an offline-first workflow. It doesn't impose opinion or\njuristicional-specific logic on the data. taxtools purpose is to deliver clean\nand factual data to financial authorities such that when they decided how they\nwant to tax crypto, they can do so with my data. I want to build taxtool such\nthat it remains a small and well-tested code base.\n\n## Data Format\n\n`taxtool` works with `.csv` files. It mandates a canonical header structure:\n\n```csv\ntype,location,asset,amount,exchanged_amount,exchanged_asset,datetime\nbuy,coinbase,ETH,1.5,1.5,EUR,2021-03-17T11:32:48.468Z\nbuy,coinbase,ETH,1.5,1.5,EUR,2021-03-17T11:32:48.468Z\n```\n\ntaxtool uses this data structure as my accountant and I found this\nstructure useful.\n\n### Properties\n\n- `type` is either `{\"sell\", \"buy\", \"receive\", \"send\"}`.\n- `location` is an arbitrary string referring to the exchange of the trade.\n- `asset` is the ticker value of the asset, e.g. Ethereum is \"ETH\".\n- `amount` is the amount of `asset`.\n- `exchanged_amount` is the amount of `exchanged_asset`.\n- `exchanged_asset` is the counter asset ticket of `asset`, e.g. Euro is \"EUR\".\n- `datetime` is the ISO 8601 time the action executed. Note that ISO 8601 assumes\n  UTC as its default time zone.\n\nFor `type == \"receive\"` or `type == \"send\"`, `exchanged_amount` and\n`exchanged_asset` have to be empty.\n\n### Notes\n\n- taxtool uses [moneysafe](https://www.npmjs.com/package/moneysafe) to ensure\n  precision for financial calculations.\n\n## Installation\n\n```bash\n$ npm i -g taxtool\n```\n\nAlternatively, you can clone this repo and use `npx taxtool --help` to run\ncommands.\n\n## Usage\n\n### `--help`\n\n```bash\n$ taxtool --help\n```\n\n### Using `--parse, -p`\n\nThe purpose of the `--parse` option is help you format your .csv file into the\ncanonical `taxtool` format layed out a few sections above. Successfully parsing\nyour .csv file will allow you to use further functionality of `taxtool`.\n\n```bash\n$ taxtool trades.csv --parse \u003e parsed.csv\n$ cat parsed.csv\n\u003e type,location,asset,amount,exchanged_amount,exchanged_asset,datetime\n\u003e buy,coinbase,ETH,1.5,1.5,EUR,2021-03-17T11:32:48.468Z\n\u003e ...\n```\n\n### Using `--formatdatetime, -f`\n\nAssuming you have a date of the format `28/05/2017 13:18:12 Z`, then you can\nuse the format string `dd/MM/yyyy HH:mm:ss X` according to [date-fns's\n`parse`](https://date-fns.org/v2.8.1/docs/parse). Please don't forget including\ntimezone information in your date strings as otherwise the data may be\nincorrectly shifted in relation to UTC.\n\ntrades.csv\n```csv\n\u003e type,location,asset,amount,exchanged_amount,exchanged_asset,datetime\n\u003e buy,coinbase,ETH,1.5,1.5,EUR,17/03/2021 11:32:48\n```\n\n```bash\n$ taxtool trades.csv --parse -f \"dd/MM/yyyy HH:mm:ss\"\n\u003e type,location,asset,amount,exchanged_amount,exchanged_asset,datetime\n\u003e buy,coinbase,ETH,1.5,1.5,EUR,2021-03-17T11:32:48.468Z\n\u003e ...\n```\n\n**Please note** that taxtool assumes all datetimes in your computer's time\nzone. It will, however, output [ISO\n8601](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString)\nin the \"UTC\" timezone indicated by the \"Z\" suffix.\n\n### Using `--checkduplicates, -d`\n\nThere could be cases where your file includes two times the exact same trade.\nHowever, you want to make sure to remove all duplicates. By using `-d`, all\ntrades of a file will be comparred with each other and in case of a duplicate\nan error will be thrown.\n\n### Using `--order, -o`\n\nTrades can be sorted ascendingly by date using the `--order` parameter.\n\n### Using `--calcbalance, -b`\n\nTo check a document's plausibility or to see a year's revenue, `--calcbalance`\ncan be used. As an string input it takes an asset name e.g. \"ETH\" and will then\nextend the output by adding five new colums:\n\n1. `{assetName}_BOUGHT`: The number of assets bought until that date.\n1. `{assetName}_SOLD`: The number of assets sold until that date.\n1. `{assetName}_RECEIVED`: The number of assets received until that date (e.g.\n   through a donation).\n1. `{assetName}_SENT`: The number of assets sent until that date (e.g.  to rent\n   a server).\n1. `{assetName}_BALANCE`: The balance of that asset after the transaction.\n\nUpfront, all trades are sorted by their date time in an ascending order.\n`--calcbalance` can process multiple assets at once by separating them with a\ncomma: `--calcbalance \"ETH,EUR\"`\n\ntrades.csv\n```csv\ntype,location,asset,amount,exchanged_amount,exchanged_asset,datetime\nbuy,coinbase,ETH,1,1,EUR,2021-03-17T11:32:48.468Z\nsell,coinbase,ETH,1,1,EUR,2021-03-17T12:32:48.468Z\nsell,coinbase,EUR,1,1,ETH,2021-03-17T13:32:48.468Z\nbuy,coinbase,EUR,1,1,ETH,2021-03-17T14:32:48.468Z\nreceive,friend,ETH,1,,,2015-05-26T10:21:15.000Z\nsend,friend,ETH,1,,,2021-05-26T10:21:15.000Z\n```\n\n```bash\n$ taxtool ./test/fixtures/testfile_balance.csv -p --calcbalance \"ETH,EUR\"\ntype,location,asset,amount,exchanged_amount,exchanged_asset,datetime,ETH_BOUGHT,ETH_SOLD,ETH_RECEIVED,ETH_SENT,ETH_BALANCE,EUR_BOUGHT,EUR_SOLD,EUR_RECEIVED,EUR_SENT,EUR_BALANCE\nreceive,friend,ETH,1.000000000000000000,,,2015-05-26T10:21:15.000Z,0.000000000000000000,0.000000000000000000,1.000000000000000000,0.000000000000000000,1.000000000000000000,0.00,0.00,0.00,0.00,0.00\nbuy,coinbase,ETH,1.000000000000000000,1.00,EUR,2021-03-17T11:32:48.468Z,1.000000000000000000,0.000000000000000000,1.000000000000000000,0.000000000000000000,2.000000000000000000,0.00,1.00,0.00,0.00,-1.00\nsell,coinbase,ETH,1.000000000000000000,1.00,EUR,2021-03-17T12:32:48.468Z,1.000000000000000000,1.000000000000000000,1.000000000000000000,0.000000000000000000,1.000000000000000000,1.00,1.00,0.00,0.00,0.00\nsell,coinbase,EUR,1.00,1.000000000000000000,ETH,2021-03-17T13:32:48.468Z,2.000000000000000000,1.000000000000000000,1.000000000000000000,0.000000000000000000,2.000000000000000000,1.00,2.00,0.00,0.00,-1.00\nbuy,coinbase,EUR,1.00,1.000000000000000000,ETH,2021-03-17T14:32:48.468Z,2.000000000000000000,2.000000000000000000,1.000000000000000000,0.000000000000000000,1.000000000000000000,2.00,2.00,0.00,0.00,0.00\nsend,friend,ETH,1.000000000000000000,,,2021-05-26T10:21:15.000Z,2.000000000000000000,2.000000000000000000,1.000000000000000000,1.000000000000000000,0.000000000000000000,2.00,2.00,0.00,0.00,0.00\n```\n\nThis allows us to conclude that on `2021-05-26T10:21:15.000Z` (last action) the\nuser:\n- bought 2 ETH;\n- sold 2 ETH;\n- received 1 ETH\n- sent 1 ETH\n\nAnd that their balance is 0 ETH and 0 EUR.\n\n\n### Other Options\n\n- `--silence, -s` supresses the standard outputs.\n- `--delimiter, -l` can be used to define a preferred delimiter in the output\n  file, e.g. `taxtools -l \";\" ...`\n\n## Usage with Microsoft Excel\n\nThe output of taxtool is supposed to be compatible with tools like Microsoft\nExcel. However, note that these tools carry assumptions about a user's cultural\nenvironment. For example, in Germany the usage of `.` and `,` are swapped when\ncomparred to e.g. English accounting. taxtools will always output numbers with\nhigh precision through the use of\n[moneysafe](https://www.npmjs.com/package/moneysafe).\n\nTo use an up-to-date version of Excel, however, it may be required to label\nsome columns in the text-import wizard as \"Text\" and not \"General\".\nAdditionally, the `--delimiter, -l` function can help.\n\n![](./assets/excel-columns.png)\n\n## Changelog\n\n### 0.3.0\n\n- (Breaking change) `--calcbalance` now adds `${NAME}_RECEIVED`, `${NAME}_SENT`\nand `${NAME}_BALANCE`.\n- (Breaking change) Two new values (\"receive\" and \"send\") in the data format\nwere added for `type`.\n\n### 0.2.0\n\n- `--calcbalance` can now ingest multiple assets separated by a comma `,`\n- A new parameter boolean `--order` is introduced that sorts all trades in\n  ascending order. `--calcbalance` now automatically orders before too.\n- Balances with `--calcbalance` have been incorrect with reverse buys and sells\n  being accounted to the type of action. It is now correct and explicitly\n  tested.\n\n### 0.1.0\n\n- Add `--silence, -s` option\n- Add `--checkduplicate, -d` option\n- Add `--delimiter, -l` option\n- Add `--calcbalance, -b` option\n\n### 0.0.1\n\n- Initial release\n\n## License\n\nSee [LICENSE](./LICENSE)\n\n## Further reading\n\n- https://plaintextaccounting.org/\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimdaub%2Ftaxtool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftimdaub%2Ftaxtool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimdaub%2Ftaxtool/lists"}