GeeTest v4 in Node.js: Batch Sign-Ups With fetch and Types

To solve GeeTest v4 in Node.js without a browser, read the captcha_id from the page once, call solver.geetestV4() from the capskip package with that id and the page address, and send the five fields it returns under the same names in the request the page makes itself. The script below does that for six sign-ups with the built-in fetch, one fresh solve per submission, and ends with Promise.allSettled. The tasks are solved by the CapSkip GeeTest v4 solver on your own Windows PC, with no fee per solve.
What you need
- A Windows machine with CapSkip 5.0.0 or a later version, the first release that solves GeeTest v4 according to the changelog.
- Node.js 18 or newer, which is what the engines field of capskip 1.8.0 declares. That is the first SDK version with geetestV4(). My runs covered 20.11.1, 24.22.0 and 25.2.1, so I never ran Node.js 18 itself.
- TypeScript, but only for the optional type check. At the time of writing npm resolved typescript 7.0.2, which declares Node.js 16.20 or later, and @types/node 26.6.6.
- A sign-up or login page with a GeeTest v4 widget that you may automate.
- An address for CapSkip. Local mode keeps it on 127.0.0.1. Server mode also accepts connections from your network or a public IP, and the Connection Settings section of the setup guide describes both modes.
Every run below used two small servers I wrote, one imitating the CapSkip API and one imitating a sign-up page, which makes the site rules mine. The real CapSkip app wasn’t answering on this PC when I tested, so I sent it nothing, and no GeeTest site saw a request. Where a claim rests on the CapSkip docs, the SDK source or the GeeTest docs instead of a run, I say so. A real site checks the five fields on its own server, with its private key, through the GeeTest server validation API.
Step 1: set up the folder
Run the first block in an empty folder. It creates package.json, installs capskip and adds TypeScript for the type check. Save the tsconfig block as tsconfig.json. Then save the four JavaScript blocks of Steps 2 to 5, in order, as one file named geetest_v4.mjs. The .mjs extension allows top-level await. Before the first run, change ORIGIN, the two paths and the emails to your own site. Left as they are, the script asks example.com and stops with "the page answered HTTP 404".
# Run in an empty folder, in PowerShell or any other shell npm init -y npm install capskip npm install --save-dev typescript @types/node
{
"compilerOptions": {
"target": "es2022",
"module": "node16",
"moduleResolution": "node16",
"allowJs": true,
"checkJs": true,
"noEmit": true,
"strict": true,
"skipLibCheck": true,
"types": ["node"]
},
"files": ["geetest_v4.mjs"]
}With this file, tsc reads the script as typed JavaScript. The package ships GeetestV4Options and a SolveResult whose five GeeTest fields are optional, so Step 3 has a guard.
Step 2: read the captcha_id once
The page passes the id to initGeetest4 as captchaId, and the request to gcaptcha4.geetest.com/load carries it as captcha_id, according to the CapSkip GeeTest v4 API docs. It is the same for every visitor, so readCaptchaId keeps its promise in a variable and fetches the page once per run, however many submissions follow. It collects every match in a Set and refuses to guess: two different ids, or none, make every submission fail before any solve is bought. It also caches a rejected promise, so one page timeout fails the whole run.
// @ts-check
// npm install capskip
import {
CapSkip, ApiException, NetworkException, TimeoutException, ValidationException,
} from "capskip";
const ORIGIN = "https://example.com";
const PAGE_URL = `${ORIGIN}/signup`; // the page that shows the widget
const API_URL = `${ORIGIN}/api/signup`; // where the page's own submit sends its JSON
// Local mode. In Server mode, use the address of the PC that runs CapSkip.
const solver = new CapSkip({ host: "127.0.0.1", port: 8080 });
/** @type {Promise<string> | undefined} */
let idRead;
// The captcha_id is the same for every visitor, so read it once per run.
function readCaptchaId() {
idRead ??= (async () => {
const res = await fetch(PAGE_URL, { signal: AbortSignal.timeout(10_000) });
if (!res.ok) throw new Error(`the page answered HTTP ${res.status}`);
const html = await res.text();
const pattern = /captchaId["']?\s*:\s*["']([0-9a-f]{32})["']|[?&]captcha_id=([0-9a-f]{32})/gi;
const ids = new Set([...html.matchAll(pattern)].map((m) => (m[1] ?? m[2]).toLowerCase()));
if (ids.size !== 1) throw new Error(`expected one captcha_id in the page, found ${ids.size}`);
return [...ids][0];
})();
return idRead;
}On my mock page the id came out right when the page wrote it with double quotes, with single quotes and the key on its own line, as a quoted key in a JSON-style object, and in the load URL. A page with an older id left in a comment beside the real one stopped with "found 2", and a page whose script builds the id elsewhere stopped with "found 0". The pattern expects 32 hexadecimal characters, like the ids in the docs.
Step 3: ask for the five fields with typed options
The call is solver.geetestV4(captchaId, url, options). It submits a task, polls for the result and resolves to an object. The API docs say res.php sends the five values as one JSON string in its request field, which is why code is a string: the SDK parses it a second time and copies captcha_id, lot_number, pass_token, gen_time and captcha_output onto the result, plus isOffline when GeeTest couldn’t be reached. Per the SDK source, a string that doesn’t parse leaves the result unexpanded and raises no error, so fiveFields throws unless all five are present.
/** @typedef {"slide" | "icon" | "nine" | "word" | "phrase" | "match" | "winlinze" | "svg_seed" | "svg_icon" | "ai"} RiskType */
const NAMES = /** @type {const} */ (["captcha_id", "lot_number", "pass_token", "gen_time", "captcha_output"]);
// All five fields or an error: the SDK hands back an answer it cannot parse untouched.
/** @param {import("capskip").SolveResult} result */
function fiveFields(result) {
/** @type {Record<string, string>} */
const fields = {};
for (const name of NAMES) {
if (!result[name]) {
throw new Error(`the answer has no ${name}; code starts: ${String(result.code).slice(0, 40)}`);
}
fields[name] = String(result[name]);
}
return { fields, offline: result.isOffline === true };
}
/** @param {RiskType} [riskType] */
async function solveOnce(riskType) {
/** @type {import("capskip").GeetestV4Options & { riskType?: RiskType }} */
const options = { timeout: 60, polling_interval: 2 }; // both in seconds
if (riskType) options.riskType = riskType;
const result = await solver.geetestV4(await readCaptchaId(), PAGE_URL, options);
return fiveFields(result);
}Two names look alike. captcha_id is the widget id that GeeTest echoes back, and it is the one to send. captchaId is the id CapSkip gave the task. The result carries both, and the SDK example prints captchaId under the label Captcha ID. On my mock the task id was 102, and posting it as captcha_id was refused.
The docs list ten values for riskType: slide, icon, nine, word, phrase, match, winlinze, svg_seed, svg_icon and ai. GeeTest applies one only where the site allows it, and the site’s own choice usually wins, so I couldn’t test the effect. The SDK’s own definition types riskType as a plain string, and at run time the SDK checks only that it is a string, so a typo travels on: my mock received risk_type slid untouched. The RiskType typedef catches it, and tsc rejected the call with error TS2345. It can’t catch a misspelt option name, because the options type allows other keys. An option called risktype compiled, then the SDK refused it at run time as an unsupported parameter.
The timeout and polling_interval options are in seconds. Without timeout the client default of 300 seconds applies, and the SDK takes no AbortSignal, so set timeout instead of racing a signal: the polling stops with it. The SDK checks the deadline only when the next poll is due. Against a mock that never answered, timeout 5 ended after 7.9 seconds with the default interval of 5, and after 5.9 with polling_interval 2. A tight timeout can also lose a finished answer, as the table below shows. Leave room for the solve plus one interval. AsyncCapSkip is the same class under another name, since every method already returns a promise.
The proxy option takes a string or an object with type and uri. With a string, proxytype defaults to HTTP, and my mock saw the object form arrive as a proxy value plus proxytype SOCKS5. It reaches the CapSkip solve only, and my fetch calls don’t use it. The CapSkip docs advise a proxy pool beyond occasional solves. I tested no real proxy.
Eleven mistakes were refused by the SDK with ValidationException before anything reached my mock’s in.php: no captcha id, a missing, relative or ftp page address, the v3 parameters gt and challenge, a userAgent option, an unknown option name, a number as riskType, proxytype SOCKS4 and a proxy object without uri. The userAgent refusal is worth knowing, because the MTCaptcha and Yandex SmartCaptcha methods accept one and GeeTest v4 doesn’t. The docs say the app answers ERROR_BAD_PARAMETERS for a missing captcha_id or an unsupported proxytype and ERROR_PAGEURL for a missing or malformed page address. For the other refusals the docs say nothing, and the SDK stops them first.
Step 4: send the five fields as JSON
The CapSkip docs say to send the fields under those names in the request the page’s own submit makes, unchanged, and to solve again for every submission. My mock page submits JSON with the email and the five fields, so submit does the same. If your page sends a form, replace the body with new URLSearchParams and drop the content type header.
/**
* @param {string} email
* @param {RiskType} [riskType]
*/
async function submit(email, riskType) {
const { fields, offline } = await solveOnce(riskType); // one solve per submission
const res = await fetch(API_URL, {
method: "POST",
// fetch adds no Origin or Referer by itself, and a CSRF check may want them.
headers: { "Content-Type": "application/json", Origin: ORIGIN, Referer: PAGE_URL },
body: JSON.stringify({ email, ...fields }),
signal: AbortSignal.timeout(10_000),
});
const body = (await res.text()).slice(0, 60);
if (!res.ok) throw new Error(`HTTP ${res.status} ${body}`);
return `${email}: HTTP ${res.status}${offline ? " (offline pass)" : ""}`;
}The two headers matter because fetch adds neither Origin nor Referer. With both headers removed my mock answered all six submissions with 403 and a csrf error, after six solves had been spent. With only one of the two it accepted them. That is my mock’s rule and your site has its own, so send one trial submission before a batch.
Never reuse an answer. When I sent the same five fields twice, my mock answered 200 and then 403 with captcha used. Whether GeeTest itself accepts a replay, I couldn’t test.
The isOffline flag is for the case where GeeTest itself couldn’t be reached. The docs say the widget then passes without a challenge, the answer carries isOffline set to true, and the site decides on its server whether to accept it. The setup guide explains an Offline pass label in the Monitor tab, and submit adds the words offline pass to its result line. With every second answer offline, a mock site that refuses offline passes took three of six, and one that accepts them took all six.
Step 5: GeeTest v4 in Node.js with Promise.allSettled
The setup guide says CapSkip solves only as many tasks of one type at once as its Max. Threads setting allows. The others wait for a free thread for up to Wait Timeout seconds, and your call timeout keeps running meanwhile. The loop below sends WAVE submissions, waits for all of them with Promise.allSettled and starts the next wave. allSettled never rejects, so the script sets the exit code itself, and describe turns each of the four SDK exception classes into one line.
const WAVE = 3; // keep this at or below Max. Threads for GeeTest in CapSkip
/** @param {unknown} err */
function describe(err) {
if (err instanceof ValidationException) return `refused before sending: ${err.message}`;
if (err instanceof TimeoutException) return `no answer in time: ${err.message}`;
if (err instanceof NetworkException) return `CapSkip not reachable: ${err.message}`;
if (err instanceof ApiException) return `CapSkip error: ${err.message}`;
return err instanceof Error ? err.message : String(err);
}
const emails = [
"[email protected]", "[email protected]", "[email protected]",
"[email protected]", "[email protected]", "[email protected]",
];
/** @type {PromiseSettledResult<string>[]} */
const settled = [];
for (let i = 0; i < emails.length; i += WAVE) {
const wave = emails.slice(i, i + WAVE).map((email) => submit(email));
settled.push(...(await Promise.allSettled(wave)));
}
settled.forEach((s, i) => {
console.log(s.status === "fulfilled" ? `ok ${s.value}` : `FAIL ${emails[i]}: ${describe(s.reason)}`);
});
process.exitCode = settled.every((s) => s.status === "fulfilled") ? 0 : 1;Check the types, then run it. It prints one line per email.
# Check the types, then run the script npx tsc node geetest_v4.mjs
These rows are mock results from Node.js 24.22.0 on Windows 11 with capskip 1.8.0, timed from process start to exit. The counts matched on 20.11.1 and 25.2.1, and timings agreed within 0.3 seconds.
| Mock setting | What the script did |
|---|---|
| Six submissions, solve 2 seconds, 3 slots; WAVE 3, 6 or 1 | Six in each case, in 7.7, 5.9 and 22.9 seconds; at most 3, 3 and 1 task at once |
| Call timeout 4, polling_interval 1, solve 2 seconds, 3 slots; WAVE 3 or 6 | WAVE 3: six in, 5.7 seconds. WAVE 6: three in, three "timeout 4 exceeded" at 4.9 |
| Solve 2 seconds, timeout 3; polling_interval 2 or 1 | 2: all three "timeout 3 exceeded" at 3.9 seconds. 1: all three in, 2.9 seconds |
| Answer never ready, timeout 5; polling_interval 5, 2 or 1 | TimeoutException after 7.9, 5.9 and 5.9 seconds |
| Origin and Referer headers removed | Six refused with 403 csrf, after six solves were spent |
| The same five fields sent twice | 200, then 403 "captcha used" |
| Every second answer offline; the site refuses or accepts offline passes | Three in and three refused, or all six in |
| The answer is not JSON, or lot_number is missing | Six guard errors and no request to the site |
| The first two tasks end in ERROR_CAPTCHA_UNSOLVABLE | Two FAIL lines, four in |
Waves cost time when the timeout is generous: six submissions at once took 5.9 seconds against 7.7 for waves of three, because a wave waits for its slowest member before the next one starts. They pay off when the call timeout is tight, as the second row shows. With a timeout of 4 seconds, the three tasks that queued behind a full house ran out of time. The third row is the lost answer: the mock had it at 2 seconds, but the last poll came at 1.8 seconds and the next was due at 3.8, past the deadline. Keep WAVE at or below the Max. Threads value of the GeeTest row in CapSkip.
Common errors
Unless a row says seen, it comes from the CapSkip GeeTest v4 API docs.
| Error | Cause | Fix |
|---|---|---|
| ValidationException | Refused inside the SDK, nothing sent (seen, eleven cases) | Read the message |
| ERROR_BAD_PARAMETERS | Per the docs: no captcha_id, or a proxytype that is not accepted | The SDK refuses both first |
| ERROR_PAGEURL | Per the docs: the page address is missing or malformed | Pass the full page address |
| ERROR_PROXY_FORMAT | Per the docs: a proxy value CapSkip can’t parse | Use IP:PORT or login:password@IP:PORT |
| ERROR_CAPTCHA_UNSOLVABLE | Per the docs: the task couldn’t be solved. My mock produced it for two tasks | Run the failed emails again |
| ERROR_KEY_DOES_NOT_EXIST | API Key Validation is on. Without apiKey the SDK sent the key capskip, and my mock refused it | Pass your key as apiKey |
| TimeoutException | No answer within timeout (seen) | Raise timeout or lower polling_interval |
| NetworkException | connect ECONNREFUSED when nothing listened (seen) | Start CapSkip, check host and port |
| HTTP 403 from the site | The site’s own rule: headers, a used answer or an offline pass | Compare with the page’s own request |
FAQ
Can I run the script on a different PC from CapSkip?
Yes. Put CapSkip in Server mode and set the host option to the address of its PC, which is the only line that changes. The setup guide notes that Server mode needs administrator rights. My advice, not a setup guide claim: assume the port is open to every address in Server mode, add a Windows Firewall block rule for the machines you don’t expect, and turn on API Key Validation so each call must carry a key.
Can one solve serve several submissions?
No. The docs say to solve again for every submission, and my mock refused a replay.
Does this work on a page that hands out gt and a challenge?
No, that is GeeTest v3, and the SDK refuses gt and challenge in a v4 call. For that generation, follow the GeeTest v3 guide for Node.js.
GeeTest v4 in Node.js comes down to one id read per run, one solve per submission and five fields copied under their own names. A refused submission or a second solve never reaches a bill, since this local captcha solver runs on your own PC. The Node.js CAPTCHA solver page lists the other CAPTCHA types.
