hCaptcha solver API for JavaScript and TypeScript

Use the typed easycaptcha JavaScript SDK with fetch, axios, ky, or XHR. Create token jobs, wait for completion, and keep API credentials on the server.

Start with the fetch backend

The JavaScript SDK is asynchronous and ships TypeScript declarations. Its public job request type is a union: recognition, regular token, and enterprise token requests have their own required fields. Transport subclasses expose the same methods, so changing the HTTP backend does not change your application lifecycle.

npm install @easycaptcha-to/sdk

Import FetchClient from @easycaptcha-to/sdk/fetch. The axios and ky backends have separate import paths and require their respective HTTP packages. XHR is also available for environments with XMLHttpRequest. Use Node.js 20 or newer for the native-fetch example below.

Wait for a terminal result

Set EASYCAPTCHA_API_KEY, HCAPTCHA_SITEKEY, and HCAPTCHA_PAGE_URL in your server environment. Save this example as solve.mjs.

import { setTimeout as sleep } from "node:timers/promises";
import { FetchClient } from "@easycaptcha-to/sdk/fetch";

const client = new FetchClient({
  apiKey: process.env.EASYCAPTCHA_API_KEY,
});
let job = await client.createJob({
  type: "hcaptcha_token",
  sitekey: process.env.HCAPTCHA_SITEKEY,
  url: process.env.HCAPTCHA_PAGE_URL,
  hold: 30,
});
const jobId = job.task_id;
console.log(`Task ID: ${jobId}`);
const deadline = performance.now() + 180_000;
while (job.status === "queued" || job.status === "running") {
  if (performance.now() >= deadline) {
    throw new Error(`Retrieve ${jobId} again later`);
  }
  await sleep(1000);
  job = await client.getJob(jobId);
}
if (job.status === "failed") {
  throw new Error(job.error.detail);
}
const token = job.result.token;
// Pass token to your application's completion handler.

A job being created is different from a job completing. hold can reduce the number of lookups when completion is quick; it does not remove the need to handle queued, running, and failed results. getJob makes one lookup, so your program controls polling and its own deadline.

Keep credentials out of public bundles

The SDK can run in a browser, but placing a private paid account key in browser JavaScript exposes it to visitors. Put customer-key requests behind your own server when building a public application. Your server should decide which operations a user may create; it should not expose an unrestricted proxy to your account balance.

Aborting a request stops that client from waiting. It does not cancel a server-side job. Preserve its ID, and avoid automatically retrying task creation after an uncertain timeout. Use sendFeedback(jobId, success) only after your application observes the result being accepted or rejected.

Recognition and enterprise tasks

For recognition, supply the existing challenge object in task with type: "hcaptcha_recognition". The optional sitekey attributes that challenge to its originating site. For enterprise tokens, the request type is hcaptcha_enterprise_token, and the integration’s rqdata is required. Enterprise access must be approved first.

The API reference defines fields and result shapes. The Python guide shows the same workflow in another language, and browser testing explains how to keep live verification out of routine application tests.