crypto-tracker/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

A Python tool that tracks Bitcoin and Ethereum addresses to identify the first cryptocurrency purchase - essential for Romanian crypto tax calculations. The tool analyzes blockchain transactions backward in time to find when crypto was first acquired from an exchange.

Architecture

Single-file application (crypto_tracker.py) with one main class:

• CryptoTracker: Core class handling both BTC and ETH tracking
  • track_bitcoin_address(): Uses blockchain.info API (no API key required)
  • track_ethereum_address(): Uses Etherscan API (optional API key)
  • _check_exchange(): Matches addresses against known exchange wallets
  • _display_bitcoin_results() / _display_ethereum_results(): Formatted output
  • main(): Interactive CLI entry point

Data flow: User address → API fetch → Parse transactions (oldest first) → Identify exchange sources → Display first purchase with date/amount/hash

Development Commands

Run interactive mode

python crypto_tracker.py

Run tests (with public addresses)

python test_tracker.py

Install dependencies

pip install -r requirements.txt
# or simply:
pip install requests

Key Implementation Details

Bitcoin tracking:

• Uses blockchain.info free API (https://blockchain.info/rawaddr/{address})
• Hardcoded list of known exchange addresses in known_exchanges dict
• Processes transactions in reverse chronological order to find oldest first
• Converts satoshi to BTC (÷ 100,000,000)

Ethereum tracking:

• Uses Etherscan API (https://api.etherscan.io/api)
• Free tier: 5 requests/second without API key
• Converts wei to ETH (÷ 10^18)
• Manual verification required for exchange detection (Etherscan address tags)

Exchange detection:

• Bitcoin: Direct address matching against known_exchanges dictionary
• Ethereum: Flagged for manual review (addresses should be checked on Etherscan for exchange tags)

Extending the Codebase

Adding new exchanges: Update known_exchanges dict in __init__() with exchange name as key and list of known wallet addresses as value.

Adding new blockchains: Follow the pattern of track_bitcoin_address() / track_ethereum_address() - create new method, fetch transactions via blockchain API, parse chronologically, identify exchange markers.

Testing: test_tracker.py uses public addresses (Genesis block for BTC, Ethereum Foundation for ETH) to verify API connectivity and parsing logic.

Important Constraints

• Read-only operation: No private keys, no transactions sent
• Rate limits: Ethereum API limited to 5 req/sec without key
• Exchange detection limitations: Only major exchanges in Bitcoin; Ethereum requires manual verification
• Not for privacy coins: Only supports transparent blockchain analysis