fetch_tx_details/README.md

# Bitcoin Transaction Forensic Analyzer v2.0

A comprehensive Python tool for forensic analysis of Bitcoin transactions with advanced change address detection using probabilistic heuristics.

## Overview

This tool performs in-depth forensic analysis of Bitcoin transactions by:
- Fetching comprehensive transaction data from mempool APIs
- Applying multiple heuristics to identify likely change addresses
- Generating detailed forensic reports with probability assessments
- Providing network context and spending status analysis

## Features

### Core Analysis
- **Multi-heuristic change detection**: Combines 7+ different analytical approaches
- **Probabilistic scoring**: Uses weighted feature analysis instead of arbitrary point systems
- **Comprehensive data collection**: Fetches from multiple API endpoints
- **Network context awareness**: Incorporates current fee environment and mempool state

### Heuristics Implemented
1. **Round Number Analysis**: Identifies payment patterns vs precise change amounts
2. **Address History Analysis**: Examines address reuse patterns and transaction frequency
3. **Relative Value Analysis**: Compares output values and percentages
4. **Positional Pattern Analysis**: Considers wallet-specific change placement strategies
5. **Script Type Analysis**: Checks for address type consistency across inputs/outputs
6. **Fee Context Analysis**: Evaluates transaction urgency and batching patterns
7. **Address Type Reuse**: Determines if outputs match input address types

### Output Features
- Detailed probability assessments with confidence levels
- Comprehensive transaction breakdown
- Spending status tracking
- RBF (Replace-by-Fee) history analysis
- Raw transaction data preservation
- Feature contribution breakdown for each heuristic

## Requirements

### System Requirements
- Python 3.7 or higher
- Internet connection for API access
- ~50MB available disk space

### Python Dependencies
```
requests>=2.25.0
```

### API Access
- Requires access to a mempool.space-compatible API
- Default configuration uses `mempool.mikoshi.de`
- No API key required for basic usage

## Installation

1. **Clone or download** the script file
2. **Install dependencies**:
   ```bash
   pip install requests
   ```
3. **Verify setup**:
   ```bash
   python btc_forensic.py --help
   ```

## Usage

### Basic Usage
```bash
python btc_forensic.py input_file.txt output_report.txt
```

### Command Line Options
```bash
python btc_forensic.py [options] input_file output_file

Required Arguments:
  input_file    Path to text file containing transaction IDs (one per line)
  output_file   Path where forensic report will be saved

Optional Arguments:
  -h, --help           Show help message
  -v, --verbose        Enable verbose output during processing
  -d DELAY, --delay    Delay between API requests in seconds (default: 0.1)
```

### Input File Format
Create a text file with one transaction ID per line:
```
15e10745f15593a899cef391191bdd3d7c12412cc4696b7bcb669d0feadc8521
dba43fd04b7ae3df8e5b596f2e7fab247c58629d622e3a5213f03a5a09684430
# Comments starting with # are ignored
c4e53c2e37f4fac759fdb0d8380e4d49e6c7211233ae276a44ce7074a1d6d168
```

### Example Usage
```bash
# Basic analysis
python btc_forensic.py transactions.txt forensic_report.txt

# Verbose output with custom delay
python btc_forensic.py -v -d 0.2 suspicious_txs.txt detailed_report.txt
```

## Understanding the Output

### Change Address Analysis
The script provides probability assessments for each output:
- **Probability > 70%**: Likely change address
- **Probability 50-70%**: Possible change address  
- **Probability 30-50%**: Uncertain classification
- **Probability < 30%**: Likely payment address

### Confidence Levels
- **HIGH**: Strong evidence supporting the assessment
- **MEDIUM**: Moderate evidence, some uncertainty
- **LOW**: Weak evidence, high uncertainty

### Feature Breakdown
Each output analysis includes detailed reasoning showing:
- Individual heuristic scores and contributions
- Weighted feature analysis
- Specific evidence found (round numbers, address history, etc.)

## Technical Details

### API Endpoints Used
- `/api/tx/{txid}` - Basic transaction data
- `/api/tx/{txid}/outspends` - Spending status
- `/api/v1/tx/{txid}/rbf` - RBF history
- `/api/tx/{txid}/hex` - Raw transaction data
- `/api/address/{address}` - Address statistics
- `/api/address/{address}/txs` - Address transaction history
- `/api/mempool` - Current mempool state
- `/api/v1/fees/recommended` - Fee recommendations

### Scoring Algorithm
The probabilistic model uses weighted feature combination:
1. Each heuristic produces a score (-1.0 to +1.0)
2. Scores are weighted by empirical effectiveness
3. Combined score is normalized using sigmoid function
4. Result is converted to probability percentage

### Rate Limiting
- Default 100ms delay between requests
- Configurable via `--delay` parameter
- Designed to be respectful of API resources

## Limitations and Considerations

### Analytical Limitations
- **Heuristic-based**: Not 100% accurate, provides probability estimates
- **Privacy techniques**: May be less effective against advanced privacy wallets
- **Exchange transactions**: Complex batching patterns may confuse analysis
- **Network conditions**: Accuracy may vary based on fee environment

### Technical Limitations
- **API dependency**: Requires reliable internet connection
- **Rate limits**: May need adjustment for different API providers
- **Memory usage**: Large transaction sets may require significant RAM

### Legal and Ethical Considerations
- **Intended for legitimate forensic analysis only**
- **Compliance**: Ensure usage complies with local laws and regulations
- **Privacy**: Be mindful of privacy implications when analyzing transactions
- **Data handling**: Secure storage and handling of forensic reports required

## Troubleshooting

### Common Issues

**"Network error fetching data"**
- Check internet connection
- Verify API endpoint is accessible
- Try increasing delay with `--delay` parameter

**"No valid transaction IDs found"**
- Verify input file format (one TXID per line)
- Check for proper 64-character hex transaction IDs
- Ensure file encoding is UTF-8

**"Could not retrieve base transaction data"**
- Transaction may not exist or be too recent
- API may be temporarily unavailable
- Try with a known valid transaction ID

**High memory usage**
- Process smaller batches of transactions
- Monitor system resources during execution
- Consider running analysis in segments

### Performance Optimization
- Use appropriate `--delay` setting for your network
- Process transactions in smaller batches for large datasets
- Monitor API response times and adjust accordingly

## Version History

### v2.0 (Current)
- Advanced probabilistic change detection
- Multi-heuristic analysis framework
- Comprehensive forensic reporting
- Network context awareness
- Enhanced API utilization

### v1.0 (Legacy)
- Basic change detection using simple heuristics
- Limited API endpoint usage
- Basic reporting functionality

## Support and Contributing

### Reporting Issues
When reporting issues, please include:
- Python version and operating system
- Complete error messages
- Sample transaction IDs (if not sensitive)
- Command line arguments used

### Best Practices
- Test with known transactions before production use
- Validate results against other analytical tools
- Keep transaction ID lists organized and documented
- Regularly update the script for new features

## Disclaimer

This tool is provided for educational and legitimate forensic analysis purposes only. Users are responsible for ensuring compliance with applicable laws and regulations. The probabilistic nature of the analysis means results should be considered as investigative leads rather than definitive conclusions.

Accuracy of change address detection varies based on wallet software, transaction patterns, and other factors. Always corroborate findings with additional analytical techniques and evidence.