0
# Cryptocurrency Address Validation
1

2
Validators for blockchain addresses across major cryptocurrency networks. These validators implement network-specific address formats, checksums, and encoding schemes to ensure valid cryptocurrency addresses.
3

4
## Capabilities
5

6
### Bitcoin Address Validation
7

8
Validates Bitcoin addresses including legacy, SegWit, and Bech32 formats.
9

10
```python { .api }
11
def btc_address(value: str, /) -> Union[Literal[True], ValidationError]:
12
    """
13
    Validate Bitcoin addresses across all supported formats.
14
    
15
    Parameters:
16
    - value: Bitcoin address string to validate
17
    
18
    Returns:
19
    True if valid Bitcoin address, ValidationError otherwise
20
    
21
    Supported formats:
22
    - P2PKH (Pay-to-Public-Key-Hash): starts with '1'
23
    - P2SH (Pay-to-Script-Hash): starts with '3'  
24
    - Bech32 (SegWit): starts with 'bc1'
25
    
26
    Validates:
27
    - Address format and length
28
    - Base58 encoding (for legacy addresses)
29
    - Bech32 encoding (for SegWit addresses)
30
    - Checksum verification
31
    """
32
```
33

34
### Ethereum Address Validation
35

36
Validates Ethereum addresses with ERC-55 mixed-case checksum support.
37

38
```python { .api }
39
def eth_address(value: str, /) -> Union[Literal[True], ValidationError]:
40
    """
41
    Validate Ethereum addresses with optional ERC-55 checksum.
42
    
43
    Parameters:
44
    - value: Ethereum address string to validate
45
    
46
    Returns:
47
    True if valid Ethereum address, ValidationError otherwise
48
    
49
    Validates:
50
    - Length: exactly 42 characters (including 0x prefix)
51
    - Format: 0x followed by 40 hexadecimal characters
52
    - ERC-55 checksum: mixed-case checksum validation when present
53
    
54
    Accepts both checksummed and non-checksummed addresses.
55
    Requires 'validators[crypto-eth-addresses]' for advanced validation.
56
    """
57
```
58

59
### Binance Smart Chain Address Validation
60

61
Validates Binance Smart Chain (BSC) addresses.
62

63
```python { .api }
64
def bsc_address(value: str, /) -> Union[Literal[True], ValidationError]:
65
    """
66
    Validate Binance Smart Chain addresses.
67
    
68
    Parameters:
69
    - value: BSC address string to validate
70
    
71
    Returns:
72
    True if valid BSC address, ValidationError otherwise
73
    
74
    BSC addresses follow Ethereum address format:
75
    - Length: exactly 42 characters (including 0x prefix)
76
    - Format: 0x followed by 40 hexadecimal characters
77
    - Compatible with ERC-55 checksum validation
78
    
79
    BSC is EVM-compatible, so addresses use same format as Ethereum.
80
    """
81
```
82

83
### Tron Address Validation
84

85
Validates Tron (TRX) addresses with base58 encoding and checksum verification.
86

87
```python { .api }
88
def trx_address(value: str, /) -> Union[Literal[True], ValidationError]:
89
    """
90
    Validate Tron (TRX) addresses.
91
    
92
    Parameters:
93
    - value: Tron address string to validate
94
    
95
    Returns:
96
    True if valid Tron address, ValidationError otherwise
97
    
98
    Validates:
99
    - Format: starts with 'T' followed by 33 base58 characters
100
    - Length: exactly 34 characters total
101
    - Base58 encoding validation
102
    - Address checksum verification using double SHA-256
103
    
104
    Tron addresses use base58 encoding similar to Bitcoin but with different prefixes.
105
    """
106
```
107

108
## Usage Examples
109

110
```python
111
import validators
112

113
# Bitcoin address validation
114
validators.btc_address('1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa')      # True (P2PKH)
115
validators.btc_address('3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy')      # True (P2SH)
116
validators.btc_address('bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4')  # True (Bech32)
117

118
# Invalid Bitcoin addresses
119
validators.btc_address('1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNb')      # ValidationError (bad checksum)
120
validators.btc_address('not-a-bitcoin-address')                    # ValidationError
121

122
# Ethereum address validation
123
validators.eth_address('0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed')  # True (checksummed)
124
validators.eth_address('0x5aaeb6053f3e94c9b9a09f33669435e7ef1beaed')  # True (lowercase)
125
validators.eth_address('0x5AAEB6053F3E94C9B9A09F33669435E7EF1BEAED')  # True (uppercase)
126

127
# Invalid Ethereum addresses
128
validators.eth_address('5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed')   # ValidationError (no 0x prefix)
129
validators.eth_address('0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeA')    # ValidationError (too short)
130

131
# BSC address validation (same format as Ethereum)
132
validators.bsc_address('0x10ED43C718714eb63d5aA57B78B54704E256024E')  # True
133
validators.bsc_address('0x10ed43c718714eb63d5aa57b78b54704e256024e')  # True
134

135
# Tron address validation
136
validators.trx_address('TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH')        # True
137
validators.trx_address('TMuA6YqfCeX8EhbfYEg5y7S4DqzSJireY9')        # True
138

139
# Invalid Tron addresses
140
validators.trx_address('TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZY')         # ValidationError (too short)
141
validators.trx_address('BLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH')        # ValidationError (wrong prefix)
142
```
143

144
## Advanced Usage
145

146
### Multi-Network Address Validation
147

148
```python
149
import validators
150

151
def validate_crypto_address(address: str, network: str) -> bool:
152
    """Validate cryptocurrency address for specific network."""
153
    
154
    network_validators = {
155
        'bitcoin': validators.btc_address,
156
        'ethereum': validators.eth_address,
157
        'bsc': validators.bsc_address,
158
        'tron': validators.trx_address,
159
    }
160
    
161
    validator_func = network_validators.get(network.lower())
162
    if not validator_func:
163
        raise ValueError(f"Unsupported network: {network}")
164
    
165
    return bool(validator_func(address))
166

167
# Usage examples
168
validate_crypto_address('1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa', 'bitcoin')  # True
169
validate_crypto_address('0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed', 'ethereum')  # True
170
```
171

172
### Address Format Detection
173

174
```python
175
import validators
176

177
def detect_crypto_address_type(address: str) -> str:
178
    """Detect cryptocurrency address type."""
179
    
180
    if validators.btc_address(address):
181
        if address.startswith('1'):
182
            return 'Bitcoin P2PKH'
183
        elif address.startswith('3'):
184
            return 'Bitcoin P2SH'
185
        elif address.startswith('bc1'):
186
            return 'Bitcoin Bech32'
187
    elif validators.eth_address(address):
188
        return 'Ethereum'
189
    elif validators.bsc_address(address):
190
        return 'Binance Smart Chain'
191
    elif validators.trx_address(address):
192
        return 'Tron'
193
    
194
    return 'Unknown'
195

196
# Usage
197
addresses = [
198
    '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa',
199
    '0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed',
200
    'TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH'
201
]
202

203
for addr in addresses:
204
    print(f"{addr}: {detect_crypto_address_type(addr)}")
205
```
206

207
## Security Considerations
208

209
### Checksum Validation
210

211
```python
212
import validators
213

214
def validate_with_checksum_warning(address: str, network: str) -> tuple[bool, str]:
215
    """Validate address and provide checksum warnings."""
216
    
217
    if network == 'ethereum':
218
        # Check if address has mixed case (likely checksummed)
219
        has_mixed_case = any(c.isupper() for c in address) and any(c.islower() for c in address)
220
        
221
        if validators.eth_address(address):
222
            if not has_mixed_case and address != address.lower():
223
                return True, "Valid but consider using checksummed address for better security"
224
            return True, "Valid address"
225
        else:
226
            return False, "Invalid address format"
227
    
228
    # Add similar logic for other networks...
229
    return False, "Network not supported"
230

231
# Usage
232
result, message = validate_with_checksum_warning('0x5aaeb6053f3e94c9b9a09f33669435e7ef1beaed', 'ethereum')
233
print(f"Valid: {result}, Message: {message}")
234
```
235

236
## Installation Requirements
237

238
Some cryptocurrency validators require additional dependencies:
239

240
```bash
241
# Basic installation
242
pip install validators
243

244
# With Ethereum address checksum validation
245
pip install validators[crypto-eth-addresses]
246
```
247

248
The `crypto-eth-addresses` extra provides enhanced Ethereum address validation including:
249
- ERC-55 mixed-case checksum validation
250
- Improved address format checking
251
- Better error messages for invalid checksums