@mercuryo-ai/captcha-solver

Standalone CAPTCHA-solving helpers for browser-driving runtimes.

Do You Need This Package Directly?

Most people do not. If you are already using @mercuryo-ai/magicbrowse-cli or @mercuryo-ai/magicpay-cli, CAPTCHA handling is available through those CLIs and you do not need to install this package yourself.

Install this package directly when:

• you are building a custom browser-automation runtime and do not want the rest of the MagicBrowse / MagicPay machinery;
• you want to run CAPTCHA solving inline inside a backend worker or MCP tool that already has its own CDP connection.

What It Provides

• solveCaptchasByCdp(cdpUrl, apiKey, options?) — one-shot solver. Attaches to the browser, detects challenges on the current page, solves them, applies the solution, and disconnects. Use this for known CAPTCHA-gating points (a form that always shows a challenge).
• setupCaptchaMonitor(...) — long-running observer. Watches a browser session over time, solves CAPTCHAs as they appear, stays attached until you stop it. Use this for pages that show CAPTCHAs at unpredictable points (mid-flow anti-bot challenges, background checks).
• CaptchaSolver — the lower-level HTTP client both of the above build on. Use it directly only when you already own the browser-side integration and just need to talk to the Mercuryo CAPTCHA API.
• Detection and solving helpers for reCAPTCHA v2, hCaptcha, and Turnstile (including Cloudflare challenge-page Turnstile).

TypeScript types for every public API are re-exported from the package root: SolveCaptchasByCdpOptions, SolveCaptchasByCdpResult, CaptchaSolverConfig, CaptchaSolveRequest, CaptchaSolveResult, CaptchaSolveOutcome, DetectedCaptcha, ProxyConfig.

Scope

This package only owns the CAPTCHA step. Browser session lifecycle, page observation, form filling, and payment approvals belong to the caller.

Prerequisites

• A Mercuryo agent API key. This is the same @mercuryo-ai API key used by MagicPay CLIs and the MagicPay SDK. Create one at https://agents.mercuryo.io/signup. The CAPTCHA-solving endpoint lives on the same API, so there is no separate credential to provision.
• A running Chrome or Chromium with remote debugging enabled, reachable over a CDP WebSocket URL. You obtain the URL from whatever component launched the browser (an agent runtime, your own Playwright launcher, a cloud browser provider).

Install

npm i @mercuryo-ai/captcha-solver

Example: One-Shot Solve

import { solveCaptchasByCdp } from '@mercuryo-ai/captcha-solver';

const result = await solveCaptchasByCdp(
  'ws://127.0.0.1:9222/devtools/browser/test',
  process.env.MAGICPAY_API_KEY!,
  {
    apiUrl: 'https://agents-api.mercuryo.io/functions/v1/api',
    timeoutMs: 90_000,
    onProgress: (message) => console.log('[captcha]', message),
  }
);

console.log(result);
// → { solved: 1, verified: 1, unresolved: 0, detected: 1, timedOut: false, ... }

Both apiKey and apiUrl are required. Omitting either throws at construction time.

solveCaptchasByCdp options

• apiUrl (required) — MagicPay API base URL. Use https://agents-api.mercuryo.io/functions/v1/api unless you are testing against a different environment.
• timeoutMs — total deadline for detection + solving, defaults to 90_000.
• pollIntervalMs — how often to scan the page for new CAPTCHAs, defaults to 1500.
• solveTimeoutMs — per-task solve timeout passed to CaptchaSolver.
• connectTimeoutMs — CDP connection timeout, defaults to 15_000.
• proxy — ProxyConfig applied to solver-side HTTP traffic:

  { server: 'http://proxy.example:8080', username?: string, password?: string }

• sharedTransport — reuse one underlying HTTP connection for all tasks; defaults to true when proxy is set.
• onProgress(message) — callback for progress lines. Useful for forwarding to a logger or progress UI.

What If The CAPTCHA Refreshes Mid-Solve?

The solver sees the refresh as a new challenge and starts a new task. The result counts new challenges in detected and solved; previous partially-completed tasks are discarded.