Solving reCAPTCHA v2 with Puppeteer and DeathByCaptcha in Node.js

Solving reCAPTCHA v2 with Puppeteer and DeathByCaptcha in Node.js

Posted on 2026-11-20 | 3 min read | Category: puppeteer | By DeathByCaptcha Engineering Team

Puppeteer


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 install downloads it; if you already have a browser, point CHROME_BIN at 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

Common pitfalls

  • Using a CAPTCHA solving service for illegitimate purposes instead of legitimate automation and testing.
  • Hard-coding credentials or API keys in client-side code that users can inspect.
  • Sending the wrong CAPTCHA type parameter, which returns incorrect or empty responses.
  • Failing to poll for the solution status and not handling timeouts gracefully.
  • Scaling automation without monitoring error rates, response times, and CAPTCHA type coverage.
DBC
Written by DeathByCaptcha Engineering Team
DeathByCaptcha engineers build and operate the CAPTCHA solving technology behind this site. Articles are written by our technical team and checked for accuracy before publishing.
Reviewed by DeathByCaptcha Editorial Team

Get your API key — start solving

Free to try · No credit card · Python, Node.js, Java, C# SDKs

Get your API key


Status: OK

Servers are fully operational with faster than average response time.
  • Average solving time
  • 4 seconds - Normal CAPTCHAs (1 min. ago)
  • 8 seconds - reCAPTCHA V2, V3 (1 min. ago)
  • 4 seconds - others (1 min. ago)
Chrome and Firefox logos
Browser extensions available

Updates

  1. Nov 19: We are currently updating our cryptocurrency payment processor, Hekelet, so crypto payments may be temporarily unavailable. In the meantime, you can purchase credits through 2Checkout or contact our support team for assistance. We expect normal crypto payment processing to be restored within this week. Thank you for your patience and understanding!
  2. May 13: Crypto payments got better! You can now purchase your CAPTCHAs using cryptocurrency through the Hekelet payment processor at https://deathbycaptcha.com/user-pay and receive an extra 20% FREE CAPTCHA credit with every package purchased this way.
  3. Apr 15: GitHub Updates: We’ve upgraded our libraries, expanded sample code, enhanced documentation, and added support for C++ and Go, making integration smoother than ever. Explore what’s new at github.com/deathbycaptcha!

  4. Previous updates…

Support

Our system is designed to be completely user-friendly and easy-to-use. Should you have any trouble with it, simply email us at DBC technical support emailcom, and a support agent will get back to you as soon as possible.

Live Support

Available Monday to Friday (10am to 4pm EST) Live support image. Link to live support page