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
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.
| # | 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 |
| Tax Calculation Engine | |
| ✅ | Capital gains calculation — disposals, proceeds, cost basis |
| ✅ | Same-Day matching rule (TCGA92 S105) |
| ✅ | Bed & Breakfast rule — 30-day buyback window |
| ✅ | Section 104 pool cost averaging |
| ✅ | Crypto income tracking — mining, staking, interest, dividends |
| ✅ | Fee handling across all transaction types |
| Transaction Types (25+) | |
| ✅ | Core: Deposit, Withdrawal, Trade, Spend |
| ✅ | Income: Mining, Staking-Reward, Interest, Dividend, Income, Airdrop |
| ✅ | Transfers: Gift-Sent, Gift-Received, Gift-Spouse, Charity-Sent |
| ✅ | DeFi: Stake, Unstake, Fork, Loan, Loan-Repayment, Loan-Interest |
| ✅ | Margin: Margin-Gain, Margin-Loss, Margin-Fee, Margin-Fee-Rebate |
| ✅ | Other: Referral, Cashback, Fee-Rebate, Lost |
| Data Processing | |
| ✅ | Excel (.xlsx) and CSV file import |
| ✅ | Automatic GBP price lookup and valuation |
| ✅ | Wallet balance audit with integrity verification |
| ✅ | Record validation with mandatory field enforcement per type |
| ✅ | PDF tax report generation (ReportLab) |
| Interface | |
| ✅ | Tkinter GUI with visual transaction processing |
| ✅ | CLI mode for batch/automated processing (--cli) |
| ✅ | Rich-styled console menu with ASCII banner |
| ✅ | Configurable via bittytax.conf |
| 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) |
git clone <repository-url>
cd BittyTax
pip install -r requirements.txt
python main.pygit clone <repository-url>
cd BittyTax
pip3 install -r requirements.txt
python3 main.pypython main.py --cli path/to/transactions.xlsxBittyTax 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 |
| 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 |
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 stakingSettings 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 |
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 |
Process a transaction file directly from the command line:
python main.py --cli transactions.xlsxOutput includes capital gains summary: disposal count, total proceeds (GBP), total cost basis (GBP), and net gain/loss.
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 # Excel (.xlsx) and CSV read/write
├── gpu_manager.py # Configuration loader (bittytax.conf)
└── logger.py # Logging setup
What UK tax rules does this implement?
BittyTax implements the HMRC capital gains matching hierarchy for cryptoassets:
- Same-Day Rule (TCGA92 S105) — buys and sells on the same day are matched first
- Bed & Breakfast Rule — disposals matched against reacquisitions within 30 days
- Section 104 Pool — remaining disposals matched against the average cost pool
Can I use this for non-UK taxes?
The tool is primarily designed for UK HMRC rules (GBP-based, CGT matching hierarchy). However, the transaction processing, audit, and report generation are generic enough to be adapted for other jurisdictions by modifying the matching rules in detection/temporal.py.
What exchanges and wallets are supported?
BittyTax accepts any transaction data in the standard BittyTax record format (Excel or CSV). You can export from any exchange (Binance, Coinbase, Kraken, Ledger, Trezor, MetaMask, etc.) and convert to BittyTax format using the official bittytax_conv tool or manually.
Does it handle DeFi and NFTs?
Yes. The tool supports DeFi-specific transaction types including Stake, Unstake, Loan, Loan-Repayment, Fork, and Airdrop. NFT transactions can be recorded as standard Trade or Spend types with the NFT as the buy/sell asset.
Is the GBP price lookup automatic?
The core/inpainting.py module handles GBP valuation. If your records include "Value in GBP" columns, those are used directly. Missing values are filled via the configured price source (e.g., CoinGecko).
Can I generate a PDF tax report?
Yes. With reportlab installed, the tool can generate PDF reports containing capital gains summaries, disposal details, income breakdowns, and wallet audit results. Set output_format: pdf in configuration.
This software is provided for informational purposes only. It does NOT constitute tax, legal, or financial advice.
- Users should consult a qualified accountant or tax advisor for their specific tax obligations.
- The software is provided "as is" without warranties of any kind.
- Tax rules change — always verify calculations against current HMRC guidance.
- No data is shared with third parties. All processing is performed locally.
If BittyTax helps with your crypto taxes, please star the repo ⭐
No subscriptions. No data sharing. Open source forever.