# auto-captcha-solver

Adopt this skill: https://proskills.md/skills/software-development/interfluve-wav-auto-captcha-solver-hermes-skill

Page: https://proskills.md/skills/software-development/interfluve-wav-auto-captcha-solver-hermes-skill
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: hermes-skill/SKILL.md
size: 5679
sha: 4f0dee7a1f4db4ef851798088866f9380222f4f1
upstream: https://github.com/interfluve-wav/auto-captcha-solver/blob/main/hermes-skill/SKILL.md

````text
---
name: auto-captcha-solver
description: Universal captcha auto-solver for Playwright browser automation. Detects hCaptcha and reCAPTCHA v2 on any page, solves via NopeCHA API, and injects tokens automatically. Drop-in CaptchaSolver class with auto_solve(page) method.
category: software-development
---

# 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

```python
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
```python
captchas = solver.detect(page)
# Returns: [{"type": "hcaptcha"|"recaptcha2", "sitekey": "...", "url": "...", "frame": ...}]
```

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

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

### Auto (detect + solve + inject)
```python
results = solver.auto_solve(page)
for r in results:
    print(f"{r.captcha_type}: {'OK' if r.success else r.error}")
```

## SmartPage (transparent wrapper)

```python
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", "user@example.com")
    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. |

## Stealth & Context Cloning (v0.1.6)

`apply_stealth(context)` masks the in-page headless leaks (`navigator.webdriver`,
`window.chrome`, `navigator.plugins`, WebGL vendor string). Call right after
`browser.new_context(...)`.

```python
from auto_captcha_solver import CaptchaSolver, apply_stealth
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch()
    context = browser.new_context()
    apply_stealth(context)          # mask fingerprint
    page = context.new_page()
    solver = CaptchaSolver(api_key="your-key")
    results = solver.auto_solve(page)   # clones UA + cookies automatically
```

`auto_solve(..., clone_context=True)` (default) forwards the browser's real
User-Agent and cookies to NopeCHA so the token is minted in a context matching
the presenting browser. Turnstile solves without a proxy emit a warning, because
Cloudflare requires the solver IP to match the client IP.

## Turnkey Autopilot

```python
from auto_captcha_solver import auto_solve_url

report = auto_solve_url("https://site.com", api_key="key", stealth=True)
print(report.summary)   # "https://site.com — hcaptcha:OK"
# proxy_pool=[...] + round_robin_rotator rotate proxies per session;
# auto_solve_page(page, solver) solves captchas on a page you already own.
```

## NopeCHA API Details

- **Base URL**: `https://api.nopecha.com`
- **Auth**: `Authorization: Basic <API_KEY>` header (NOT query param, NOT Bearer)
- **Status check**: `GET /v1/status`
- **Submit hCaptcha**: `POST /v1/token/hcaptcha` body `{"sitekey": "...", "url": "..."}`
- **Submit reCAPTCHA**: `POST /v1/token/recaptcha2` body `{"sitekey": "...", "url": "..."}`
- **Poll result**: `GET /v1/token/<type>?id=<job_id>`
- **Response**: `{"data": "<token>"}` on success, `{"error": 14}` = still in queue (retryable), other errors = fail
- **hCaptcha** solves fast (~30-40s). **reCAPTCHA** queue is often slow (60-120s+).

## Pitfalls

- **reCAPTCHA queues can be slow** — may take 60-120+ seconds during peak times
- **hCaptcha iframe detection** — look for `hcaptcha.com` in frame URLs; some sites load hCaptcha without an iframe (use DOM fallback: `document.querySelector('[data-sitekey]')`). Always add `time.sleep(3)` after page load for lazy loading.
- **reCAPTCHA iframe detection** — look for `recaptcha` AND `/anchor` in frame URL; the `?k=<sitekey>` param has the key
- **reCAPTCHA callback injection** — needs `___grecaptcha_cfg` to exist; if site uses enterprise, injection may fail silently
- **Credits** — each solve costs 1 credit; check with `solver.get_credits()`
- **Headless detection** — some sites detect headless browsers; use `headless=False` or stealth plugins if needed

## Installation

```bash
pip install auto-captcha-solver
python -m playwright install chromium
```

## MCP Server

Works with Claude Code, OpenClaw, and any MCP-compatible agent:

```bash
claude mcp add auto-captcha-solver -- python -m auto_captcha_solver.mcp_server
```

## File Location

```
~/.hermes/skills/auto-captcha-solver/
```
````

## File: README.md
upstream: https://github.com/interfluve-wav/auto-captcha-solver/blob/main/README.md

````text
# auto-captcha — Universal Captcha Solver for Playwright

![Python](https://img.shields.io/pypi/pyversions/auto-captcha)
![PyPI version](https://img.shields.io/pypi/v/auto-captcha)
![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue)
![Hermes Skill](https://img.shields.io/badge/Hermes-Skill-gold)

Drop-in captcha bypass for Playwright browser automation. Detects hCaptcha, reCAPTCHA v2/v3, and Cloudflare Turnstile, solves them via the NopeCHA Token API, and injects tokens automatically — so your automation scripts never stall.

```
Your script → page loads → captcha detected → NopeCHA API → token injected → continue
```

## Quick Start

```bash
pip install auto-captcha
python -m playwright install chromium
```

```python
from auto_captcha_solver import smart_page

with smart_page(api_key="your-nopecha-key") as page:
    page.goto("https://protected-site.com")
    page.fill("#email", "user@example.com")
    page.click("#submit")  # captcha auto-solved → form submits
```

## Why This Exists

Browser automation hits captcha walls. Existing solutions either require manual intervention or brittle image-to-text heuristics. **auto-captcha** uses a commercial token API (NopeCHA) that actually solves the challenge server-side — it's the same API powering many production captcha-bypass automation tools.

**Features:**
- **Automatic detection** — scans frames and DOM for hCaptcha, reCAPTCHA v2/v3, Turnstile
- **Zero-config wrapper** — `smart_page()` context manager handles everything
- **Fine-grained control** — `CaptchaSolver` class exposes detect/solve/inject separately
- **MCP server included** — use from Claude Code, Cursor, or any MCP-compatible agent
- **CLI tool** — solve or detect from the command line
- **Playwright CLI compatibility** — works alongside `playwright-cli` workflows

> **Note:** Requires a NopeCHA API key (free tier available). See https://nopecha.com

## Installation

### Core Package

```bash
pip install auto-captcha
```

### With Playwright (recommended)

```bash
pip install auto-captcha[playwright]
python -m playwright install chromium
```

Or install separately:

```bash
pip install playwright
python -m playwright install
```

## Three Ways to Use

### 1. `smart_page()` — Context Manager (easiest)

Manages browser lifecycle and auto-solves on navigation/click events.

```python
from auto_captcha_solver import smart_page

with smart_page(api_key="your-key") as page:
    page.goto("https://example.com")
    page.fill("#email", "user@test.com")
    page.click("#submit")  # auto-solved
    print(page.captcha_log)  # [{'type': 'hcaptcha', 'status': 'solved'}]
```

**Options:**
- `headless=False` — see the browser
- `wait_after_load=3.0` — delay before solving (site-dependent)

### 2. `SmartPage` — Wrap an Existing Page

Use when you already have a Playwright page/browser instance:

```python
from auto_captcha_solver import SmartPage
from playwright.sync_api import sync_playwright

pw = sync_playwright().start()
browser = pw.chromium.launch(headless=True)
raw_page = browser.new_page()
page = SmartPage(raw_page, api_key="your-key")

page.goto("https://site.com")  # captchas auto-solved
page.fill("#input", "value")
page.click("#submit")
browser.close()
pw.stop()
```

### 3. `CaptchaSolver` — Full Control

Detect, solve, and inject manually:

```python
from auto_captcha_solver import CaptchaSolver

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

# Detect all captchas on the page
captchas = solver.detect(page)
# → [{'type': 'hcaptcha', 'sitekey': 'abc123', 'url': 'https://...'}]

# Solve one
result = solver.solve(captcha_type="hcaptcha", sitekey="abc123", url=page.url)
if result.success:
    # Inject into page
    solver.inject(page, "hcaptcha", result.token)
```

## Stealth & Context Cloning

Token solves are minted server-side by the provider, so the token's *context*
(IP, User-Agent, cookies) must match the browser that presents it — otherwise
anti-bot systems (especially Cloudflare Turnstile) invalidate it on submit.

**`apply_stealth(context)`** masks the in-page fingerprint leaks a vanilla
headless Chromium exposes (`navigator.webdriver`, missing `window.chrome`,
empty `navigator.plugins`, SwiftShader WebGL vendor). Call it once on the
`BrowserContext`, before creating pages:

```python
from auto_captcha_solver import CaptchaSolver, apply_stealth
with sync_playwright() as p:
    browser = p.chromium.launch()
    context = browser.new_context()   # or use your real profile
    apply_stealth(context)            # mask fingerprint
    page = context.new_page()
    solver = CaptchaSolver(api_key="your-key")
    results = solver.auto_solve(page) # UA + cookies cloned automatically
```

**`clone_context(page)`** snapshots the browser's real User-Agent and cookies so
you can forward them to `solve()`:

```python
from auto_captcha_solver import clone_context
ctx = clone_context(page)  # {"useragent": str|None, "cookies": list|None}
result = solver.solve("hcaptcha", sitekey, page.url, **ctx)
```

- `auto_solve(..., clone_context=True)` (default) forwards the live UA + cookies
  and reads `data-action`/`data-cdata` off the widget for reCAPTCHA v3 /
  Turnstile metadata.
- **Turnstile requires a proxy** whose IP matches the client's — `solve()`
  emits a warning if you call it without `proxy=...`.
- The `Runtime.enable` CDP leak (below the JS layer) is closed only by driving
  the browser with [Patchright](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright-python)
  — a drop-in Playwright fork. `apply_stealth` stacks cleanly on top of it.

## Turnkey Auto-Solve (Autopilot)

`auto_solve_*` helpers wrap the full detect → solve → inject pipeline into a
single call. They wait for captchas that render late, clone the browser context,
and support proxy rotation.

```python
from auto_captcha_solver import auto_solve_url

report = auto_solve_url(
    "https://some-login-form.com",
    api_key="your-key",
    stealth=True,          # mask headless fingerprint
    proxy={"scheme": "http", "host": "your-residential-ip", "port": 7777},
)
print(report.summary)   # "https://... — hcaptcha:OK"
print(report.solved)    # True
```

**Rotating proxies** (e.g. Novada) — pass a pool; one proxy is picked per session
and used for BOTH browser egress and the solve request, so the token IP always
matches the browser IP (required for token validity):

```python
from auto_captcha_solver import auto_solve_url, round_robin_rotator

proxies = [
    {"scheme": "http", "host": "p1.novada.example", "port": 7777, "username": "u", "password": "p"},
    {"scheme": "http", "host": "p2.novada.example", "port": 7777, "username": "u", "password": "p"},
]
report = auto_solve_url("https://site.com", api_key="k", proxy_pool=proxies)
```

**Remote / hosted browsers** (Browserless, Steel, or any CDP endpoint) — pass
`cdp_url` to drive an existing browser instead of launching one. The function
opens a fresh context on the remote browser, solves, and closes that context
without killing the remote session:

```python
from auto_captcha_solver import auto_solve_url

report = auto_solve_url(
    "https://site.com",
    api_key="your-key",
    cdp_url="https://<token>.browserless.io?token=***",   # or wss:// Steel endpoint
    # connect_kwargs={"headers": {"Authorization": "Bearer <token>"}},  # if needed
    # proxy={"scheme": "http", "host": "remote-egress-ip", "port": 7777},
    #   ↑ forward the remote browser's egress IP to the solver — the token's IP
    #     must match the client IP or Turnstile/reCAPTCHA v3 will invalidate it.
)
```

In CDP mode the browser's egress is fixed by the host (you can't re-route it),
so match it with `proxy` for the solve request. Local mode does this
automatically: `proxy` drives both the launched browser and the solver.

Wire it into a page you already own with `auto_solve_page(page, solver)` — it
polls for late-rendering widgets (safer than waiting for `networkidle`, which
Turnsti
````
