Automate captcha solving in your **Selenium WebDriver** (Python) projects. CaptchaSonic solves the challenge server-side over a native **gRPC** connection and hands back a ready-to-inject token, so your script submits the form as if a human passed the challenge.

> [!TIP]
> This walkthrough uses the **token** flow. The SDK handles polling, retries, and error mapping internally — no HTTP plumbing, no image scraping.

The complete, runnable project lives on GitHub: [**selenium-python-solver**](https://github.com/Captcha-Sonic/selenium-python-solver).

---

## Install

```bash
pip install captchasonic selenium
export CAPTCHASONIC_API_KEY=sonic_your_key_here   # dashboard → API Keys
```

You need a CaptchaSonic API key with credits ([get one](/app), then [add funds](/docs/guides/add-funds)) and the target page's reCAPTCHA sitekey — found in the page HTML as `data-sitekey="…"`.

---

## Quick start

```python
import os
from selenium import webdriver
from selenium.webdriver.common.by import By
from captchasonic import CaptchaSonic

# Solves over a native gRPC connection (no HTTP overhead).
client = CaptchaSonic(os.environ["CAPTCHASONIC_API_KEY"])

driver = webdriver.Chrome()
driver.get("https://example.com/login")

# 1. Read the sitekey from the page.
sitekey = driver.find_element(
    By.CSS_SELECTOR, "[data-sitekey]"
).get_attribute("data-sitekey")

# 2. Ask CaptchaSonic for a token (auto-polls, returns when ready).
result = client.solve_recaptcha_v2_token(
    website_url=driver.current_url,
    website_key=sitekey,
)
token = result["solution"]["gRecaptchaResponse"]

# 3. Inject the token and submit the form.
driver.execute_script(
    "document.getElementById('g-recaptcha-response').innerHTML = arguments[0];",
    token,
)
driver.find_element(By.CSS_SELECTOR, "button[type='submit']").click()
```

---

## How it works

1. **Read the sitekey** from the target page (`data-sitekey`).
2. **Solve** — `solve_recaptcha_v2_token()` sends the sitekey and URL to CaptchaSonic over gRPC and blocks until a token is ready.
3. **Inject** the returned `gRecaptchaResponse` into the hidden `#g-recaptcha-response` textarea.
4. **Submit** the form — the site's handler reads the token exactly as if a human solved the challenge.

The same client solves reCAPTCHA v3, Cloudflare Turnstile, GeeTest, AWS WAF, and image captchas — see the [Python SDK reference](/docs/clients-sdks/python).

---

## Common pitfalls

- **Token bound via callback.** Some sites bind the token through a JS callback (`data-callback="…"`) instead of the textarea. Call that function with the token: `driver.execute_script("onCaptchaSolved(arguments[0])", token)`.
- **Token expires before submit.** reCAPTCHA tokens live ~120 s — solve as late as possible, right before the submit click.
- **Sitekey differs per environment.** Read it from the live page at runtime rather than hard-coding it.
- **Geo-locked validation.** Pass a `proxy=` argument so the token is solved through your IP when the target validates IP↔token coherence.

---

## See also

- [**selenium-python-solver** on GitHub](https://github.com/Captcha-Sonic/selenium-python-solver) — the full example project
- [Python SDK](/docs/clients-sdks/python) — every solve method and return shape
- [reCAPTCHA v2](/docs/recognition/recaptcha-v2) · [Turnstile](/docs/recognition/turnstile) — task-type references
- [Capability Matrix](/docs/clients-sdks/capabilities) — which return field for which captcha type
