# 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](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
```bash
python crypto_tracker.py
```

### Run tests (with public addresses)
```bash
python test_tracker.py
```

### Install dependencies
```bash
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](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