Solving reCAPTCHA v2 with Puppeteer and DeathByCaptcha in Node.js
Puppeteer is the shortest path from a Node.js script to a real browser. The hard part starts when the form ends in a reCAPTCHA: the browser can fill the fields, but the token has to come from somewhere.
This example does exactly that: it opens Google's reCAPTCHA v2 demo with Puppeteer, reads the sitekey, requests a token from DeathByCaptcha, injects it and submits the form. The token is never printed.
The example lives in the official Node.js client:
examples/puppeteer/recaptcha_v2_puppeteer.js
What you need
- Node.js 20 or newer.
- A DeathByCaptcha account with balance.
- Chrome for Puppeteer.
npm installdownloads it; if you already have a browser, pointCHROME_BINat it.
Setup
git clone https://github.com/deathbycaptcha/deathbycaptcha-api-client-nodejs.git
cd deathbycaptcha-api-client-nodejs
npm install
cp .env.sample .env
# edit .env with DBC_USERNAME and DBC_PASSWORD
The example reads DBC_USERNAME and DBC_PASSWORD from the environment.
The .env file is for your local run; it is ignored by git.
Run it
node examples/puppeteer/recaptcha_v2_puppeteer.js
Headless is the default. To watch the browser:
DBC_PUPPETEER_HEADLESS=false node examples/puppeteer/recaptcha_v2_puppeteer.js
If Chrome is not the build Puppeteer downloaded:
CHROME_BIN=/path/to/chrome node examples/puppeteer/recaptcha_v2_puppeteer.js
The flow
The sample launches Puppeteer, navigates to the demo and reads the sitekey from the widget:
const browser = await puppeteer.launch({
headless,
executablePath: process.env.CHROME_BIN || undefined,
args: ['--no-sandbox', '--disable-dev-shm-usage'],
});
const page = await browser.newPage();
await page.goto('https://www.google.com/recaptcha/api2/demo');
await page.waitForSelector('#recaptcha-demo');
const googleKey = await page.$eval(
'#recaptcha-demo',
(element) => element.getAttribute('data-sitekey')
);
Then it asks DeathByCaptcha for a type 4 token, using the sitekey and the page URL:
const solution = await decodeAsync(client, {
extra: {
type: 4,
token_params: JSON.stringify({
googlekey: googleKey,
pageurl: 'https://www.google.com/recaptcha/api2/demo',
}),
},
});
The injection is the part that is easy to get wrong. The token is passed to
page.evaluate as an argument, not built into a script string:
await page.evaluate((token) => {
const textarea =
document.getElementsByName('g-recaptcha-response')[0] ||
document.getElementById('g-recaptcha-response');
if (!textarea) return false;
textarea.style.display = 'block';
textarea.value = token;
textarea.dispatchEvent(new Event('input', { bubbles: true }));
textarea.dispatchEvent(new Event('change', { bubbles: true }));
// Call the widget callback when the page exposes it.
const clients = window.___grecaptcha_cfg && window.___grecaptcha_cfg.clients;
// ... walk the clients object and call the first callback found ...
return true;
}, solution.text);
Finally it clicks the submit button and waits for the success message. The result object returns the captcha id and the token, but nothing logs the token.
Why the callback matters
Filling g-recaptcha-response is not always enough. Many forms keep the
submit button disabled until the widget's callback runs. The sample walks the
___grecaptcha_cfg.clients object and calls the first callback it finds,
which is what the browser would have done after a human solved the challenge.
When no callback is found, the sample still submits; if the site rejects it,
the log shows the failure instead of pretending it worked.
Things to know
- The sample uses Google's demo page. It is the vendor's own test page. Do not point it at a site you do not own or have permission to test.
- The token is not printed. It is short-lived, but writing it to a log adds no value and makes leaks easier.
- IP-bound types need a proxy. Turnstile, WAF and DataDome tokens are tied to the exit IP. If you use them, the browser and the service must share the proxy.
- Puppeteer is Node.js only. For C#, the equivalent example uses PuppeteerSharp, a community port with an active release line. Python has no maintained Puppeteer port; use Playwright or Selenium there.
- CI runs the same flow. The repository runs the sample as an integration test on every push, with the account secrets in GitHub.
Next steps
The same call shape works for the other token types: change the type and the
parameter key (token_params for reCAPTCHA, turnstile_params for
Turnstile, waf_params for Amazon WAF). The repository has per-type
examples and a Playwright sample that follows the same injection pattern.
- Node.js client: https://github.com/deathbycaptcha/deathbycaptcha-api-client-nodejs
- API documentation: https://deathbycaptcha.com/api

English
Spanish
Russian
Chinese
French
Hindi
Arabic
Bengali
Indonesian
Portuguese
com, 