***

title: CAPTCHA
description: Detect and solve captchas automatically within browser runtimes.
-----------------------------------------------------------------------------

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.

```ts
const result = await runtime.captcha.detect();

if (result.found) {
  for (const captcha of result.captchas) {
    console.log(captcha.type, captcha.siteKey, captcha.source);
  }
}
```

| 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.

```ts
const result = await runtime.captcha.solve();

if (result.success) {
  console.log(`Solved ${result.type} in ${result.duration}ms`);
}
```

| 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:

```ts
const runtime = await workspace.runtimes.browser("main").playwright({
  mode: "ephemeral",
  config: {
    solveCaptchas: true,
  },
});
```

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

## Example: detect then solve

```ts
// Navigate to a page with a captcha
await runtime.page.goto("https://example.com/login");

// Check what's on the page
const detection = await runtime.captcha.detect();
console.log(`Found ${detection.captchas.length} captcha(s)`);

// Solve it
const result = await runtime.captcha.solve();
if (result.success) {
  // Captcha token is injected — now submit the form
  await runtime.page.locator("#submit").click();
}
```