To solve CaptchaFox in Node.js, call the captchafox method of the capskip package with the sitekey and the page URL, then post the token it returns in the cf-captcha-response field. Send that post with three things fetch will not add for you: the cookies the page set, a Referer, and the user agent CapSkip returned next to the token. The user agent is the trap most Node code falls into. Node’s built-in fetch tells every server that its user agent is node, and a site that expects the token from the browser that minted it turns that post down, however good the solve was. CapSkip added CaptchaFox in version 1.4.0. This guide covers reading the key, the call, the submit, retries and running many sign-ups at once.<\/p>\n
# capskip 1.3.0 added captchafox(); cheerio reads the HTML\nnpm install capskip cheerio<\/pre>\n<\/div>\nThe samples are ES modules with top-level await. Save them with an .mjs extension, or set the type field in your package.json to module, since npm init now writes commonjs there. The capskip package also loads with require if your project is CommonJS.<\/p>\n
Step 1: fetch the page, keep its cookies and read the sitekey<\/h2>\n
Node’s fetch keeps no cookies between calls, so the session cookie the page sets is gone by the time you post the form. A site that ties its CSRF token to that session then rejects the post. Carry the cookies yourself with Headers.getSetCookie(), which returns each Set-Cookie line on its own. The guide to solving Friendly Captcha in Node.js<\/a> explains this small jar in more detail.<\/p>\n
\n\/\/ npm install capskip cheerio\nimport * as cheerio from "cheerio";\n\nconst PAGE_URL = "https:\/\/example.com\/signup";\n\n\/\/ fetch() keeps no cookies between calls, so carry the page's own.\nconst jar = new Map();\nconst page = await fetch(PAGE_URL);\nfor (const line of page.headers.getSetCookie()) {\n const pair = line.split(";")[0];\n const eq = pair.indexOf("=");\n jar.set(pair.slice(0, eq).trim(), pair.slice(eq + 1).trim());\n}\nconst html = await page.text();\nconst $ = cheerio.load(html);<\/pre>\n<\/div>\nThe sitekey is public, identical for every visitor, and conventionally starts with sk_. Most pages put it on the widget’s container, a div with the class captchafox and a data-sitekey attribute. A page that builds the widget from its own script passes the key to a captchafox.render call instead. When neither is in the HTML you fetched, open DevTools: the key is the path segment after \/captcha\/ in a request to api.captchafox.com, or to mam-api.captchafox.com on MAM pages.<\/p>\n
Check which build loads the widget while you are there. Most sites load it from cdn.captchafox.com and expect a plain token. Some platforms embed a package from s.uicdn.com\/mampkg\/ instead, and those sites expect a token that starts with MAM_. A MAM page may carry the key in that script’s own address, after ?key=. The same CDN serves unrelated packages too, so match the captchafox package path rather than the host.<\/p>\n
\n\/\/ The container, matched on the whole class name.\nconst widget = $(".captchafox").first();\n\/\/ MAM pages may carry the key in the package's script src instead.\nconst mamSrc = $('script[src*="mampkg\/@mamdev\/core.frontend.libs.captchafox"]').attr("src");\nconst sitekey = widget.attr("data-sitekey")\n ?? (mamSrc && new URL(mamSrc, PAGE_URL).searchParams.get("key"))\n ?? html.match(\/captchafox\\.render\\([\\s\\S]{0,300}?sitekey\\s*:\\s*["']([^"']+)\/)?.[1];\nconst form = widget.length ? widget.closest("form") : $("form").first();\n\nconsole.log(sitekey, Boolean(mamSrc)); \/\/ a MAM page needs a MAM_ token<\/pre>\n<\/div>\ncheerio’s class selector matches whole class names, so a wrapper element with a class such as captchafox-wrapper is not picked up by accident. The last fallback reads a key passed inline to the render call. A key that lives in a bundled script file is not in the HTML at all, and DevTools is the way to find it. Without a container, the code takes the first form on the page. If the page also has a search box or a second form, select the sign-up form by its id or its action instead.<\/p>\n
Step 2: the captchafox call<\/h2>\n
To solve CaptchaFox in Node.js you need one method. It takes the sitekey, the page URL and an optional options object, and for the standard widget the first two are all it needs.<\/p>\n
\nimport { CapSkip } from "capskip";\n\nconst solver = new CapSkip({ host: "127.0.0.1", port: 8080 });\n\/\/ Copied from the script tag on MAM pages.\nconst MAM_PACKAGE = "https:\/\/s.uicdn.com\/mampkg\/@mamdev\/core.frontend.libs.captchafox\/";\n\nconst result = await solver.captchafox(sitekey, PAGE_URL, {\n \/\/ undefined is dropped, so the standard widget sends nothing extra.\n apiServer: mamSrc ? MAM_PACKAGE : undefined,\n});\n\nconsole.log(result.token.slice(0, 24)); \/\/ goes in cf-captcha-response\nconsole.log(result.userAgent); \/\/ the browser that minted it<\/pre>\n<\/div>\nresult.token and result.code hold the same string, and result.captchaId is CapSkip’s id for the job. result.userAgent is the identity of the browser that minted the token, which is CapSkip’s own browser and not anything you sent. It is only set when the solve reported one, so test it before you use it.<\/p>\n
The page URL has to be the page the widget really runs on. CaptchaFox registers every key against a list of allowed domains and checks the host before it issues anything. A page URL on any other domain is refused on every attempt, so a shortened link, a search result or a redirect from another domain will not do.<\/p>\n
Options the method accepts<\/h3>\n
apiServer is an alias of api_server, the widget build to solve. The method drops any option whose value is undefined or null, which is why the line above can pass it on every call. It also takes a proxy object with type and uri keys, and useragent, which is accepted and deliberately not applied, because CapSkip solves in a real browser with its own identity. A per-call timeout in seconds replaces the client’s recaptchaTimeout for that one solve. The poll ceiling can be set per call too, but only as polling_interval: the camelCase pollingInterval belongs to the constructor, and passed per call it throws ValidationException. An empty sitekey or URL, an unknown option and a proxy type other than HTTP, HTTPS, SOCKS5 or SOCKS5H throw ValidationException too, before any request leaves your machine.<\/p>\n
In TypeScript, the bundled types still describe token as optional and meant for ALTCHA, so strict mode needs a non-null assertion on result.token. The value is there for every CaptchaFox solve.<\/p>\n
Step 3: submit under the user agent that minted the token<\/h2>\n
When you solve CaptchaFox in Node.js, this is the step that decides whether the site takes the token. Out of the box, Node’s fetch sends a User-Agent header with the single word node in it, on Node 20 and on Node 25 alike. That is not the browser that produced the token, so copy the returned value onto the request that carries it:<\/p>\n
\n\/\/ The form's own fields, hidden CSRF token included.\nconst body = new URLSearchParams(\n form.serializeArray().map((f) => [f.name, f.value]),\n);\nbody.set("email", "YOUR_EMAIL");\nbody.set("cf-captcha-response", result.token);\n\nconst headers = {\n cookie: [...jar].map(([k, v]) => `${k}=${v}`).join("; "),\n \/\/ Browsers send the page as Referer; strict servers want one.\n referer: PAGE_URL,\n};\n\/\/ Without this line, fetch announces itself as user-agent: node.\nif (result.userAgent) headers["user-agent"] = result.userAgent;\n\nconst res = await fetch(new URL(form.attr("action") || PAGE_URL, PAGE_URL), {\n method: "POST",\n headers,\n body,\n});\nconsole.log(res.status);<\/pre>\n<\/div>\nserializeArray collects the fields a browser would send, the hidden CSRF token and any ticked checkbox included, so you never have to name them. It leaves out the submit button, so if the server checks for the button’s name, add it with body.set. The Referer matters as much as the cookie. fetch sends no Referer and no Origin, and some frameworks, Django among them, refuse an HTTPS form post that has neither, even with the right cookie and token.<\/p>\n
Two more rules come from how CaptchaFox checks the token on the site’s side. Each token verifies once and only for a short time, so solve when you are ready and submit straight away. And treat the token as opaque: never trim or re-encode it. Some sites send it in a JSON body from their own script, so submit the form once by hand with DevTools open and mirror what the page sends. CaptchaFox’s getting started documentation<\/a> shows the widget markup and the server-side check.<\/p>\n
Step 4: retries, challenge types and timeouts<\/h2>\n
You do not choose which challenge CaptchaFox draws. Most solves draw nothing at all, because the browser evidence clears on its own, and when a slide puzzle appears CapSkip usually completes it. Image-select and audio challenges are rare and are not solved: they come back as an ApiException whose message contains ERROR_CAPTCHA_UNSOLVABLE, within seconds rather than at the end of the timeout. A fresh attempt usually draws something else, so retrying is worth it, either in CapSkip or in your code.<\/p>\n
\nimport { ApiException } from "capskip";\n\nasync function solveCaptchaFox(sitekey, url, options = {}, attempts = 3) {\n for (let attempt = 1; ; attempt++) {\n try {\n return await solver.captchafox(sitekey, url, options);\n } catch (err) {\n \/\/ Select, audio and unreadable slide draws come back unsolvable;\n \/\/ redraw. Anything else, such as a wrong API key, is final.\n const redraw = err instanceof ApiException && err.message.includes("UNSOLVABLE");\n if (!redraw || attempt === attempts) throw err;\n }\n }\n}<\/pre>\n<\/div>\nThe ApiException message is the raw reply from CapSkip, so the check reads the error code straight out of it. One catch: a key the site refuses, for example on the wrong domain, also reads as unsolvable, so it gets retried too. It fails within seconds on every attempt and never succeeds, which is the tell. The other route is the Retries setting in the CaptchaFox row of CapSkip’s settings. It takes 0 to 3 and is 0 by default. CapSkip then retries unsupported challenges, timed-out attempts and browser errors on its own, but never a refused key.<\/p>\n
captchafox polls on the client’s recaptchaTimeout, 300 seconds by default, because it is a real browser session. CapSkip runs its own clock as well: a task can wait up to 250 seconds (Wait Timeout) for one of the 10 CaptchaFox threads (Max. Threads), and a single attempt gets 150 seconds (Row Timeout). With a thread free, a failed attempt reaches you as an ApiException well inside the SDK’s 300 seconds. After a long queue, the SDK can hit its limit first and throw TimeoutException while CapSkip is still working. So pass a longer timeout when you queue many solves or raise Retries, since each retry can add another Row Timeout. The SDK also polls straight through connection errors, so if CapSkip stops mid-solve the call ends in TimeoutException, not NetworkException.<\/p>\n
Full working example<\/h2>\n
Here is the whole run in one file. signUp fetches the page, reads the key, solves with retries and posts the form with its cookies, a Referer and the minting user agent.<\/p>\n
\n\/\/ npm install capskip cheerio\n\/\/ signup.mjs: run with node signup.mjs\nimport * as cheerio from "cheerio";\nimport {\n CapSkip, ApiException, CapSkipError, TimeoutException, ValidationException,\n} from "capskip";\n\nconst PAGE_URL = "https:\/\/example.com\/signup";\n\/\/ Copied from the script tag on MAM pages.\nconst MAM_PACKAGE = "https:\/\/s.uicdn.com\/mampkg\/@mamdev\/core.frontend.libs.captchafox\/";\n\nconst solver = new CapSkip({\n apiKey: process.env.CAPSKIP_API_KEY ?? "capskip",\n host: process.env.CAPSKIP_HOST ?? "127.0.0.1",\n port: Number(process.env.CAPSKIP_PORT ?? 8080),\n});\n\nasync function solveCaptchaFox(sitekey, url, options = {}, attempts = 3) {\n for (let attempt = 1; ; attempt++) {\n try {\n return await solver.captchafox(sitekey, url, options);\n } catch (err) {\n \/\/ Select, audio and unreadable slide draws come back unsolvable.\n const redraw = err instanceof ApiException && err.message.includes("UNSOLVABLE");\n if (!redraw || attempt === attempts) throw err;\n console.log(`attempt ${attempt}: ${err.message}`);\n }\n }\n}\n\nasync function signUp(pageUrl, email) {\n \/\/ One jar per run, so runs side by side never share a session.\n const jar = new Map();\n const page = await fetch(pageUrl);\n for (const line of page.headers.getSetCookie()) {\n const pair = line.split(";")[0];\n const eq = pair.indexOf("=");\n jar.set(pair.slice(0, eq).trim(), pair.slice(eq + 1).trim());\n }\n const html = await page.text();\n const $ = cheerio.load(html);\n\n const widget = $(".captchafox").first();\n const mamSrc = $('script[src*="mampkg\/@mamdev\/core.frontend.libs.captchafox"]').attr("src");\n const sitekey = widget.attr("data-sitekey")\n ?? (mamSrc && new URL(mamSrc, pageUrl).searchParams.get("key"))\n ?? html.match(\/captchafox\\.render\\([\\s\\S]{0,300}?sitekey\\s*:\\s*["']([^"']+)\/)?.[1];\n if (!sitekey) throw new Error("No sitekey in the HTML; find it in DevTools.");\n const form = widget.length ? widget.closest("form") : $("form").first();\n\n const result = await solveCaptchaFox(sitekey, pageUrl, {\n apiServer: mamSrc ? MAM_PACKAGE : undefined,\n });\n\n const body = new URLSearchParams(form.serializeArray().map((f) => [f.name, f.value]));\n body.set("email", email);\n body.set("cf-captcha-response", result.token);\n const headers = {\n cookie: [...jar].map(([k, v]) => `${k}=${v}`).join("; "),\n referer: pageUrl,\n };\n if (result.userAgent) headers["user-agent"] = result.userAgent;\n\n const action = new URL(form.attr("action") || pageUrl, pageUrl);\n return fetch(action, { method: "POST", headers, body });\n}\n\ntry {\n const res = await signUp(PAGE_URL, "YOUR_EMAIL");\n console.log(res.status, (await res.text()).slice(0, 80));\n} catch (err) {\n if (err instanceof ValidationException) console.error(`not sent: ${err.message}`);\n else if (err instanceof TimeoutException) console.error("gave up after recaptchaTimeout");\n else if (err instanceof CapSkipError) console.error(`solve failed: ${err.name}: ${err.message}`);\n else throw err;\n process.exitCode = 1;\n}<\/pre>\n<\/div>\nIf every run fails within seconds, check the page URL before anything else, because a key used outside its registered domains fails the same way each time. If the sitekey check throws, the page builds the widget from a bundled script, and the key is in the Network tab as described in Step 1. The raw endpoint behind this method is documented in the CaptchaFox section of the API reference<\/a>.<\/p>\n
Running many sign-ups side by side<\/h2>\n
Every CapSkip method in Node returns a Promise, and AsyncCapSkip is just another name for the same class, so running solves side by side is plain JavaScript. What you need is a cap. CapSkip runs 10 CaptchaFox solves at a time by default and makes the rest wait for a free thread, so a small pool that keeps ten in flight matches it. Put it in place of the try block at the end of the full example:<\/p>\n
\n\/\/ At most `limit` calls in flight; a failure becomes that item's Error.\nasync function mapLimited(items, limit, fn) {\n const results = new Array(items.length);\n let next = 0;\n async function worker() {\n while (next < items.length) {\n const i = next++;\n results[i] = await fn(items[i]).catch((err) => err);\n }\n }\n await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));\n return results;\n}\n\nconst emails = ["YOUR_EMAIL_1", "YOUR_EMAIL_2", "YOUR_EMAIL_3"];\nconst results = await mapLimited(emails, 10, (email) => signUp(PAGE_URL, email));\nfor (const r of results) console.log(r instanceof Error ? r.message : r.status);<\/pre>\n<\/div>\nsignUp is the function from the full example. It builds its own cookie jar on every call, which is what makes it safe in parallel: one jar shared by ten runs would mix up their sessions and CSRF tokens. It also keeps each token next to its own user agent until the post goes out. Raise Max. Threads in CapSkip’s CaptchaFox settings for a bigger pool. CaptchaFox also scores the network as well as the browser, so many solves from one address raise the challenge rate over a long run. Set up proxies with the Configure Proxies button in that same row, or pass a proxy object on each call.<\/p>\n
Running the solver on another machine<\/h2>\n
127.0.0.1 is right while the script and CapSkip share a Windows PC. When the Node code moves to a VPS, a container, a CI runner or a serverless function, loopback points at the wrong machine and the first solve throws NetworkException with ECONNREFUSED. Switch CapSkip to Server mode and it listens on your network address or public IP, so any of those can call it over the same API. Use a static public IP when the route crosses the internet, turn on API key validation, and limit the port to the addresses you expect with a Windows Firewall rule. The solver is still your own Windows machine, and solves are still unmetered.<\/p>\n
The client does not read environment variables by itself. Read CAPSKIP_HOST, CAPSKIP_PORT and CAPSKIP_API_KEY in your code and pass them to the constructor, as the full example does, so the same script runs at your desk and on a server.<\/p>\n
Common errors and what they mean<\/h2>\n
\n\n
\n \nWhat you see<\/th>\n Cause<\/th>\n Fix<\/th>\n<\/tr>\n<\/thead>\n \n The site rejects a token CapSkip returned as solved<\/td>\n The post went out with user-agent: node, fetch’s default, not as the browser that minted the token<\/td>\n Send result.userAgent as the User-Agent header on that request<\/td>\n<\/tr>\n \n Rejected although the user agent matches<\/td>\n The page loads the MAM package and the solve used the default widget, or the reverse<\/td>\n Read the script tag and set apiServer to match it<\/td>\n<\/tr>\n \n A 403 on the post, with a valid token and user agent<\/td>\n The session cookie was not sent, so the CSRF field no longer matches, or the post had no Referer<\/td>\n Carry the cookies from the page fetch and send the page URL as Referer<\/td>\n<\/tr>\n \n result.userAgent is undefined<\/td>\n The solve reported no user agent, so fetch sends its own<\/td>\n Keep the if check; if the site refuses node, send a current desktop browser user agent yourself<\/td>\n<\/tr>\n \n An ApiException within seconds, every time, for one key<\/td>\n The page URL is outside the domains the key is registered for, or the key itself is wrong<\/td>\n Send the page the widget runs on, not a redirect or a search result, and recheck the key<\/td>\n<\/tr>\n \n An occasional ApiException containing ERROR_CAPTCHA_UNSOLVABLE<\/td>\n CaptchaFox drew an image-select or audio challenge, or a slide CapSkip could not read<\/td>\n Retry in code, or raise Retries in CapSkip’s CaptchaFox settings<\/td>\n<\/tr>\n \n A token that worked once fails the second time<\/td>\n Each token verifies once and expires quickly<\/td>\n Solve a fresh token for every post, and post straight away<\/td>\n<\/tr>\n \n ValidationException before anything is sent<\/td>\n An empty sitekey or URL, an option the method does not take, such as a per-call pollingInterval, or a proxy type CapSkip does not accept<\/td>\n Check the sitekey was found, and fix or drop the option the message names<\/td>\n<\/tr>\n \n TimeoutException after five minutes<\/td>\n The wait for a free CaptchaFox thread plus the solve itself ran past the SDK’s 300 seconds, or CapSkip stopped mid-solve<\/td>\n Cap the pool at Max. Threads, or pass a longer timeout for that call<\/td>\n<\/tr>\n \n NetworkException with ECONNREFUSED or ETIMEDOUT on the first call<\/td>\n CapSkip is not running, the host or port is wrong, or a firewall drops the connection<\/td>\n Start CapSkip, then check whether it should be in Local mode or Server mode<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n FAQ<\/h2>\n
\n\n
Do axios or got avoid the user agent problem?<\/h3>\n<\/summary>\n
No. They only change the name. axios sends axios followed by its version number, and got sends got followed by the address of its GitHub repository. Neither keeps cookies or sends a Referer unless you set them up to, so the same three headers apply. Whatever the client, set the user agent on the request that carries the token, from result.userAgent.<\/p>\n<\/details>\n
\n\n
Can I use the token in Puppeteer or Playwright instead?<\/h3>\n<\/summary>\n
Yes, as long as the page that submits it runs under the user agent CapSkip returned. Solve first, then open a Playwright context with browser.newContext({ userAgent: ua }), or call page.setUserAgent(ua) in Puppeteer before the page loads. Load the form, write the token into the cf-captcha-response field and submit. If your automation does not need a browser for anything else, the fetch route above is lighter.<\/p>\n<\/details>\n
\n\n
How is this different from the Python version?<\/h3>\n<\/summary>\n
The call and the rules are the same, and so is the main trap: the HTTP client sends its own name as the user agent. In Python that name is python-requests or python-httpx, and a requests.Session keeps the cookies for you. In Node it is node, and you carry the cookies yourself. The Python side is covered in the guide to solving CaptchaFox in Python<\/a>.<\/p>\n<\/details>\n
The short version<\/h2>\n
To solve CaptchaFox in Node.js, fetch the page and keep its cookies, read the sitekey from the captchafox container, the render call or the MAM script, and note which build the page loads. Call solver.captchafox() with the sitekey and the real page URL, adding apiServer only for MAM pages. Post result.token in cf-captcha-response with the page’s cookies, the page as Referer and result.userAgent as the User-Agent header, once and straight away. Retry unsolvable draws, keep no more solves in flight than Max. Threads, 10 by default, and switch to Server mode when the script leaves the solver’s machine.<\/p>\n