The fastest way to solve CAPTCHAs in Puppeteer. Bypass reCAPTCHA v2, reCAPTCHA v3, Cloudflare Turnstile, Geetest v4, AWS WAF, and image captchas with 3 lines of TypeScript.
Powered by CaptchaSonic — the AI captcha solving API with gRPC transport, sub-second response times, and 99%+ accuracy.
// ❌ Other captcha solvers — 20+ lines of manual API polling:
const res = await fetch('https://api.other-solver.com/createTask', { method: 'POST', body: JSON.stringify({...}) });
const { taskId } = await res.json();
while (true) {
await new Promise(r => setTimeout(r, 3000));
const result = await fetch('https://api.other-solver.com/getResult', { method: 'POST', body: JSON.stringify({ taskId }) });
const data = await result.json();
if (data.status === 'ready') { token = data.solution.token; break; }
}
// ✅ CaptchaSonic — 3 lines:
import { CaptchaSonic } from 'captchasonic';
const client = new CaptchaSonic('sonic_your_key_here');
const result = await client.solveRecaptchaV2Token({ websiteURL: url, websiteKey: siteKey });
const token = result.solution.gRecaptchaResponse;CaptchaSonic handles polling, retries, and errors internally — via a native gRPC connection (no HTTP overhead).
# 1. Clone this repo
git clone https://github.com/Captcha-Sonic/puppeteer-solver.git
cd puppeteer-solver
npm install
# 2. Set your API key
cp .env.example .env
# Edit .env → CAPTCHASONIC_API_KEY=sonic_your_key_here
# 3. Solve a captcha
npm run recaptcha-v2Puppeteer downloads Chromium automatically — no separate browser install needed.
Get your API key → captchasonic.com
| Captcha Type | Token Method | Script Method | npm Command |
|---|---|---|---|
| reCAPTCHA v2 (checkbox / invisible) | ✅ | ✅ | npm run recaptcha-v2 |
| reCAPTCHA v3 (score-based) | ✅ | — | npm run recaptcha-v3 |
| Cloudflare Turnstile | ✅ | — | npm run turnstile |
| Geetest v4 (slide, click, nine-grid) | ✅ | ✅ | npm run geetest |
| AWS WAF Captcha | ✅ | ✅ | npm run aws-waf |
| Image Captcha / OCR | ✅ | — | npm run image-captcha |
| Popular Captcha | ✅ | ✅ | npm run popularcaptcha |
The CaptchaSonic API solves the captcha server-side and returns a bypass token. You inject the token into the page and submit the form — no visible browser interaction needed.
Your script → CaptchaSonic API → returns bypass token → inject into page → submit form
import puppeteer from 'puppeteer';
import { CaptchaSonic } from 'captchasonic';
const browser = await puppeteer.launch({ headless: true });
const page = await browser.newPage();
await page.goto('https://example.com/login');
const client = new CaptchaSonic(process.env.CAPTCHASONIC_API_KEY);
// Solve reCAPTCHA v2 — one API call
const result = await client.solveRecaptchaV2Token({
websiteURL: 'https://example.com/login',
websiteKey: '6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-',
});
// Inject the token and submit
await page.evaluate((token) => {
document.querySelector('#g-recaptcha-response').value = token;
document.querySelector('form').submit();
}, result.solution.gRecaptchaResponse);Best for: headless automation, CI/CD pipelines, web scraping, maximum speed (5–15s)
Injects lightweight JavaScript into the page that detects, extracts, and clicks captcha challenges using CaptchaSonic's image classification API.
Inject script → detect captcha → extract tile images → SDK classifies → inject clicks → repeat
import { ScriptSolver } from '../shared/solver';
const solver = new ScriptSolver(page, client);
const result = await solver.solve('recaptcha_v2'); // or 'popularcaptcha', 'geetest', 'aws_waf'
if (result.solved) {
console.log(`Solved in ${result.time}s (${result.rounds} rounds)`);
}Best for: Popular Captcha, Geetest (nine-grid, slide, icon), AWS WAF, any visual challenge
| Token Method | Script Method | |
|---|---|---|
| How it works | API returns bypass token | JS extracts tiles → SDK classifies → JS clicks |
| Speed | ⚡ 5–15 seconds | 🐢 30–60 seconds per round |
| Headless | ✅ Fully headless | ✅ Works headless |
| Best for | reCAPTCHA v2/v3, Turnstile | Popular Captcha, Geetest, AWS WAF |
| Recommended | ✅ Start here | Use when token method is unavailable |
# Token method examples (API-based, fastest)
npm run recaptcha-v2 # Solve reCAPTCHA v2 checkbox
npm run recaptcha-v3 # Solve reCAPTCHA v3 score
npm run turnstile # Solve Cloudflare Turnstile
npm run geetest # Solve Geetest v4
npm run aws-waf # Solve AWS WAF captcha
npm run image-captcha # Solve image-to-text / OCR
npm run popularcaptcha # Solve Popular Captcha
# Script method examples (JS injection, visual captchas)
npm run recaptcha-v2:script # reCAPTCHA v2 tile clicking
npm run geetest:script # Geetest nine-grid / slide
npm run aws-waf:script # AWS WAF visual challenge
npm run popularcaptcha:script # Popular Captcha tile clickingpuppeteer-solver/
├── scripts/ # JS captcha detection/extraction scripts
│ ├── popularcaptcha.js # Popular Captcha handler
│ ├── recaptcha-v2.js # reCAPTCHA v2 tile handler
│ ├── geetest.js # Geetest handler (nine-grid, slide, icon)
│ └── aws-waf.js # AWS WAF handler
├── shared/
│ ├── helpers.ts # API key loader, token injector, utilities
│ └── solver.ts # ScriptSolver — detect → extract → solve → inject
├── examples/
│ ├── recaptcha-v2/
│ │ ├── token-method.ts # ⭐ Start here — fastest approach
│ │ └── script-method.ts # Tile clicking via JS injection
│ ├── recaptcha-v3/
│ │ └── token-method.ts # Score-based reCAPTCHA v3
│ ├── turnstile/
│ │ └── token-method.ts # Cloudflare Turnstile bypass
│ ├── geetest/
│ │ ├── token-method.ts # Geetest token solve
│ │ └── script-method.ts # Geetest visual solve (nine-grid, slide)
│ ├── aws-waf/
│ │ ├── token-method.ts # AWS WAF token
│ │ └── script-method.ts # AWS WAF visual
│ ├── image-captcha/
│ │ └── token-method.ts # OCR / image-to-text
│ └── popularcaptcha/
│ ├── token-method.ts # Popular Captcha token
│ └── script-method.ts # Popular Captcha tile clicking
├── package.json
├── tsconfig.json
└── LICENSE
Each example targets a public demo page. To solve captchas on your own site:
// 1. Change the target URL and site key
const SITE_URL = 'https://yoursite.com/login';
const SITE_KEY = 'your-recaptcha-site-key-here';
// 2. Run the example
// npm run recaptcha-v2For script method, just change the URL — the script auto-detects the captcha type on the page.
cp .env.example .env| Variable | Required | Description |
|---|---|---|
CAPTCHASONIC_API_KEY |
✅ | Your CaptchaSonic API key (starts with sonic_) |
CAPTCHASONIC_SCRIPTS_DIR |
❌ | Custom path to JS scripts (defaults to ./scripts/) |
// gRPC (default) — fastest, native binary protocol
const client = new CaptchaSonic('sonic_xxx');
// HTTP REST — works behind corporate proxies
const client = new CaptchaSonic('sonic_xxx', { transport: 'http' });const result = await client.solveRecaptchaV2Token({
websiteURL: 'https://example.com',
websiteKey: '...',
proxy: 'http://user:pass@host:port',
});- Node.js ≥ 18
- Puppeteer — installed automatically via
npm install(includes Chromium) - CaptchaSonic API key — get one free
How is CaptchaSonic different from 2Captcha or Anti-Captcha?
CaptchaSonic uses gRPC instead of HTTP polling — meaning no createTask → getResult loop. You make one call and get the answer. It's faster, simpler, and uses less bandwidth.
Does this work in headless mode?
Yes — both token and script methods work in headless: true mode. Token method is recommended for headless since it doesn't require visible browser interaction.
Can I use this with Puppeteer Extra / stealth plugin?
Yes. CaptchaSonic works with any Puppeteer setup including puppeteer-extra and puppeteer-extra-plugin-stealth.
What's the difference between Token and Script method?
Token method sends the captcha site key to CaptchaSonic's servers and gets back a bypass token — no browser interaction needed. Script method injects JS into the page that visually clicks tiles — needed for captchas that don't support token-based solving.
How much does it cost?
Check current pricing at captchasonic.com. New accounts get free credits to test.
| Project | Language | Link |
|---|---|---|
| Playwright Captcha Solver | TypeScript | Captcha-Sonic/playwright-solver |
| Selenium Captcha Solver | Python | Captcha-Sonic/selenium-python-solver |
| CaptchaSonic npm SDK | TypeScript | npmjs.com/captchasonic |
| CaptchaSonic Python SDK | Python | pypi.org/captchasonic |
| n8n Integration | n8n | n8n-nodes-captchasonic |
| MCP Server | AI Agents | @captchasonic/mcp-server |
puppeteer captcha solver · solve recaptcha puppeteer · bypass recaptcha v2 · puppeteer recaptcha · captcha automation · headless browser captcha · solve cloudflare turnstile · geetest solver · aws waf captcha bypass · captcha solving api · puppeteer automation · web scraping captcha · captchasonic · typescript captcha solver · node.js captcha solver · image captcha ocr · popular captcha solver puppeteer · anti captcha alternative · 2captcha alternative · captcha bypass service
MIT © CaptchaSonic — free to use in commercial and open-source projects.