A Golang program to process Bitcoin transaction statements from Fold and calculate the Optimized HIFO (Highest In, First Out) cost basis for tax reporting purposes.

For accurate HIFO calculations, it is highly recommended to include ALL transaction history from Fold. The HIFO algorithm requires complete transaction history to properly:

• Build accurate tax lot inventory from all purchases and deposits
• Calculate correct cost basis using the highest-cost lots first
• Handle withdrawals that reduce lot quantities without creating taxable events
• Ensure chronological integrity (sales can only use lots acquired before the sale date)

Even if you're only generating a tax report for 2025, include transaction files from 2022, 2023, and 2024 for the most accurate calculations.

• Tax-Optimized HIFO Algorithm: Prioritizes long-term capital gains (>1 year) then highest-cost lots to minimize tax liability
• Short-Term vs Long-Term Separation: Automatically categorizes and reports gains separately per IRS requirements
• Multi-Year Processing: Processes all historical transactions but reports on specific tax years
• Form 8949 Compliant Output: Generates properly structured CSV files for direct IRS tax form preparation
• Beautiful Terminal Display: Separate tables for short-term and long-term sales with color-coded gains/losses
• Historical Price Integration: Automatically fetches missing Bitcoin prices from mempool.space API
• Modular Architecture: Clean separation of concerns with dedicated modules for parsing, calculations, and display
• Precise Monetary Calculations: Uses go-money library for exact decimal arithmetic avoiding floating-point errors

# Clone or download the project
cd hi-fold

# Install dependencies
go mod tidy

# Build the binary
go build -o hi-fold .

./hi-fold [flags]

Flags:
  -h, --help             help for hi-fold
  -i, --input strings    Input CSV files (can specify multiple, required)
      --mempool-url      Custom mempool API base URL (default: mempool.space)  
  -m, --mock-prices      Use mock prices instead of API for testing
  -o, --output string    Output CSV file (default: tax-records-{year}.csv)
  -y, --year int         Tax year to calculate (default: previous year)

# Calculate cost basis for 2025 with single file
./hi-fold --year 2025 --input fold-history-2025.csv

# Custom output file
./hi-fold --year 2025 --input transactions.csv --output my-tax-records.csv

# Use mock prices for testing (offline mode)
./hi-fold --year 2025 --input transactions.csv --mock-prices

The program supports processing multiple CSV files simultaneously with automatic deduplication:

# Process multiple files with repeated flags
./hi-fold --year 2025 --input jan-2025.csv --input feb-2025.csv --input mar-2025.csv

# Process multiple files with comma-separated syntax
./hi-fold --year 2025 --input jan-2025.csv,feb-2025.csv,mar-2025.csv

# Use glob patterns to match multiple files automatically
./hi-fold --year 2025 --input "fold-*.csv"

# More specific glob patterns
./hi-fold --year 2025 --input "fold-*-202[45].csv"

# Example with complete history for accurate HIFO calculations
./hi-fold --year 2025 --input fold-2022.csv,fold-2023.csv,fold-2024.csv,fold-2025.csv

• Glob pattern support: Use wildcards like *.csv or fold-*-20*.csv to match multiple files automatically
• Automatic deduplication: Transactions with duplicate Reference IDs are detected and skipped
• Chronological sorting: All transactions are sorted by date after merging
• File validation: Each input file is checked for existence before processing
• Progress reporting: Shows processing status and duplicate detection results

The program automatically fetches historical Bitcoin prices from mempool.space API for transactions missing price data, ensuring accurate cost basis calculations. Use the --mock-prices flag for testing without API calls.

You can configure a custom mempool.space API base URL using the --mempool-url flag:

# Use a custom mempool.space instance (domain only)
./hi-fold --year 2025 --input transactions.csv --mempool-url "custom.mempool.space"

# Use a full URL with HTTPS protocol
./hi-fold --year 2025 --input transactions.csv --mempool-url "https://my-mempool-server.com"

# Use HTTP protocol (not recommended for production)
./hi-fold --year 2025 --input transactions.csv --mempool-url "http://localhost:3006"

# Use IP address with custom port
./hi-fold --year 2025 --input transactions.csv --mempool-url "192.168.1.100:8080"

The URL normalization automatically handles:

• Domain-only or IP address with port (adds https:// prefix)
• Full URL with protocol (used as-is)
• Trailing slash removal for consistency

The program expects CSV files exported from Fold with the following format:

• Account information in the first 3 rows
• Transaction header row starting with "Reference ID"
• Transaction data with columns: Reference ID, Date (UTC), Transaction Type, Description, Asset, Amount (BTC), Price per Coin (USD), Subtotal (USD), Fee (USD), Total (USD), Transaction ID

The program generates two types of output with proper short-term vs long-term capital gains separation:

• Overall Summary Table: Total sales, proceeds, cost basis, and gain/loss for the target year
• Short-Term Sales Details: Separate table for sales of Bitcoin held ≤1 year with totals
• Long-Term Sales Details: Separate table for sales of Bitcoin held >1 year with totals
• Holdings Details: Current Bitcoin holdings with acquisition dates and cost basis
• Holdings Summary: Net position, average price, and unrealized gains/losses

The CSV file is structured for direct IRS Form 8949 compliance with proper separation:

• Short-Term Section: "Form 8949 Part I" transactions with summary totals
• Long-Term Section: "Form 8949 Part II" transactions with summary totals
• Individual Tax Lots: Each sale broken down by the specific lots used (HIFO prioritized)
• Holding Period Compliance: Automatically categorizes based on >1 year vs ≤1 year holding periods

CSV Structure:

• Section headers for short-term and long-term capital gains
• Individual lot records: Description, Date Acquired, Date Sold, Proceeds, Cost Basis, Gain/Loss
• Summary totals for each section

The program displays two important but different metrics in the Holdings Summary:

This represents your actual Bitcoin balance - the simple mathematical sum of all Bitcoin transactions that have affected your wallet balance. It includes:

• ✅ Purchases (positive amounts)
• ✅ Deposits/Receives (positive amounts)
• ✅ Sales (negative amounts)
• ✅ Withdrawals (negative amounts)

Example: If you bought 1.0 BTC, received 0.5 BTC, sold 0.3 BTC, and withdrew 0.8 BTC, your Net BTC Position would be: 1.0 + 0.5 - 0.3 - 0.8 = 0.4 BTC

This represents the Bitcoin amounts that are still available for tax lot tracking and cost basis calculations. This number excludes Bitcoin that has been withdrawn from the exchange because:

1. Withdrawn Bitcoin cannot be sold from the exchange (it's no longer in your exchange account)
2. Tax lots track what you can sell for capital gains calculations
3. HIFO processing only applies to tradeable assets still under exchange custody

Key Difference: Withdrawals reduce your Net BTC Position (because you no longer own that Bitcoin in that account) but don't affect tax lot calculations for the remaining Bitcoin you can still trade.

• Net BTC Position: Your actual Bitcoin ownership across all transactions
• Remaining Holdings: Only the Bitcoin still available for trading and tax lot calculations

Real-world analogy: Think of it like a bank account. If you deposit $1000, withdraw $300 in cash, your account balance is $700 (like Net BTC Position). But if you want to calculate interest on money still in the bank, you only count the $700 remaining (like Remaining Holdings).

• Net BTC Position: Useful for understanding your total Bitcoin exposure
• Remaining Holdings: What matters for future capital gains calculations when you sell from the exchange

The program implements the Optimized HIFO (Highest In, First Out) method - a tax optimization strategy that prioritizes long-term capital gains and sells the highest-cost Bitcoin lots first to minimize overall tax liability.

1. Long-Term HIFO First: Prioritizes selling lots held for more than 1 year (long-term capital gains rates)
2. Short-Term HIFO Second: Within each category, sells highest-cost lots first
3. Holding Period Calculation: Uses the exact date difference to determine short-term (≤1 year) vs long-term (>1 year)

1. Multi-Year Processing: Processes ALL transactions chronologically to build complete lot inventory
2. Lot Creation: Each purchase/deposit creates a tax lot with acquisition date, amount, and cost basis
3. Optimal Tax Matching: When selling, prioritizes long-term gains first, then highest cost within each category
4. Withdrawal Handling: Withdrawals reduce lot quantities without creating taxable events
5. Year-Specific Reporting: Only sales from the target year appear in output

• Long-Term Gain Prioritization: Automatically prioritizes favorable long-term capital gains tax rates
• Precise Calculations: Uses go-money library to avoid floating-point precision errors
• Chronological Integrity: Sales can only use lots acquired before the sale date
• Lot Splitting: Supports partial lot sales with accurate remaining quantities
• Complete History Required: Processes all years to ensure accurate cost basis calculations

The program follows IRS regulations for capital gains reporting with proper holding period compliance:

• Part I (Short-Term): Capital gains/losses for assets held ≤1 year
• Part II (Long-Term): Capital gains/losses for assets held >1 year
• Automatic Categorization: Uses exact date calculations for holding period determination
• Individual Lot Reporting: Each tax lot reported separately as required

• IRS Form 8949 (Sales and Other Dispositions of Capital Assets)
• Schedule D (Capital Gains and Losses)
• Popular tax software (TurboTax, FreeTaxUSA, etc.)

This section shows a complete example of processing multiple files and the resulting output.

# Process complete transaction history for accurate HIFO calculations using glob patterns
./hi-fold --year 2025 --input "fold-*.csv"

# Alternative: specify files explicitly
./hi-fold --year 2025 --input fold-2024.csv,fold-2025.csv

Using mempool.space API for historical prices
Processing file 1/2: fold-bitcoin-transaction-history-2024.csv
  Loaded 23 transactions (0 duplicates skipped)
Processing file 2/2: fold-bitcoin-transaction-history-2025.csv
  Loaded 82 transactions (0 duplicates skipped)
Loaded 105 unique transactions from 2 file(s)


 Bitcoin HIFO Cost Basis Report - 2025


┌────────────────┬───────────┐
│     Metric     │   Value   │
├────────────────┼───────────┤
│Total Sales     │         28│
│Total Proceeds  │$119,821.31│
│Total Cost Basis│$122,268.38│
│Total Gain/Loss │ -$2,447.07│
└────────────────┴───────────┘

 Sales Details
┌──────────┬────────────┬────────────┬──────────────┬───────────┬─────────────┐
│Date Sold │Amount (BTC)│Proceeds ($)│Cost Basis ($)│ Price/BTC │Gain/Loss ($)│
├──────────┼────────────┼────────────┼──────────────┼───────────┼─────────────┤
│2025-02-01│ 0.02473770₿│   $2,501.05│     $2,644.38│$101,102.77│     -$143.33│
│2025-02-03│ 0.01115567₿│   $1,041.77│     $1,048.86│ $93,394.00│       -$7.09│
│2025-02-14│ 0.01000000₿│     $945.46│     $1,045.46│ $94,546.00│     -$100.00│
...
└──────────┴────────────┴────────────┴──────────────┴───────────┴─────────────┘

Remaining Holdings

┌─────────────┬────────────┬──────────────┬───────────┐
│Date Acquired│Amount (BTC)│Cost Basis ($)│ Price/BTC │
├─────────────┼────────────┼──────────────┼───────────┤
│ 2024-10-30  │ 0.01718401₿│     $1,250.00│ $72,742.04│
│ 2025-02-28  │ 0.03675968₿│     $3,000.00│ $81,611.15│
│ 2025-03-19  │ 0.00299466₿│       $250.00│ $83,481.93│
...
└─────────────┴────────────┴──────────────┴───────────┘

┌────────────────────┬───────────┐
│  Holdings Summary  │   Value   │
├────────────────────┼───────────┤
│Net BTC Position    │0.12345678₿│
│Average BTC Price   │ $84,210.45│
│Total Cost Basis    │ $10,396.35│
│Current BTC Price   │$111,111.00│
│Current Value       │ $13,717.41│
│Unrealized Gain/Loss│  $3,321.06│
└────────────────────┴───────────┘

Description,Date Acquired,Date Sold,Proceeds,Cost Basis,Gain/Loss
0.01115567 BTC,12/15/2024,02/03/2025,1041.77,1048.86,-7.09
0.01000000 BTC,12/15/2024,02/14/2025,945.46,1045.46,-100.00

Terminal Sales Details (aggregated per transaction):

2025-03-15 | 0.50000000₿ | $45,000.00 | $42,000.00 | $90,000.00 | $3,000.00

CSV Output (individual tax lots from same transaction):

0.30000000 BTC, 2024-01-15, 2025-03-15, $27,000.00, $24,000.00, $3,000.00
0.20000000 BTC, 2024-02-20, 2025-03-15, $18,000.00, $18,000.00, $0.00

The terminal shows aggregated sales, while the CSV shows individual tax lot breakdowns required for Form 8949.

The application is organized into focused modules:

• main.go: CLI interface and application coordination
• models.go: Data structures (Transaction, Lot, Sale, etc.) and helper functions
• csv.go: CSV parsing and tax record generation
• hifo.go: Core HIFO algorithm implementation and lot matching logic
• display.go: Terminal output formatting and styled table rendering

• go-money - Precise monetary calculations with 8-decimal BTC support
• Cobra - CLI framework and command handling
• Lipgloss - Terminal styling and table formatting
• Fang - Enhanced CLI execution

This software is provided for informational purposes only and should not be considered tax advice. Always consult with a qualified tax professional for your specific situation. Verify all calculations before filing tax returns.