BittyTax

BittyTax — Open-source cryptocurrency tax calculator for UK HMRC rules with capital gains computation (Same-Day, Bed & Breakfast, Section 104 Pool), 25+ transaction types, Excel/CSV import, wallet balance audit, PDF report generation, and Tkinter GUI interface

 /$$$$$$$  /$$   /$$     /$$            /$$$$$$$$                 
| $$__  $$|__/  | $$    | $$           |__  $$__/                 
| $$  \ $$ /$$ /$$$$$$ /$$$$$$   /$$   /$$| $$  /$$$$$$  /$$   /$$
| $$$$$$$ | $$|_  $$_/|_  $$_/  | $$  | $$| $$ |____  $$|  $$ /$$/
| $$__  $$| $$  | $$    | $$    | $$  | $$| $$  /$$$$$$$ \  $$$$/ 
| $$  \ $$| $$  | $$ /$$| $$ /$$| $$  | $$| $$ /$$__  $$  >$$  $$
| $$$$$$$/| $$  |  $$$$/|  $$$$/|  $$$$$$$| $$|  $$$$$$$ /$$/\  $$
|_______/ |__/   \___/   \___/   \____  $$|__/ \_______/|__/  \__/
                                 /$$  | $$                         
                                |  $$$$$$/                         
                                 \______/

Command-line crypto tax calculator for UK tax rules — capital gains, income, audit, and PDF reports

Installation · Features · Usage · Record Format · Configuration · FAQ · Disclaimer

</div>

About

BittyTax is an open-source command-line cryptocurrency tax calculator designed for UK HMRC tax rules. It processes transaction records from exchanges and wallets, calculates capital gains and crypto income, audits wallet balances, and generates comprehensive tax reports in PDF or terminal format.

This tool implements the full UK capital gains matching hierarchy: Same-Day Rule (TCGA92 S105), Bed & Breakfast Rule (30-day window), and Section 104 Pool calculations. It supports 25+ transaction types covering trading, staking, DeFi, margin, lending, and more.

The tool offers both a Tkinter GUI for visual interaction and a CLI mode for batch processing and automation.

Official Links

| # | Resource | Link | |:-:|----------|------| | 1 | HMRC Cryptoassets Manual | gov.uk — Crypto Assets | | 2 | HMRC CGT Test Cases | BittyTax Wiki — HMRC Examples | | 3 | BTWrapper (Web Interface) | cgt.edce.uk |

Features

<table> <tr><td colspan="2"><strong>Tax Calculation Engine</strong></td></tr> <tr><td>✅</td><td>Capital gains calculation — disposals, proceeds, cost basis</td></tr> <tr><td>✅</td><td>Same-Day matching rule (TCGA92 S105)</td></tr> <tr><td>✅</td><td>Bed & Breakfast rule — 30-day buyback window</td></tr> <tr><td>✅</td><td>Section 104 pool cost averaging</td></tr> <tr><td>✅</td><td>Crypto income tracking — mining, staking, interest, dividends</td></tr> <tr><td>✅</td><td>Fee handling across all transaction types</td></tr> <tr><td colspan="2"><strong>Transaction Types (25+)</strong></td></tr> <tr><td>✅</td><td>Core: Deposit, Withdrawal, Trade, Spend</td></tr> <tr><td>✅</td><td>Income: Mining, Staking-Reward, Interest, Dividend, Income, Airdrop</td></tr> <tr><td>✅</td><td>Transfers: Gift-Sent, Gift-Received, Gift-Spouse, Charity-Sent</td></tr> <tr><td>✅</td><td>DeFi: Stake, Unstake, Fork, Loan, Loan-Repayment, Loan-Interest</td></tr> <tr><td>✅</td><td>Margin: Margin-Gain, Margin-Loss, Margin-Fee, Margin-Fee-Rebate</td></tr> <tr><td>✅</td><td>Other: Referral, Cashback, Fee-Rebate, Lost</td></tr> <tr><td colspan="2"><strong>Data Processing</strong></td></tr> <tr><td>✅</td><td>Excel (.xlsx) and CSV file import</td></tr> <tr><td>✅</td><td>Automatic GBP price lookup and valuation</td></tr> <tr><td>✅</td><td>Wallet balance audit with integrity verification</td></tr> <tr><td>✅</td><td>Record validation with mandatory field enforcement per type</td></tr> <tr><td>✅</td><td>PDF tax report generation (ReportLab)</td></tr> <tr><td colspan="2"><strong>Interface</strong></td></tr> <tr><td>✅</td><td>Tkinter GUI with visual transaction processing</td></tr> <tr><td>✅</td><td>CLI mode for batch/automated processing (<code>--cli</code>)</td></tr> <tr><td>✅</td><td>Rich-styled console menu with ASCII banner</td></tr> <tr><td>✅</td><td>Configurable via <code>bittytax.conf</code></td></tr> </table>

Installation

Prerequisites

| Dependency | Version | Purpose | |------------|---------|---------| | Python | 3.8+ | Runtime | | pip | Latest | Package manager | | pandas | ≥ 2.0.0 | Data manipulation | | openpyxl | ≥ 3.1.0 | Excel file I/O | | reportlab | ≥ 4.0.0 | PDF report generation | | pyyaml | ≥ 6.0 | Configuration parsing | | rich | ≥ 13.0.0 | Terminal UI | | tqdm | ≥ 4.65.0 | Progress bars | | tkinter | stdlib | GUI (bundled with Python) |

Windows (One-Click)

git clone <repository-url>
cd BittyTax
pip install -r requirements.txt
python main.py

Linux / macOS

git clone <repository-url>
cd BittyTax
pip3 install -r requirements.txt
python3 main.py

CLI Mode (Headless)

python main.py --cli path/to/transactions.xlsx

Record Format

BittyTax uses a standardized transaction record format. Each row represents one transaction with the following columns:

| Column | Description | Required | |--------|-------------|:--------:| | Type | Transaction type (see list below) | Yes | | Buy Quantity | Amount of asset acquired | Per type | | Buy Asset | Ticker of acquired asset (BTC, ETH, etc.) | Per type | | Buy Value in GBP | GBP value at time of acquisition | Optional | | Sell Quantity | Amount of asset disposed | Per type | | Sell Asset | Ticker of disposed asset | Per type | | Sell Value in GBP | GBP value at time of disposal | Optional | | Fee Quantity | Fee amount | Optional | | Fee Asset | Fee asset ticker | Optional | | Fee Value in GBP | Fee value in GBP | Optional | | Wallet | Wallet/exchange name | Optional | | Timestamp | ISO 8601 datetime | Yes | | Note | Free-text annotation | Optional |

Transaction Types

| Category | Types | |----------|-------| | Core | Deposit, Withdrawal, Trade, Spend | | Income | Mining, Staking-Reward, Interest, Dividend, Income | | Gifts | Gift-Received, Gift-Sent, Gift-Spouse, Charity-Sent | | DeFi | Stake, Unstake, Fork, Airdrop, Loan, Loan-Repayment, Loan-Interest | | Margin | Margin-Gain, Margin-Loss, Margin-Fee, Margin-Fee-Rebate | | Other | Referral, Cashback, Fee-Rebate, Lost |

Example Record (CSV)

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
Trade,0.5,BTC,,500,GBP,,0.001,BTC,,Coinbase,2024-03-15T10:30:00,Bought BTC
Trade,,,,0.25,BTC,12500,0.0005,BTC,,Coinbase,2024-09-20T14:00:00,Sold BTC
Staking-Reward,0.01,ETH,25,,,,,,,,2024-06-01T00:00:00,Monthly staking

Configuration

Settings are managed via bittytax.conf (YAML) and loaded by utils/gpu_manager.py:

local_currency: GBP
tax_year: 2024
price_source: coingecko
output_format: pdf
audit_enabled: true

| Key | Description | Default | |-----|-------------|---------| | local_currency | Base fiat currency for valuations | GBP | | tax_year | Target tax year for report | Current year | | price_source | Historical price data provider | coingecko | | output_format | Report output: pdf or terminal | pdf | | audit_enabled | Run wallet balance audit | true |

Usage

GUI Mode

Launch the interactive Tkinter interface:

python main.py

╭──────────────────────────────────────────────────────╮
│                    BittyTax                           │
├──────────────────────────────────────────────────────┤
│  [1]  Start              — Launch GUI                │
│  [2]  About              — Project details           │
│  [3]  Help               — Usage instructions        │
│  [0]  Exit                                           │
╰──────────────────────────────────────────────────────╯

| Option | Action | |:------:|--------| | 1 | Open Tkinter GUI — load file, process, view report | | 2 | Display full project description and feature list | | 3 | Show installation and usage instructions | | 0 | Exit application |

CLI Mode

Process a transaction file directly from the command line:

python main.py --cli transactions.xlsx

Output includes capital gains summary: disposal count, total proceeds (GBP), total cost basis (GBP), and net gain/loss.

Project Structure

BittyTax/
├── main.py                 # Entry point — GUI menu or CLI (--cli <file>)
├── requirements.txt        # Python dependencies
├── README.md               # This file
├── gui/
│   ├── __init__.py
│   └── main_window.py     # Tkinter GUI — file load, processing, reports
├── core/
│   ├── __init__.py
│   ├── inpainting.py      # GBP valuation — price lookup and filling
│   ├── processor.py       # Pipeline: load → validate → audit → report
│   └── validator.py       # Record validation — mandatory fields per type
├── detection/
│   ├── __init__.py
│   ├── detector.py        # Export format detection (CSV / Excel)
│   ├── signature.py       # Transaction type definitions and field rules
│   └── temporal.py        # Same-day rule, Bed & Breakfast, Section 104
└── utils/
    ├── __init__.py
    ├── file_handler.py    # Exce

BittyTax

Install / Use

README

BittyTax

About

Official Links

Features

Installation

Prerequisites

Windows (One-Click)

Linux / macOS

CLI Mode (Headless)

Record Format

Transaction Types

Example Record (CSV)

Configuration

Usage

GUI Mode

CLI Mode

Project Structure