{"id":16717088,"url":"https://github.com/metanivek/taz","last_synced_at":"2025-04-10T06:42:53.653Z","repository":{"id":42046050,"uuid":"477184116","full_name":"metanivek/taz","owner":"metanivek","description":"Collect, classify, and collate your Tezos transactions","archived":false,"fork":false,"pushed_at":"2022-04-15T19:13:34.000Z","size":762,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-01T23:49:20.992Z","etag":null,"topics":["tezos"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/metanivek.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}},"created_at":"2022-04-02T22:20:39.000Z","updated_at":"2022-08-03T23:10:46.000Z","dependencies_parsed_at":"2022-08-12T03:20:21.137Z","dependency_job_id":null,"html_url":"https://github.com/metanivek/taz","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metanivek%2Ftaz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metanivek%2Ftaz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metanivek%2Ftaz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metanivek%2Ftaz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/metanivek","download_url":"https://codeload.github.com/metanivek/taz/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248173366,"owners_count":21059592,"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":["tezos"],"created_at":"2024-10-12T21:29:42.469Z","updated_at":"2025-04-10T06:42:53.628Z","avatar_url":"https://github.com/metanivek.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![tests](https://github.com/metanivek/taz/actions/workflows/test.yml/badge.svg)](https://github.com/metanivek/taz/actions/workflows/test.yml)\n\n# Taz\n\nTaz is a tool for analyzing and reporting on your Tezos transactions.\n\nTaz does three things to help analyze your Tezos transactions.\n\n1. **Collect**: It downloads transactions and other data needed for processing.\n1. **Classify**: It analyzes and classifies your transactions within and across\n   accounts.\n1. **Collate**: It gathers, sorts, and further classifies all transactions.\n\nFrom these three things, Taz is also able to help automate creating CSV reports\nlike income statements and gains and losses reports.\n\n## Caveat Utilitor\n\n**Disclaimer**: Taz is not a replacement for professional financial or tax\nadvice. Code and documentation are provided for informational purposes; use at\nyour own risk.\n\n## Status\n\nTaz is a work in progress. I created this based on my own usage, but Tezos is a\nbig place, with lots of different interaction patterns. If something doesn't\nlook right (or you get errors when running it), feel free to open an issue or\nsuggest code changes via PR. It is my goal to support as much of the Tezos\nblockchain as I can.\n\nCurrent areas of known limitation:\n\n1. DeFi. Outsize of simple XTZ-token swaps, Taz most likely does not properly\n   classify/analyze DeFi transactions like liquidity, staking, etc. This is my\n   highest priority area to improve.\n1. NFT platforms I haven't used. Some _should_ work but I haven't directly tested all.\n1. Custom constracts. Taz has a rudimentary plugin system for special case\n   handling of contracts, but with almost 100k contracts on Tezos, there is lots\n   of room for improvement.\n1. Unknown unknowns. :alien:\n\n---\n\n# Using Taz\n\n## Technical Setup\n\n1. Make sure you have Node.js installed (tested on v16.14.0). [Installation Instructions](https://nodejs.dev/learn/how-to-install-nodejs)\n1. Clone/download repository. [GitHub Help](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository)\n1. Install node dependencies by opening a terminal application, navigating to\n   the directory where you cloned the repository, and running `npm install`.\n\n## Configuration\n\nTo configure Taz for your data:\n\n1. Copy the `.env.sample` file to a file named `.env`. This is where Taz reads\n   configuration information.\n1. Set the variables in `.env`\n\nOnce you have done this, you _can_ run Taz to see its output, but the analysis\nwill be wrong unless you create your exchange CSV files.\n\n### Currency Support\n\nTaz currently supports the currencies that TzKT does.\n\n- Btc\n- Cny\n- Eth\n- Eur\n- Gbp\n- Jpy\n- Krw\n- Usd\n\n## Centralized Exchange Data\n\nTaz does not automatically download centralized exchange data (yet), so you will\nhave to create this manually for accurate analysis.\n\nYou can find an sample CSV in the examples folder that contains each type of\ntransaction currently supported. For accurate analysis, you must include all\ntransactions that involve XTZ. For instance if you receive BTC and then trade it\nfor XTZ, you must include the transaction where you receive BTC. You can include\ntransactions for other cryptocurrencies but Taz will ignore them.\n\nThe easiest way to create this CSV is to [copy the sample\nCSV](./sample/exchange-transactions.csv) and replace the example transactions\nwith your own. Once you have finished your CSV put it in the appropriate year's\nuser folder (creating if needed).\n\nExample folder structure:\n\n- data\n  - 2021\n    - user\n      - exchange-transactions.csv\n\n### Headers\n\nThese headers must be in your CSV.\n\n- `timestamp`: ISO 8601 timestamp of transaction\n- `type`: type of transaction\n- `fiat`: price in fiat per coin. This **must** be present for `receive`,\n  `trade`, `interest`, `trade:fiat-in`, and `trade:fiat-out` types.\n- `in_amt`: amount for incoming transcation\n- `in_token`: token symbol for incoming transaction (eg, XTZ)\n- `in_token_id`: token id for incoming transaction (not used currently)\n- `in_token_from`: source of incoming transaction (use your address when\n  transferring to a centralized exchange)\n- `out_amt`: amount for outgoing transaction\n- `out_token`: token symbol for outgoing transaction (eg, XTZ)\n- `out_token_id`: token id for outgoing transaction (not used currently)\n- `out_token_to`: destination of outgoing transaction (use your own address when\n  transferring to yourself)\n- `fees`: fee for transaction. Include for outgoing `transfer` types.\n- `account`: account for transaction. You can use the name of your exchange if\n  you like.\n- `op`: operation hash for transaction. You **must** include this for `transfer`\n  types. Most exchanges will give you this information, but you might need to\n  find it on a blockchain explorer like [TzKT](https://tzkt.io/) if not.\n\n### Types\n\nTaz supports the following transaction types in the exchange CSV.\n\n- `transfer`: for sending or receiving tez to or from one of your addresses.\n  `fiat` is not needed.\n- `receive`: for receiving _any_ cryptocurrency from an address that is not\n  yours. `fiat` is price per coin of incoming token.\n- `trade`: trading cryptocurrency for cryptocurrency. `fiat` is price per coin of\n  outgoing token.\n- `trade:fiat-out`: trading fiat for cryptocurrency. `fiat` is price per coin of\n  incoming token.\n- `trade:fiat-in`: trading cryptocurrency for fiat. `fiat` is price per coin of\n  outgoing token.\n- `interest`: cryptocurrency received from exchange for holding (usually this is\n  a staking reward of some kind). `fiat` is price per coin of incoming token.\n\n### Operation Hashes\n\nFor incoming and outgoing `transfer` types, make sure to include the operation\nhash in the `op` column so that Taz can match it correctly with the\ncorresponding blockchain transaction.\n\n### Fiat\n\nTaz uses the `fiat` column to calculate cost basis and income. Here is how to\nset it, based on `type`:\n\n- `receive`: price per coin for `in_token`\n- `interest`: price per coin for `in_token`\n- `trade`: price per coin for `out_token`\n- `trade:fiat-out`: price per coin of `in_token`\n- `trade:fiat-in`: price per coin of `out_token`\n- `transfer`: not needed\n\n## Running Taz\n\nNow that you have configured Taz and created your exchange CSV, you are now ready\nto download your blockchain data and look at how Taz analyzes it! :tada:\n\nSimple run `node index.js` in Taz's directory. Depending on how many\ntransactions you have it can take some time to download, but once Taz finishes,\nyou should see data in your year folders (under `data`).\n\nIf you run into problems, feel free to let me know by opening an issue.\n\n# Reports\n\nCurrently, Taz creates the following reports (found in the `reports` folder for\na given year, eg `data/2021/reports/`):\n\n- `gains-FIFO.csv`: a FIFO report of gains and losses\n- `gains-HIFO.csv`: a HIFO report of gains and losses\n- `income.csv`: an income statement\n- `all-classified-transactions.csv`: a collated report of how Taz classified all\n  of your transactions\n- individual classification reports for each address you configure\n\n# Contributing\n\nThe most helpful way to contribute at the moment is to setup Taz, run it, and\nlet me know if you experience errors or data that looks/is wrong. I also welcome\ncode contributions, if you're willing to jump into a young code base. All code\nis [MIT licensed](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetanivek%2Ftaz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmetanivek%2Ftaz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetanivek%2Ftaz/lists"}