crypto-pnl-tool

A local-first, auditable crypto profit & loss (P&L) and tax reporting tool supporting Coinbase, Kraken, and Binance US.

This project focuses on correctness, transparency, and explainability over black-box automation. All calculations are deterministic and reproducible, with tooling to audit cost basis, open lots, and tax outputs.

---

Features

Core Accounting

• FIFO cost basis engine (tested)
• Realized P&L calculation by pair and tax year
• Open-lot inspection (--open-lots)
• Fee-aware cost basis handling
• Cost basis overrides for self-custody transfers

Exchange Support

• Coinbase
• Kraken
• Binance US
• Incremental sync (only pulls new data after first run)
• Local SQLite database (no SaaS, no cloud dependency)

Reporting & Exports

• IRS Form 8949–style CSV exports
• Summary and detailed P&L exports
• TurboTax Online–compatible Universal CSV export
• Automatic TurboTax row splitting
• TurboTax preflight validation

---

Installation

git clone https://github.com/metalusmonk/crypto-pnl-tool.git
cd crypto-pnl-tool
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

For development and testing:

pip install -r requirements-dev.txt

---

Configuration

API keys are read from environment variables.

Example (macOS / Linux):

export COINBASE_API_KEY="..."
export COINBASE_SECRET="..."

export KRAKEN_API_KEY="..."
export KRAKEN_SECRET="..."

export BINANCEUS_API_KEY="..."
export BINANCEUS_SECRET="..."

You may also use a .env file (recommended).
Ensure .env is added to .gitignore.

---

Basic Usage

Sync all exchanges

python3 crypto_pnl_tool.py

Sync a single exchange

python3 crypto_pnl_tool.py -e coinbase

Skip syncing (use local DB only)

python3 crypto_pnl_tool.py --no-sync

---

Audit & Inspection Commands

List recent trades

python3 crypto_pnl_tool.py --list-trades --trade-limit 20 --no-sync

Inspect open FIFO lots for a pair

python3 crypto_pnl_tool.py --open-lots BTC/USD --no-sync

List deposits or withdrawals

python3 crypto_pnl_tool.py --list-deposits --no-sync
python3 crypto_pnl_tool.py --list-withdrawals --no-sync

---

Tax & Reporting

Export IRS 8949–style CSV

python3 crypto_pnl_tool.py --tax-year 2025 --export-8949 pnl_2025.csv

Export TurboTax Universal CSV (recommended for TurboTax Online)

python3 crypto_pnl_tool.py \
  --tax-year 2025 \
  --export-turbotax-universal turbotax_2025.csv \
  --no-sync

Handle TurboTax row limits (recommended)

TurboTax Online typically accepts ~2,250 rows per file.

python3 crypto_pnl_tool.py \
  --tax-year 2025 \
  --export-turbotax-universal turbotax_2025.csv \
  --turbotax-split \
  --turbotax-max-rows 500 \
  --no-sync

---

TurboTax Online (Important)

TurboTax Online has multiple crypto CSV import paths, and only one works with the Universal CSV generated by this tool.

➡️ You must select Raw transaction activity
❌ Do not select Gain/Loss or 1099-B import

Full step-by-step guide

See the dedicated guide:

👉 docs/turbotax.md

---

TurboTax Preflight Validation

Before uploading to TurboTax Online, validate the CSV locally:

python3 crypto_pnl_tool.py --validate-turbotax turbotax_2025.csv --no-sync

---

Testing

pytest

---

License

Apache License 2.0

---

Disclaimer

This tool is provided for informational and educational purposes only and does not constitute tax, legal, or financial advice.

---

Support the Project

If this tool saved you time, reduced stress, or helped you file crypto taxes with confidence,
consider supporting continued development.

Support is optional and never required.

• ⭐ Star the repository
• 🧡 Sponsor via GitHub Sponsors
• 💸 Optional crypto donation (ETH): 0xFaD5D317BBa40C2667F6455e2e9641CCe6131758 Thank you for using and trusting this project.