Skip to content

Selenium + CaptchaSonic

Solve reCAPTCHA, Turnstile, and more inside Selenium WebDriver with the CaptchaSonic Python SDK — solved server-side over gRPC and injected as a token.

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.

Install

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, then add funds) and the target page's reCAPTCHA sitekey — found in the page HTML as data-sitekey="…".

Quick start

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.

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