CAPTCHA | BCTRL | Documentation

BCTRL can detect and solve captchas on the current page. Supported captcha types include reCAPTCHA v2/v3, Cloudflare Turnstile, hCaptcha, GeeTest, Arkose, and more.

Access via runtime.captcha.

Supported types

Type	ID
reCAPTCHA v2	`recaptcha_v2`
reCAPTCHA v3	`recaptcha_v3`
Cloudflare Turnstile	`turnstile`
hCaptcha	`hcaptcha`
GeeTest v3	`geetest_v3`
GeeTest v4	`geetest_v4`
Arkose Labs	`arkose`
MTCaptcha	`mtcaptcha`
Lemin	`lemin`
Friendly Captcha	`friendly_captcha`
DataDome	`datadome`

captcha.detect(options?)

Scan the page for captcha widgets. Detection checks the DOM, loaded scripts, and network requests.

1 const result = await runtime.captcha.detect();
2 
3 if (result.found) {
4   for (const captcha of result.captchas) {
5     console.log(captcha.type, captcha.siteKey, captcha.source);
6   }
7 }

Parameter	Type	Required	Description
`types`	`CaptchaType[]`	No	Only detect these specific captcha types

Returns CaptchaDetectResult

Field	Type	Description
`found`	`boolean`	Whether any captchas were detected
`captchas`	`CaptchaDetection[]`	Array of detected captchas
`captchas[].type`	`CaptchaType`	The captcha type
`captchas[].siteKey`	`string`	The site key (if found)
`captchas[].source`	`'dom' \| 'script' \| 'network'`	How the captcha was detected

captcha.solve(options?)

Detect and solve a captcha, then inject the solution token into the page.

1 const result = await runtime.captcha.solve();
2 
3 if (result.success) {
4   console.log(`Solved ${result.type} in ${result.duration}ms`);
5 }

Parameter	Type	Required	Description
`type`	`CaptchaType`	No	Solve a specific captcha type (auto-detects if omitted)

Returns CaptchaSolveResult

Field	Type	Description
`success`	`boolean`	Whether the captcha was solved
`type`	`CaptchaType`	The captcha type that was solved
`token`	`string`	The solution token
`duration`	`number`	Time to solve in milliseconds
`error`	`string`	Error message if solving failed

Auto-solve on launch

Enable automatic captcha solving when launching a runtime:

1 const runtime = await workspace.runtimes.browser("main").playwright({
2   mode: "ephemeral",
3   config: {
4     solveCaptchas: true,
5   },
6 });

When solveCaptchas is enabled, captchas are detected and solved automatically as they appear — no manual calls needed.

Example: detect then solve

1 // Navigate to a page with a captcha
2 await runtime.page.goto("https://example.com/login");
3 
4 // Check what's on the page
5 const detection = await runtime.captcha.detect();
6 console.log(`Found ${detection.captchas.length} captcha(s)`);
7 
8 // Solve it
9 const result = await runtime.captcha.solve();
10 if (result.success) {
11   // Captcha token is injected — now submit the form
12   await runtime.page.locator("#submit").click();
13 }