0
# CAPTCHA Solving
1

2
Integration with external CAPTCHA solving services for handling Cloudflare challenges that require human verification. CloudScraper supports multiple providers with automatic submission and result retrieval.
3

4
## Capabilities
5

6
### Base CAPTCHA Interface
7

8
Abstract base class that all CAPTCHA solver providers implement for consistent challenge solving across different services.
9

10
```python { .api }
11
class Captcha:
12
    def __init__(self, name: str):
13
        """
14
        Initialize CAPTCHA solver.
15
        
16
        Parameters:
17
        - name: str, provider identifier
18
        """
19

20
    @classmethod
21
    def dynamicImport(cls, name: str):
22
        """
23
        Dynamically import and initialize CAPTCHA provider.
24
        
25
        Parameters:
26
        - name: str, provider name to load
27
        
28
        Returns:
29
        Captcha instance
30
        
31
        Raises:
32
        - ImportError: If provider cannot be loaded
33
        """
34

35
    def getCaptchaAnswer(self, captchaType: str, url: str, siteKey: str, captchaParams: dict):
36
        """
37
        Solve CAPTCHA challenge using external service.
38
        
39
        Parameters:
40
        - captchaType: str, type of CAPTCHA (hcaptcha, recaptcha, turnstile)
41
        - url: str, page URL where CAPTCHA appears
42
        - siteKey: str, CAPTCHA site key
43
        - captchaParams: dict, additional CAPTCHA parameters
44
        
45
        Returns:
46
        CAPTCHA solution token
47
        
48
        Raises:
49
        - CaptchaServiceUnavailable: If service cannot be reached
50
        - CaptchaAPIError: If API returns error
51
        - CaptchaTimeout: If solving takes too long
52
        """
53

54
    def solveCaptcha(self, captchaType: str, url: str, siteKey: str, captchaParams: dict):
55
        """
56
        Public interface for solving CAPTCHAs.
57
        
58
        Parameters: Same as getCaptchaAnswer()
59
        Returns: CAPTCHA solution token
60
        """
61
```
62

63
### 2captcha Provider
64

65
Integration with 2captcha.com service for solving various CAPTCHA types including reCAPTCHA, hCaptcha, and Turnstile.
66

67
```python { .api }
68
class captchaSolver(Captcha):
69
    def __init__(self):
70
        """Initialize 2captcha solver."""
71

72
    def getCaptchaAnswer(self, captchaType: str, url: str, siteKey: str, captchaParams: dict):
73
        """
74
        Solve CAPTCHA using 2captcha service.
75
        
76
        Parameters:
77
        - captchaType: str, CAPTCHA type
78
        - url: str, page URL
79
        - siteKey: str, site key  
80
        - captchaParams: dict, additional parameters including:
81
          - api_key: str, 2captcha API key
82
          - no_proxy: bool, disable proxy forwarding
83
        
84
        Returns:
85
        str: CAPTCHA solution token
86
        """
87
```
88

89
#### Usage Examples
90

91
```python
92
# Configure 2captcha solver
93
scraper = cloudscraper.create_scraper(
94
    captcha={
95
        'provider': '2captcha',
96
        'api_key': 'your_2captcha_api_key'
97
    }
98
)
99

100
# Solve Turnstile challenges automatically
101
response = scraper.get('https://turnstile-protected-site.com')
102

103
# With proxy support
104
scraper = cloudscraper.create_scraper(
105
    captcha={
106
        'provider': '2captcha',
107
        'api_key': 'your_api_key',
108
        'no_proxy': False  # Forward proxy to 2captcha
109
    },
110
    proxies={'http': 'http://proxy.example.com:8080'}
111
)
112

113
# Disable proxy forwarding to 2captcha
114
scraper = cloudscraper.create_scraper(
115
    captcha={
116
        'provider': '2captcha', 
117
        'api_key': 'your_api_key',
118
        'no_proxy': True  # Don't send proxy to 2captcha
119
    },
120
    proxies={'http': 'http://proxy.example.com:8080'}
121
)
122
```
123

124
### AntiCaptcha Provider
125

126
Integration with Anti-Captcha service for high-quality CAPTCHA solving with various challenge types.
127

128
```python { .api }
129
class captchaSolver(Captcha):
130
    def __init__(self):
131
        """Initialize AntiCaptcha solver."""
132

133
    def getCaptchaAnswer(self, captchaType: str, url: str, siteKey: str, captchaParams: dict):
134
        """
135
        Solve CAPTCHA using Anti-Captcha service.
136
        
137
        Parameters:
138
        - captchaType: str, CAPTCHA type
139
        - url: str, page URL
140
        - siteKey: str, site key
141
        - captchaParams: dict, additional parameters including:
142
          - api_key: str, Anti-Captcha API key
143
          - no_proxy: bool, disable proxy forwarding
144
        
145
        Returns:
146
        str: CAPTCHA solution token
147
        """
148
```
149

150
#### Usage Examples
151

152
```python
153
# Configure AntiCaptcha solver
154
scraper = cloudscraper.create_scraper(
155
    captcha={
156
        'provider': 'anticaptcha',
157
        'api_key': 'your_anticaptcha_api_key'
158
    }
159
)
160

161
# Solve various CAPTCHA types
162
response = scraper.get('https://recaptcha-protected-site.com')
163
response = scraper.get('https://hcaptcha-protected-site.com')
164
```
165

166
### 9kw Provider
167

168
Integration with 9kw.eu CAPTCHA solving service with configurable timeout settings.
169

170
```python { .api }
171
class captchaSolver(Captcha):
172
    def __init__(self):
173
        """Initialize 9kw solver."""
174

175
    def getCaptchaAnswer(self, captchaType: str, url: str, siteKey: str, captchaParams: dict):
176
        """
177
        Solve CAPTCHA using 9kw service.
178
        
179
        Parameters:
180
        - captchaType: str, CAPTCHA type
181
        - url: str, page URL
182
        - siteKey: str, site key
183
        - captchaParams: dict, additional parameters including:
184
          - api_key: str, 9kw API key
185
          - maxtimeout: int, maximum solving timeout in seconds
186
        
187
        Returns:
188
        str: CAPTCHA solution token
189
        """
190
```
191

192
#### Usage Examples
193

194
```python
195
# Configure 9kw solver with custom timeout  
196
scraper = cloudscraper.create_scraper(
197
    captcha={
198
        'provider': '9kw',
199
        'api_key': 'your_9kw_api_key',
200
        'maxtimeout': 300  # 5 minute timeout
201
    }
202
)
203

204
# Default timeout is 180 seconds
205
scraper = cloudscraper.create_scraper(
206
    captcha={
207
        'provider': '9kw',
208
        'api_key': 'your_api_key'
209
    }
210
)
211
```
212

213
### CapMonster Cloud Provider
214

215
Integration with CapMonster Cloud service for fast and reliable CAPTCHA solving.
216

217
```python { .api }
218
class captchaSolver(Captcha):
219
    def __init__(self):
220
        """Initialize CapMonster solver."""
221

222
    def getCaptchaAnswer(self, captchaType: str, url: str, siteKey: str, captchaParams: dict):
223
        """
224
        Solve CAPTCHA using CapMonster Cloud service.
225
        
226
        Parameters:
227
        - captchaType: str, CAPTCHA type
228
        - url: str, page URL
229
        - siteKey: str, site key
230
        - captchaParams: dict, additional parameters including:
231
          - clientKey: str, CapMonster client key
232
          - no_proxy: bool, disable proxy forwarding
233
        
234
        Returns:
235
        str: CAPTCHA solution token
236
        """
237
```
238

239
#### Usage Examples
240

241
```python
242
# Configure CapMonster solver
243
scraper = cloudscraper.create_scraper(
244
    captcha={
245
        'provider': 'capmonster',
246
        'clientKey': 'your_capmonster_client_key'
247
    }
248
)
249

250
# With proxy configuration
251
scraper = cloudscraper.create_scraper(
252
    captcha={
253
        'provider': 'capmonster',
254
        'clientKey': 'your_client_key',
255
        'no_proxy': False  # Forward proxy to CapMonster
256
    }
257
)
258
```
259

260
### Capsolver Provider
261

262
Integration with Capsolver service for modern CAPTCHA solving including Turnstile support.
263

264
```python { .api }
265
class captchaSolver(Captcha):
266
    def __init__(self):
267
        """Initialize Capsolver solver."""
268

269
    def getCaptchaAnswer(self, captchaType: str, url: str, siteKey: str, captchaParams: dict):
270
        """
271
        Solve CAPTCHA using Capsolver service.
272
        
273
        Parameters:
274
        - captchaType: str, CAPTCHA type
275
        - url: str, page URL
276
        - siteKey: str, site key
277
        - captchaParams: dict, additional parameters including:
278
          - api_key: str, Capsolver API key
279
        
280
        Returns:
281
        str: CAPTCHA solution token
282
        """
283
```
284

285
#### Usage Examples
286

287
```python
288
# Configure Capsolver
289
scraper = cloudscraper.create_scraper(
290
    captcha={
291
        'provider': 'capsolver',
292
        'api_key': 'your_capsolver_api_key'
293
    }
294
)
295

296
# Good for Turnstile challenges
297
response = scraper.get('https://turnstile-site.com')
298
```
299

300
### DeathByCaptcha Provider
301

302
Integration with DeathByCaptcha service using username/password authentication.
303

304
```python { .api }
305
class captchaSolver(Captcha):
306
    def __init__(self):
307
        """Initialize DeathByCaptcha solver."""
308

309
    def getCaptchaAnswer(self, captchaType: str, url: str, siteKey: str, captchaParams: dict):
310
        """
311
        Solve CAPTCHA using DeathByCaptcha service.
312
        
313
        Parameters:
314
        - captchaType: str, CAPTCHA type
315
        - url: str, page URL
316
        - siteKey: str, site key
317
        - captchaParams: dict, additional parameters including:
318
          - username: str, DeathByCaptcha username
319
          - password: str, DeathByCaptcha password
320
        
321
        Returns:
322
        str: CAPTCHA solution token
323
        """
324
```
325

326
#### Usage Examples
327

328
```python
329
# Configure DeathByCaptcha solver
330
scraper = cloudscraper.create_scraper(
331
    captcha={
332
        'provider': 'deathbycaptcha',
333
        'username': 'your_username',
334
        'password': 'your_password'
335
    }
336
)
337
```
338

339
### Return Response Provider
340

341
Special provider that returns the challenge response without solving, useful for manual handling or debugging.
342

343
```python { .api }
344
class captchaSolver(Captcha):
345
    def __init__(self):
346
        """Initialize return response provider."""
347

348
    def getCaptchaAnswer(self, captchaType: str, url: str, siteKey: str, captchaParams: dict):
349
        """
350
        Return challenge response without solving.
351
        
352
        Returns:
353
        The original response for manual processing
354
        """
355
```
356

357
#### Usage Examples
358

359
```python
360
# Get challenge response for manual handling
361
scraper = cloudscraper.create_scraper(
362
    captcha={'provider': 'return_response'}
363
)
364

365
# This will return the CAPTCHA challenge page instead of solving it
366
response = scraper.get('https://captcha-protected-site.com')
367
print("Manual CAPTCHA solving required")
368
print(response.text)  # Contains CAPTCHA challenge HTML
369
```
370

371
## CAPTCHA Configuration and Usage
372

373
### Provider Selection
374

375
Choose the best CAPTCHA provider for your needs:
376

377
```python
378
providers = {
379
    '2captcha': {
380
        'pros': 'Reliable, supports all types, good API',
381
        'cons': 'Can be slower',
382
        'config': {'provider': '2captcha', 'api_key': 'key'}
383
    },
384
    'anticaptcha': {
385
        'pros': 'Fast, high quality',
386
        'cons': 'More expensive',  
387
        'config': {'provider': 'anticaptcha', 'api_key': 'key'}
388
    },
389
    'capsolver': {
390
        'pros': 'Modern, good Turnstile support',
391
        'cons': 'Newer service',
392
        'config': {'provider': 'capsolver', 'api_key': 'key'}
393
    }
394
}
395

396
# Select provider based on needs
397
provider = 'capsolver'  # Good for Turnstile
398
scraper = cloudscraper.create_scraper(
399
    captcha=providers[provider]['config']
400
)
401
```
402

403
### CAPTCHA Type Support
404

405
Different providers support different CAPTCHA types:
406

407
```python
408
captcha_support = {
409
    'recaptcha_v2': ['2captcha', 'anticaptcha', 'capmonster', 'capsolver'],
410
    'recaptcha_v3': ['2captcha', 'anticaptcha', 'capmonster', 'capsolver'],
411
    'hcaptcha': ['2captcha', 'anticaptcha', 'capmonster', 'capsolver'],
412
    'turnstile': ['2captcha', 'anticaptcha', 'capmonster', 'capsolver'],
413
    'funcaptcha': ['2captcha', 'anticaptcha', 'capmonster'],
414
    'geetest': ['2captcha', 'anticaptcha', 'capmonster']
415
}
416

417
# For Turnstile specifically
418
turnstile_providers = ['2captcha', 'anticaptcha', 'capmonster', 'capsolver']
419
scraper = cloudscraper.create_scraper(
420
    captcha={
421
        'provider': '2captcha',  # Any Turnstile-compatible provider
422
        'api_key': 'your_api_key'
423
    }
424
)
425
```
426

427
### Proxy Integration with CAPTCHA
428

429
Configure how proxies are handled with CAPTCHA services:
430

431
```python
432
# Forward proxy to CAPTCHA service (recommended for accuracy)
433
scraper = cloudscraper.create_scraper(
434
    captcha={
435
        'provider': '2captcha',
436
        'api_key': 'your_api_key',
437
        'no_proxy': False  # Send proxy info to 2captcha
438
    },
439
    proxies={'http': 'http://proxy.example.com:8080'}
440
)
441

442
# Don't forward proxy (faster but may be less accurate)
443
scraper = cloudscraper.create_scraper(
444
    captcha={
445
        'provider': '2captcha',
446
        'api_key': 'your_api_key', 
447
        'no_proxy': True  # Don't send proxy to 2captcha
448
    },
449
    proxies={'http': 'http://proxy.example.com:8080'}
450
)
451
```
452

453
## Error Handling and Troubleshooting
454

455
### CAPTCHA Exception Handling
456

457
Handle various CAPTCHA-related errors:
458

459
```python
460
try:
461
    scraper = cloudscraper.create_scraper(
462
        captcha={
463
            'provider': '2captcha',
464
            'api_key': 'your_api_key'
465
        }
466
    )
467
    response = scraper.get('https://captcha-protected-site.com')
468
    
469
except cloudscraper.CaptchaServiceUnavailable:
470
    print("CAPTCHA service is unavailable")
471
except cloudscraper.CaptchaAPIError as e:
472
    print(f"CAPTCHA API error: {e}")
473
except cloudscraper.CaptchaTimeout:
474
    print("CAPTCHA solving timed out")
475
except cloudscraper.CaptchaAccountError:
476
    print("CAPTCHA account issue (balance, credentials)")
477
except cloudscraper.CloudflareCaptchaProvider:
478
    print("CAPTCHA challenge detected but no solver configured")
479
```
480

481
### Provider Fallback
482

483
Implement fallback between different CAPTCHA providers:
484

485
```python
486
def create_scraper_with_fallback():
487
    """Create scraper with CAPTCHA provider fallback."""
488
    providers = [
489
        {'provider': '2captcha', 'api_key': 'key1'},
490
        {'provider': 'anticaptcha', 'api_key': 'key2'},
491
        {'provider': 'capsolver', 'api_key': 'key3'}
492
    ]
493
    
494
    for captcha_config in providers:
495
        try:
496
            scraper = cloudscraper.create_scraper(captcha=captcha_config)
497
            # Test with a simple request
498
            response = scraper.get('https://httpbin.org/get')
499
            if response.status_code == 200:
500
                print(f"Using provider: {captcha_config['provider']}")
501
                return scraper
502
        except Exception as e:
503
            print(f"Provider {captcha_config['provider']} failed: {e}")
504
            continue
505
    
506
    print("All CAPTCHA providers failed, using no solver")
507
    return cloudscraper.create_scraper()
508

509
scraper = create_scraper_with_fallback()
510
```
511

512
### CAPTCHA Debug Mode
513

514
Enable debug output to monitor CAPTCHA solving:
515

516
```python
517
scraper = cloudscraper.create_scraper(
518
    captcha={
519
        'provider': '2captcha',
520
        'api_key': 'your_api_key'
521
    },
522
    debug=True
523
)
524

525
response = scraper.get('https://turnstile-protected-site.com')
526

527
# Debug output shows:
528
# "Detected Cloudflare Turnstile challenge"
529
# "Submitting CAPTCHA to 2captcha service..."
530
# "CAPTCHA solved successfully"
531
# "Submitting solution to Cloudflare..."
532
```
533

534
### Cost Management
535

536
Monitor and manage CAPTCHA solving costs:
537

538
```python
539
# Track CAPTCHA usage
540
captcha_count = 0
541

542
def count_captcha_hook(scraper, response):
543
    """Hook to count CAPTCHA solves."""
544
    global captcha_count
545
    if 'captcha solved' in str(response.history):
546
        captcha_count += 1
547
        print(f"CAPTCHAs solved: {captcha_count}")
548
    return response
549

550
scraper = cloudscraper.create_scraper(
551
    captcha={'provider': '2captcha', 'api_key': 'key'},
552
    requestPostHook=count_captcha_hook
553
)
554

555
# Limit CAPTCHA attempts per session
556
max_captchas = 10
557
if captcha_count >= max_captchas:
558
    print("CAPTCHA limit reached")
559
    scraper = cloudscraper.create_scraper()  # No CAPTCHA solver
560
```
561

562
## Advanced CAPTCHA Configuration
563

564
### Custom CAPTCHA Parameters
565

566
Pass additional parameters to CAPTCHA services:
567

568
```python
569
# Custom 2captcha parameters
570
scraper = cloudscraper.create_scraper(
571
    captcha={
572
        'provider': '2captcha',
573
        'api_key': 'your_api_key',
574
        'pingback': 'https://your-domain.com/callback',  # Custom callback
575
        'soft_id': 123  # Software ID for tracking
576
    }
577
)
578

579
# Custom timeout for different providers
580
timeouts = {
581
    '2captcha': 180,
582
    'anticaptcha': 120,
583
    '9kw': 300
584
}
585

586
provider = '9kw'
587
scraper = cloudscraper.create_scraper(
588
    captcha={
589
        'provider': provider,
590
        'api_key': 'your_api_key',
591
        'maxtimeout': timeouts.get(provider, 180)
592
    }
593
)
594
```