sol-key-seed-scan

Derive Solana private keys from BIP39 seed phrases, scan derived addresses for on-chain activity, and export the results to CSV or Excel.

Features

• BIP39 Seed Phrase Validation -- Supports 12, 15, 18, 21, and 24-word mnemonics with checksum verification
• BIP44 Solana Key Derivation -- Derives Ed25519 keypairs using SLIP-0010 with coin type 501
• Multiple Derivation Paths -- Supports Phantom, Solflare, Ledger, and Trust Wallet path conventions
• On-Chain Scanning -- Queries Solana RPC for balance, transaction count, and transaction date range
• Gap Limit Algorithm -- Stops scanning after N consecutive unused addresses (configurable, default 20)
• CSV & Excel Export -- Formatted output with clickable Solscan explorer links in Excel
• Async & Rate-Limited -- Efficient RPC querying with configurable rate limiting and retry logic

Requirements

• Python 3.9+
• Dependencies listed in requirements.txt

Installation

# Clone the repository
git clone https://github.com/CreativeSkyAI/sol-key-seed-scan.git
cd sol-key-seed-scan

# Create a virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # Linux/macOS
# venv\Scripts\activate   # Windows

# Install dependencies
pip install -r requirements.txt

Quick Start

1. Copy environment files:

   cp .env.example .env
   cp seeds.env.example seeds.env

2. Edit seeds.env with your seed phrases:

   SEED_PHRASE_1="your twelve word seed phrase goes here in this field now"
   

3. Run the scanner:

   python -m app.main

Usage

# Scan a single seed phrase
python -m app.main --seed "word1 word2 word3 ... word12"

# Scan from a seeds file
python -m app.main --seed-file seeds.env

# Export as Excel with debug logging
python -m app.main --format xlsx --debug

# Use a custom config file
python -m app.main --config path/to/config.json

# Show help
python -m app.main --help

Windows

.\run_scanner.ps1 --format xlsx

Configuration

Configuration is stored in config/config.json. A default config is auto-created on first run if missing.

Config Fields

{
  "api_keys": {
    "solana_rpc": ""
  },
  "scan_settings": {
    "derivation_paths": [
      "m/44'/501'/x'/0'",
      "m/44'/501'/0'/0'/x'",
      "m/44'/501'/x'"
    ],
    "gap_limit": 20,
    "batch_size": 5,
    "check_balance": true,
    "check_transactions": true,
    "include_private_keys": false
  },
  "output_settings": {
    "fields": ["path", "index", "used", "balance", "..."],
    "mask_private_keys": true,
    "show_only_used_addresses": false,
    "output_dir": "results",
    "output_path": "results/scan",
    "format": "csv"
  }
}

Field	Description
solana_rpc	Solana RPC endpoint URL. Defaults to public mainnet-beta. Use a dedicated provider (Helius, QuickNode) for production.
derivation_paths	BIP44 path templates. x is replaced with the address index.
gap_limit	Stop scanning after this many consecutive unused addresses.
check_balance	Query SOL balance for each address.
check_transactions	Query transaction history for each address.
include_private_keys	Include private keys in output (use with caution).
mask_private_keys	Partially mask private keys in output.
show_only_used_addresses	Only export addresses with activity.

Environment Variables

Variable	Description
SOLANA_RPC_URL	Overrides api_keys.solana_rpc in config.

Derivation Paths

Path	Wallets
m/44'/501'/x'/0'	Phantom, Sollet, Ledger (account-level)
m/44'/501'/0'/0'/x'	Sub-account index variation
m/44'/501'/x'	Solflare, Trust Wallet, Solana CLI

All path components are automatically promoted to hardened derivation as required by Ed25519 SLIP-0010.

Output

Results are saved to the results/ directory with timestamped filenames.

CSV Output

Standard comma-separated values file with headers.

Excel Output

Formatted workbook with:

• Color-coded headers
• Auto-sized columns
• Clickable Solscan explorer links
• Color-coded "Used" column (green = active, red = inactive)
• Frozen header row

Output Fields

Field	Description
path	Full derivation path used
index	Address index within the path
used	Whether the address has any on-chain activity
balance	Current SOL balance
transaction_count	Total number of transactions
first_tx_date	Date of earliest transaction
last_tx_date	Date of most recent transaction
explorer_url	Link to Solscan block explorer
address	Base58-encoded Solana address
private_key	Private key (if include_private_keys is true)
seed_phrase	Source seed phrase (if include_private_keys is true)

Security

• Never share your seed phrases or private keys.
• The include_private_keys option is disabled by default.
• When enabled, mask_private_keys partially redacts keys in output.
• Seed phrases are never logged at INFO level.
• Store seeds.env securely and never commit it to version control (it is in .gitignore).
• Consider using a dedicated RPC endpoint for production to avoid rate limiting.

Testing

python -m pytest tests/ -v

License

MIT License - see LICENSE for details.