auto-captcha-solver

Auto-Captcha

Auto-detect and solve captchas during Playwright browser automation using the NopeCHA API.

When to Use

• Browser automation hits a captcha wall
• Web scraping tasks need captcha bypass
• Automated testing against captcha-protected sites
• Any Playwright script that might encounter hCaptcha or reCAPTCHA v2

Prerequisites

• NOPECHA_API_KEY env var set (get free credits at https://nopecha.com)
• Python requests and playwright installed
• Playwright browser installed (python -m playwright install chromium)

Quick Start

from auto_captcha_solver import CaptchaSolver

solver = CaptchaSolver(api_key="your-key")

# Auto-detect + solve + inject (one-liner)
results = solver.auto_solve(page)

Full API

Detect

captchas = solver.detect(page)
# Returns: [{"type": "hcaptcha"|"recaptcha2", "sitekey": "...", "url": "...", "frame": ...}]

Solve

result = solver.solve("hcaptcha", sitekey, page_url)
# Returns: CaptchaResult(success=True, token="...", attempts=5, elapsed_sec=38.0)

Inject

solver.inject(page, "hcaptcha", token)
# Injects token into page's captcha callback

Auto (detect + solve + inject)

results = solver.auto_solve(page)
for r in results:
    print(f"{r.captcha_type}: {'OK' if r.success else r.error}")

SmartPage (transparent wrapper)

from auto_captcha_solver import smart_page

with smart_page(api_key="your-key") as page:
    page.goto("https://protected-site.com")
    page.fill("#email", "[email protected]")
    page.click("#submit")   # captcha auto-solved after each action

Supported Captcha Types

Type	API Endpoint	Status
hCaptcha (checkbox)	/v1/token/hcaptcha	Working
hCaptcha (enterprise)	/v1/token/hcaptcha	Working
reCAPTCHA v2	/v1/token/recaptcha2	Works but queue can be slow
reCAPTCHA v3	/v1/token/recaptcha3	Working (needs data.action)
Cloudflare Turnstile	/v1/token/turnstile	Working with a proxy — proxy is Required in NopeCHA's schema for this endpoint (solver exit IP must match browser IP); check_proxy_egress() / CLI proxy-check verify first. Error 10 bodies carry a diagnostic type field, now surfaced in the error string.