Node.js SDK

The CaptchaSonic Node.js SDK (captchasonic) is a modern, Promise-based, TypeScript-first library for solving CAPTCHAs at scale. Every method returns a Promise, ships full type definitions, and runs over three interchangeable transports — native gRPC (fastest, Node.js only), ConnectRPC (works in Node.js and browsers), and plain HTTP/JSON. Transient errors are retried automatically with exponential backoff.

It works in Node.js ≥ 18 and modern browsers, and is compatible with Express, Fastify, Next.js, React, Vue, and Vite.

Installation

npm install captchasonic
# or
yarn add captchasonic
# or
pnpm add captchasonic

Requirements

The package is published as ESM only. In an ESM project ("type": "module" in your package.json, or a .mjs file) import it directly:

import { CaptchaSonic } from "captchasonic";

From a CommonJS file, load it with a dynamic import():

// CommonJS (.cjs / "type": "commonjs")
const { CaptchaSonic } = await import("captchasonic");

Authentication

Create an API key in the CaptchaSonic dashboard and pass it as the first argument to the constructor:

import { CaptchaSonic } from "captchasonic";

const solver = new CaptchaSonic("YOUR_API_KEY");

Never hard-code keys in source control. Read the key from the environment instead:

import { CaptchaSonic } from "captchasonic";

const solver = new CaptchaSonic(process.env.CAPTCHASONIC_API_KEY);

Quick Start

Each captcha type has a dedicated solve* helper that submits the task and resolves with the result. There is no separate polling step for image tasks — the SDK handles it for you.

import { CaptchaSonic } from "captchasonic";

const solver = new CaptchaSonic(process.env.CAPTCHASONIC_API_KEY);

const result = await solver.solveRecaptchaV2Token({
  websiteURL: "https://example.com/login",
  websiteKey: "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
});

console.log(result.solution.gRecaptchaResponse);
// 03AGdBq25SxXT...  ← drop into the g-recaptcha-response field

from captchasonic import CaptchaSonic

solver = CaptchaSonic("YOUR_API_KEY")

result = solver.solve_recaptcha_v2_token(
    website_url="https://example.com/login",
    website_key="6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
)

print(result["token"])
# 03AGdBq25SxXT...  ← drop this into the g-recaptcha-response field

Returns: image methods resolve a result whose answer lives under typedSolution (e.g. typedSolution.grid.objects, the selected tile indices); token methods return the token in the solution map.

Supported CAPTCHA Types

All image methods take a single typed options object. Images may be Uint8Array, Node Buffer, or a string file path (file paths are Node.js only).

reCAPTCHA v2 (image)

await solver.solveRecaptchaV2({
  images: tiles,                 // typically 9 tiles for a 3×3 grid
  question: "traffic lights",    // plain text, or a Google class code like "/m/015qff"
});
// → result.typedSolution.grid.objects  (number[] — selected tile indices)

PopularCaptcha (hCaptcha-style image)

await solver.solvePopularCaptcha({
  images: tiles,                 // 1–64 tiles
  question: "Click each image with a cat",
  questionType: "objectClassify", // "objectClassify" | "grid" | "objectClick" | "objectDrag"
  examples,                      // optional reference images for objectClick
  websiteURL: "https://example.com",
});
// objectClassify/grid → typedSolution.grid.objects
// objectClick        → typedSolution.click
// objectDrag         → typedSolution.drag

GeeTest

// nine-grid (question + images required)
await solver.solveGeetest({ type: "nine", question: "Select all bicycles", images: tiles });

// click / icon (question + images required)
await solver.solveGeetest({ type: "click", question: "the bear", images: tiles });

// slide puzzle (piece + background)
await solver.solveGeetest({ type: "slide", images: [piece], examples: [background] });

// swap puzzles
await solver.solveGeetest({ type: "match" });
await solver.solveGeetest({ type: "winlinze" });

Returns: grid/click types land in typedSolution.grid.objects (or typedSolution.click); slide returns typedSolution.slide.x.

Accepted type aliases:

OCR / image-to-text

await solver.solveOcr({ images: [img] });                                  // general OCR
await solver.solveOcr({ images: [img], module: "mtcaptcha", maxLength: 4 });
await solver.solveOcr({ images: imgs, module: "bls", numeric: true, maxLength: 3 });
// → result.typedSolution.text.texts[0]

TikTok

await solver.solveTikTok({ type: "click", question: "Select the shape", images });
await solver.solveTikTok({ type: "whirl", question: "Rotate to match", images, examples }); // examples required
await solver.solveTikTok({ type: "slide", question: "Slide to fit", images, examples });    // examples required

Returns: click lands in typedSolution.click; whirl/slide return typedSolution.slide.x.

type accepts "click"/"tiktok_click", "whirl"/"tiktok_whirl", "slide"/"tiktok_slide".

Binance

await solver.solveBinance({ type: "grid", question: "Select the bicycle", images });
await solver.solveBinance({ type: "slide", images: [puzzle], examples: [background] });

Returns: grid lands in typedSolution.grid.objects; slide returns typedSolution.slide.x.

type accepts "grid"/"binance_grid" and "slide"/"binance_slide".

AWS WAF

solveAwsWaf takes positional arguments. The question is formatted as "type:category:target".

await solver.solveAwsWaf(tiles, "grid:vehicles:cars");

Returns: selected tile indices in typedSolution.grid.objects.

Slide image (local, no AI)

Detects the slide offset locally using contour detection. Accepts one combined image, or [background, piece].

const r = await solver.solveSlideImage({ images: ["slide_bg.png", "piece.png"] });
console.log(r.typedSolution?.slide?.x); // pixel offset, e.g. 142

Returns: the slide offset in pixels at typedSolution.slide.x.

Token methods (browser automation)

These submit a task and poll internally until a token is returned (up to the polling timeout, 120s by default).

await solver.solveTurnstile({ websiteURL, websiteKey, proxy });          // proxy optional
await solver.solveRecaptchaV2Token({ websiteURL, websiteKey, proxy });   // proxy optional
await solver.solveRecaptchaV3Token({ websiteURL, websiteKey, proxy });   // proxy optional
await solver.solvePopularCaptchaToken({ websiteURL, websiteKey, proxy, metadata }); // proxy optional
await solver.solveCloudflare({ websiteURL, websiteKey, proxy });         // proxy REQUIRED

solver.solve_turnstile(website_url=..., website_key=..., proxy=...)             # proxy optional
solver.solve_recaptcha_v2_token(website_url=..., website_key=..., proxy=...)    # proxy optional
solver.solve_recaptcha_v3_token(website_url=..., website_key=..., proxy=...)    # proxy optional
solver.solve_popular_captcha_token(website_url=..., website_key=..., proxy=...) # proxy optional
solver.solve_cloudflare(website_url=..., website_key=..., proxy=...)            # proxy REQUIRED

Returns: the token in the solution map of the response (for example result.solution.token or result.solution.gRecaptchaResponse, depending on the captcha).

TypeScript Usage

The SDK exports types for every option object and response. Import them with import type.

import { CaptchaSonic } from "captchasonic";
import type { SolveGeetestOptions, GetTaskResultResponse } from "captchasonic";

const solver = new CaptchaSonic(process.env.CAPTCHASONIC_API_KEY!);

const opts: SolveGeetestOptions = {
  type: "nine",
  question: "Select all bicycles",
  images: tiles,
};

const result = await solver.solveGeetest(opts);
console.log(result.typedSolution?.grid?.objects);

Exported types

import type {
  CaptchaSonicOptions,
  ImageInput,
  SolvePopularCaptchaOptions,
  SolveRecaptchaV2Options,
  SolveGeetestOptions,
  SolveOcrOptions,
  SolveTikTokOptions,
  SolveBinanceOptions,
  SolveTurnstileOptions,
  SolvePopularCaptchaTokenOptions,
  SolveRecaptchaV2TokenOptions,
  SolveRecaptchaV3TokenOptions,
  SolveCloudflareOptions,
  SolveSlideImageOptions,
  GeetestSubtype,
  TikTokSubtype,
  BinanceSubtype,
  Task,
  CreateTaskResponse,
  GetTaskResultResponse,
} from "captchasonic";

ImageInput is Uint8Array | Buffer | string.

Proxy Support

Token / browser-automation methods accept an optional proxy string in the form http://user:pass@host:port:

await solver.solveTurnstile({
  websiteURL: "https://example.com",
  websiteKey: "0x4AAAAAAA...",
  proxy: "http://user:[email protected]:8080",
});

For enterprise hCaptcha you can also pass metadata (rqdata, rqtoken, fingerprint) to solvePopularCaptchaToken.

Configuration

Pass an options object as the second constructor argument. Only the options below are supported.

const solver = new CaptchaSonic("YOUR_API_KEY", {
  transport: "connect",   // "grpc" (default) | "connect" | "http"
  timeout: 180_000,       // max poll wait in ms (alias: timeoutMs); per-call default 30000
  pollingInterval: 5_000, // polling frequency in ms (default 2000)
  baseUrl: "https://api.captchasonic.com", // override endpoint (alias: url)
});

Transports

Error Handling

All API-level failures throw a SonicError, which extends the built-in Error. It carries a numeric errorId and sets name to the matching error name.

import { CaptchaSonic, SonicError } from "captchasonic";

try {
  const result = await solver.solveGeetest({ type: "nine", question: "bicycles", images });
} catch (err) {
  if (err instanceof SonicError) {
    console.error(err.errorId); // 1–6
    console.error(err.name);    // e.g. "InvalidApiKeyError"
    console.error(err.message);
  } else {
    throw err; // network / unexpected
  }
}

Account Helpers

const balance = await solver.getBalance(); // → number (USD)

const health = await solver.healthCheck(); // → { healthy: boolean, version: string }

Low-level task methods are available if you need direct control over submission and polling:

const created = await solver.createTask(task);        // submit a Partial<Task>
const result  = await solver.getTaskResult(taskId);   // poll for a result

Troubleshooting

require is not defined / Cannot use import statement outside a module — the package is ESM only. Use import in an ESM project, or await import("captchasonic") from CommonJS. See Installation.

grpc transport fails in the browser — native gRPC is Node.js only. Switch to transport: "connect" or transport: "http".

InvalidApiKeyError on every call — confirm the key is passed as the first constructor argument and not accidentally undefined (e.g. a missing env var).

Token method times out — token tasks poll up to timeout ms (default 120000). Increase timeout and verify the websiteURL / websiteKey match the target page. For Cloudflare, a valid proxy is required.

File-path images don't load — string file paths are read synchronously and are Node.js only; in the browser pass a Uint8Array instead.

Resources

• npm package
• API reference
• CaptchaSonic dashboard & docs