Chainalysis Sanctions Checker

A Python script that checks cryptocurrency wallet addresses against international sanctions lists using the Chainalysis Sanctions Screening API.

Overview

This tool reads a CSV file containing cryptocurrency wallet addresses (Bitcoin, Ethereum, etc.) and queries the Chainalysis API to determine whether each address is associated with an entity on an international sanctions list. It's useful for compliance checks, due diligence, and risk assessment in cryptocurrency transactions.

Features

• ✅ Multi-format CSV support: Works with both headerless CSV files and CSV files with an "address" column
• ✅ Rate limiting: Built-in throttling to respect API limits (5000 requests per 5-minute window)
• ✅ Error handling: Graceful handling of network errors, invalid addresses, and API issues
• ✅ Detailed output: Results include sanctioned status and raw identification details
• ✅ Progress tracking: Real-time progress display during processing

Prerequisites

• Python 3.8+
• Chainalysis Sanctions API key (free tier available)

Installation

1. Clone the repository

git clone <your-repo-url>
cd sanctions_python_script

2. Set up Python virtual environment

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate  # On macOS/Linux
# OR
venv\Scripts\activate     # On Windows

3. Install dependencies

pip install -r requirements.txt

4. Configure your Chainalysis API key

1. Visit Chainalysis and sign up for API access
2. Request a free Sanctions API key
3. Create your .env file:

   # Copy the example file
   cp .env.example .env
   
   # Edit .env and replace with your actual API key
   # CHAINALYSIS_API_KEY=your_actual_api_key_here

Usage

Basic Usage

python main.py --input bitcoin_addresses.csv --output results.csv

Command Line Options

• --input (required): Path to input CSV file containing addresses
• --output (optional): Path for output CSV file (default: results.csv)
• --sleep (optional): Seconds to sleep between requests (default: 0.1)

Examples

Check addresses with custom output file:

python main.py --input my_addresses.csv --output compliance_check.csv

Slower rate limiting (useful for large batches):

python main.py --input addresses.csv --sleep 0.5

Input Format

The script supports two CSV input formats:

Format 1: CSV with header

address
12QtD5BFwRsdNsAZY76UVE1xyCGNTojH9h
12dayySNfXKVbnShZjuUzQdd9gJouG7Nt1
1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2

Format 2: Headerless CSV (one address per line)

12QtD5BFwRsdNsAZY76UVE1xyCGNTojH9h
12dayySNfXKVbnShZjuUzQdd9gJouG7Nt1
1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2

Output Format

The script generates a CSV with three columns:

Column	Description
address	The cryptocurrency address that was checked
is_sanctioned	True if sanctioned, False if clear, error if lookup failed
details	Raw JSON identifications array or error message

Example Output

address,is_sanctioned,details
12QtD5BFwRsdNsAZY76UVE1xyCGNTojH9h,False,[]
1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2,True,"[{'category': 'sanctions', 'name': 'Entity Name'}]"
invalid_address,error,Request error: Invalid address format

API Information

• Endpoint: https://public.chainalysis.com/api/v1/address/{address}
• Authentication: X-API-Key header
• Rate Limit: 5000 requests per 5-minute window
• Supported Networks: Bitcoin, Ethereum, and other major cryptocurrencies

Project Structure

sanctions_python_script/
├── main.py                 # Main script
├── bitcoin_addresses.csv   # Sample input file
├── requirements.txt        # Python dependencies
├── .env.example           # Environment variables template
├── .gitignore             # Git ignore rules
├── .trufflehogignore      # TruffleHog ignore rules
└── README.md              # This file

Error Handling

The script handles various error conditions:

• Invalid API key: Returns clear error message
• Rate limiting: Automatic throttling to stay within limits
• Network errors: Graceful handling with error reporting
• Invalid addresses: Marked as errors in output
• Empty CSV files: Validation with helpful error messages

Development

Running Tests

# Test with a small sample first
python main.py --input bitcoin_addresses.csv --output test_results.csv

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Security

• ⚠️ Never commit your API key to version control
• ✅ Use the .env file for sensitive data (already excluded in .gitignore)
• ✅ Copy .env.example to .env and add your actual API key
• ✅ The .gitignore file excludes .env and other sensitive files
• ✅ TruffleHog configuration prevents secret commits

License

This project is provided as-is for educational and compliance purposes. Please ensure you comply with Chainalysis's API terms of service.

Support

For issues related to:

• API access: Contact Chainalysis support
• Script functionality: Open an issue in this repository
• Rate limiting: Adjust the --sleep parameter or contact Chainalysis about higher limits

Disclaimer

This tool is for informational purposes only. Always verify results through official channels and consult with legal experts for compliance decisions.