Marius Mutu
51c9202556
- Bitcoin and Ethereum address tracking - Identifies first purchase from exchanges - Interactive CLI mode with historical price lookup links - Test suite with public addresses - Documentation for Claude Code 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
73 lines
2.9 KiB
Markdown
73 lines
2.9 KiB
Markdown
# 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
|