Skip to content
Back to search

nonecap-js

Official TypeScript client for NoneCap, the hCaptcha solver API.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/nonecap/nonecap-js with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/nonecap/nonecap-js'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/nonecap--nonecap-js/badge.svg)](/listings/nonecap--nonecap-js)

HTML

<a href="/listings/nonecap--nonecap-js"><img src="/api/listings/nonecap--nonecap-js/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npm install nonecap

Works on Node 18+, Bun, Deno, and edge runtimes. No dependencies.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 332 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <h1 align="center">nonecap</h1>
  2. <p align="center">
  3. <a href="https://github.com/nonecap/nonecap-js/actions/workflows/ci.yml"><img src="https://github.com/nonecap/nonecap-js/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  4. <a href="https://www.npmjs.com/package/nonecap"><img src="https://img.shields.io/npm/v/nonecap.svg" alt="npm"></a>
  5. <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
  6. </p>
  7. <p align="center">Official TypeScript client for the NoneCap <a href="https://nonecap.com/">hCaptcha solver</a> API.</p>
  8. Submit a captcha, get back a token. The client handles the polling, the timeouts, and the error cases so you do not have to write the fetch loop yourself.
  9. ## Install
  10. ```sh
  11. npm install nonecap
  12. ```
  13. Works on Node 18+, Bun, Deno, and edge runtimes. No dependencies.
  14. ## Quick start
  15. Grab an API key from [dashboard.nonecap.com](https://dashboard.nonecap.com/signup?utm_source=npm&utm_medium=sdk-readme), then:
  16. ```ts
  17. import { NoneCap } from "nonecap";
  18. const nc = new NoneCap({ apiKey: process.env.NONECAP_KEY! });
  19. const solve = await nc.solve({
  20. type: "hcaptcha",
  21. sitekey: "10000000-ffff-ffff-ffff-000000000001",
  22. url: "https://example.com/login",
  23. });
  24. console.log(solve.token); // the hCaptcha token, ready to submit
  25. console.log(solve.resp_key); // hcaptcha.getRespKey() equivalent, for sites that verify the pair
  26. console.log(solve.user_agent); // submit the token with this User-Agent: some sites check the browser version
  27. console.log(solve.warnings); // e.g. proxy_session_refused: tokens you reported through this proxy session or its exit IP were refused; a different exit IP is more likely to pass (or, when your proxy changed its exit IP during the solve, use a sticky session per solve)
  28. ```
  29. `solve()` submits the captcha and waits until it is done, using the API's long-poll so you are not hammering it with requests. It returns the solved solve, or throws if the solve fails or your timeout runs out.
  30. ## MCP server (Claude Code, Cursor, and other MCP clients)
  31. The package also ships `nonecap-mcp`, a stdio [MCP](https://modelcontextprotocol.io) server, so an AI agent can solve hCaptcha through your NoneCap account.
  32. Claude Code:
  33. ```sh
  34. claude mcp add nonecap --env NONECAP_API_KEY=<your key> -- npx -y -p nonecap@latest nonecap-mcp
  35. ```
  36. Cursor (`~/.cursor/mcp.json`), Claude Desktop (`claude_desktop_config.json`), and most other clients take the same JSON:
  37. ```json
  38. {
  39. "mcpServers": {
  40. "nonecap": {
  41. "command": "npx",
  42. "args": ["-y", "-p", "nonecap@latest", "nonecap-mcp"],
  43. "env": { "NONECAP_API_KEY": "<your key>" }
  44. }
  45. }
  46. }
  47. ```
  48. Tools:
  49. | Tool | What it does |
  50. | --- | --- |
  51. | `solve_hcaptcha` | Solve an hCaptcha (`sitekey`, `url`; optional `type`, `rqdata`, `user_agent`, `proxy`, `wait_seconds`) and return the solve with its `token`. If the solve is still running after `wait_seconds` (default 45, at most 50, inside the 60 s that clients built on the official MCP SDK allow by default), it returns the solve id and status so the agent polls `get_solve` instead of solving again. |
  52. | `get_solve` | Get a solve by id, optionally waiting up to 50 seconds for it to finish. |
  53. | `cancel_solve` | Cancel a pending or running solve. |
  54. | `list_solves` | List your recent solves. |
  55. | `get_account` | Your credit balance and your plan's solves left today. |
  56. | `report_solve_outcome` | Tell NoneCap whether the site accepted a token. |
  57. A failed call comes back as a tool error whose JSON carries the API's error code (`insufficient_credits`, `sitekey_rate_limited`, a failed solve's `proxy_error`, …), plus `retry_after` when the API sent one. Set `NONECAP_BASE_URL` to point the server at a different API host.
  58. There is also an [Agent Skill](skills/nonecap-hcaptcha/SKILL.md) that tells Claude Code, Codex and other SKILL.md clients when to reach for NoneCap and how to submit the token: copy `skills/nonecap-hcaptcha` into `~/.claude/skills/` (or your agent's skills folder).
  59. ## Handling failures
  60. Every error this library throws extends `NoneCapError`, so you can catch the whole family or pick out the one you care about.
  61. ```ts
  62. import {
  63. NoneCap,
  64. SolveFailedError,
  65. InsufficientCreditsError,
  66. RateLimitError,
  67. } from "nonecap";
  68. try {
  69. const { token } = await nc.solve({ type: "hcaptcha", sitekey, url });
  70. // use token
  71. } catch (err) {
  72. if (err instanceof SolveFailedError) {
  73. // The message says what happened, what to do, and that nothing was charged.
  74. console.error(err.solve.error?.message);
  75. if (err.retryable) scheduleRetry();
  76. } else if (err instanceof InsufficientCreditsError) {
  77. console.error("Out of credits. Top up at dashboard.nonecap.com");
  78. } else if (err instanceof RateLimitError) {
  79. await new Promise((r) => setTimeout(r, (err.retryAfter ?? 1) * 1000));
  80. } else {
  81. throw err;
  82. }
  83. }
  84. ```
  85. The error subclasses are `AuthenticationError` (401), `PermissionError` (403), `InsufficientCreditsError` (402, with `KeyCreditLimitError` when one API key hit its own cap), `ValidationError` (422/400, with a `param` naming the bad field; `PayloadTooLargeError` for 413 and `UnsupportedMediaTypeError` for 415), `NotFoundError` (404), `ConflictError` (409), `RateLimitError` (429, with `ConcurrencyLimitError`, `SitekeyRateLimitedError`, `ProxyUnavailableError` (your own proxy is refusing connections) and `RateCappedError` (your account reached its submit rate cap on this sitekey, or your own-proxy sessions for it are at their limit) telling them apart; `retryAfter` is the seconds the API asked you to wait), `RecognitionFailedError` (422 from `recognize()` when no answer came back, nothing charged), `APIError` (5xx, with `ServiceUnavailableError` for a maintenance pause and its subclass `SitekeyUnavailableError` when solving for one sitekey is currently in maintenance, `retryAfter` set), and `ConnectionError` (the request never landed). Every error from a response carries `requestId`, the id to quote to support.
  86. `SolveFailedError` carries the full `solve`. `solve.error.code` is a `SolveErrorCode`, `solve.error.reason` a typed sub-reason or `null` (`proxy_rejected`, `sitekey_rate_limited`, …), and `solve.error.retryable` says whether resubmitting the same request unchanged can succeed; `err.retryable`, `err.reason` and `err.solveCode` are shortcuts to those fields. Failed solves are never charged.
  87. ## Cancelling a solve
  88. `solve()` is the simple path when you just want a token. When you need to cancel while the solve is in flight — clean shutdown, freeing a worker slot, or stopping early — start it instead. `solves.start()` returns as soon as the submission is accepted, handing you a `SolveHandle` whose `id` is available right away.
  89. Wait for the result when you want the token:
  90. ```ts
  91. const handle = await nc.solves.start({ type: "hcaptcha", sitekey, url });
  92. console.log(handle.id); // available immediately
  93. const solve = await handle.result({ timeout: 120_000 });
  94. console.log(solve.token);
  95. ```
  96. Or hold onto the handle and cancel it from somewhere else — a shutdown hook, a request that was abandoned, a "stop" button:
  97. ```ts
  98. const handle = await nc.solves.start({ type: "hcaptcha", sitekey, url });
  99. process.on("SIGTERM", () => {
  100. handle.cancel().catch(() => {}); // free the worker slot on shutdown
  101. });
  102. // elsewhere, whoever needs the token still awaits it:
  103. const solve = await handle.result();
  104. ```
  105. `handle.result()` long-polls until the solve finishes, throwing `SolveFailedError` or `TimeoutError` exactly like `solve()`. The **terminal** outcome is memoized: once the solve actually finishes, every later `result()` call returns that same result. A `TimeoutError` is not memoized — it just means that wait gave up, so you can call `result()` again (for example with a larger `timeout`) to resume polling. Concurrent `result()` calls share a single in-flight poll.
  106. `handle.cancel()` cancels a pending or in-flight solve. If the solve already finished, the API would answer 409; the handle swallows that and returns the solve's current state instead, since cancelling a finished solve is not something you need to handle. Cancelling settles the handle, so a concurrent or later `result()` stops polling and reflects the cancelled (terminal) state.
  107. Cancelled and abandoned solves are **never charged** — nothing is billed unless a solve actually succeeds, and unfinished solves simply expire uncharged at the server deadline. So cancel is for cleanup and early-stop, not cost protection.
  108. ### Cleaning up after a `solve()` timeout
  109. `solve()` blocks until the solve settles, so it hands you no handle to cancel a solve while it's still running — for that, use `solves.start()` above. The one thing the `solve()` path offers is cleanup *after* a timeout: when `solve()` throws `TimeoutError`, the error usually carries the in-flight `solveId` (and last-known `solve`), so you can cancel the solve the wait gave up on. Guard on `solveId` being present — if the very first submission times out at the transport level, no id has been assigned yet, so `solveId` is `undefined`.
  110. ```ts
  111. import { TimeoutError } from "nonecap";
  112. try {
  113. await nc.solve({ type: "hcaptcha", sitekey, url });
  114. } catch (err) {
  115. if (err instanceof TimeoutError && err.solveId) {
  116. await nc.solves.cancel(err.solveId);
  117. } else {
  118. throw err;
  119. }
  120. }
  121. ```
  122. ## Enterprise captchas
  123. For `hcaptcha_enterprise`, `rqdata` is optional: many enterprise sites never issue one. When the page does pass an `rqdata` blob to its widget, send it, fresh for each challenge.
  124. ```ts
  125. const { token } = await nc.solve({
  126. type: "hcaptcha_enterprise",
  127. sitekey,
  128. url,
  129. rqdata: "...", // only when the site provides one
  130. });
  131. ```
  132. ## Proxies
  133. Pass a proxy as a structured object or a URL string. Solves run through it, and the bytes are metered back on the solve. For HTTP/3 through your own proxy, see [HTTP/3 on your own proxy](https://nonecap.com/api-reference#http3-own-proxy).
  134. ```ts
  135. await nc.solve({
  136. type: "hcaptcha",
  137. sitekey,
  138. url,
  139. proxy: { scheme: "http", host: "1.2.3.4", port: 8080, username: "u", password: "p" },
  140. // or: proxy: "http://u:p@1.2.3.4:8080"
  141. // scheme can be http, https, socks5, socks5h, or socks4 (default http)
  142. // e.g. proxy: "socks5://u:p@1.2.3.4:1080"
  143. });
  144. ```
  145. ## Reporting token acceptance
  146. A token that hCaptcha blessed can still be refused by the site you send it to. Tell us what happened and we tune minting against your real acceptance rate — it's free, and it's the fastest way to get a regression on your sitekey noticed.
  147. Keep the `solve_id` next to the token you submit downstream, then report the verdict:
  148. ```ts
  149. const solve = await nc.solve({ type: "hcaptcha", sitekey, url });
  150. const ok = await submitToTheSiteYouAreAutomating(solve.token);
  151. await nc.feedback.report({
  152. solve_id: solve.id,
  153. outcome: ok ? "accepted" : "rejected",
  154. reason: ok ? undefined : "session invalidated", // optional, the code your target returned
  155. context: ok ? undefined : "3rd retry, rotating residential pool", // optional, anything you think would help us diagnose it
  156. });
  157. ```
  158. At volume, buffer the verdicts and flush them in one call. Reports over 500 are split across requests for you:
  159. ```ts
  160. const batch = await nc.feedback.reportMany([
  161. { solve_id: "solve_01J...", outcome: "accepted" },
  162. { solve_id: "solve_01J...", outcome: "rejected", reason: "...", context: "..." },
  163. ]);
  164. // Items resolve independently, so the call succeeds even when some are
  165. // rejected — check `failed` rather than relying on a throw.
  166. if (batch.failed > 0) {
  167. console.warn(batch.results.filter((r) => r.status === "error"));
  168. }
  169. ```
  170. `outcome` is one of `accepted`, `rejected`, `unknown` (submitted, verdict unclear), `unused` (never submitted), or `error` (downstream broke for a non-token reason). Only `accepted` and `rejected` count toward the acceptance rate.
  171. `reason` and `context` are both optional free text. `reason` is the code or message your target gave you; `context` is anything else about the attempt you think would help us diagnose it, with no schema at all. Neither is parsed — they are what a human reads when you raise a ticket, and they carry the half of a rejection we cannot see from our side.
  172. Reporting the same solve again corrects the earlier verdict, so retries and late fixes are safe. You can report any of your own solved solves within ~30 days of the solve; corrections to something you already reported are never cut off by that window.
  173. ## Recognizing images
  174. If you run your own browser and only need the answer to a challenge, send the instruction and images to `recognize()`. The answer comes back in the same response: no token, no polling.
  175. ```ts
  176. const { id, data } = await nc.recognize({
  177. type: "hcaptcha",
  178. task: "Please click each image containing a bus",
  179. image_data: tiles, // base64 or data: URIs, 1-27 tiles; or image_urls with hCaptcha image URLs
  180. });
  181. // data: boolean[], one per tile, in the order you sent them
  182. ```
  183. For a click-the-point challenge send exactly one image with `type: "hcaptcha_area_select"`. `data` is the first point as `{ x, y, w: 0, h: 0 }` and `points` lists every point to click, all in percent of the image.
  184. You can also send the challenge as hCaptcha served it, in NopeCHA's v1 recognition shape:
  185. ```ts
  186. const result = await nc.recognize({
  187. data: {
  188. request_type: "image_drag_drop", // or image_label_binary, image_label_area_select
  189. requester_question: { en: "Drag the piece into place" },
  190. tasklist: [{ task_key, datapoint_uri, entities }],
  191. },
  192. });
  193. ```
  194. `image_label_binary` answers pages of 9 booleans (`boolean[][]`), `image_label_area_select` one box per task (`null` when there is no point) plus `points` per task, and `image_drag_drop` the drop box for each entity per task. The return type follows the request, so TypeScript knows which one you got.
  195. When no answer comes back the call throws `RecognitionFailedError` and nothing is charged. An answered call's charge is final. You can tell us whether the answer worked on the challenge, which helps us track accuracy; it is optional, free, and does not refund the call:
  196. ```ts
  197. await nc.reportRecognitionOutcome(id, solved ? "solved" : "failed");
  198. ```
  199. The first report for an id sticks; a repeat returns it unchanged. Calls are capped per API key by your account's concurrency limit, so a burst over it gets `ConcurrencyLimitError` or `RateLimitError` with `retryAfter` set.
  200. ## Lower-level API
  201. `solve()` is the convenient path. When you want control over submission and polling, the raw resource methods map one to one to the REST API.
  202. ```ts
  203. // Submit without waiting: returns immediately with a pending solve
  204. const pending = await nc.solves.create({ type: "hcaptcha", sitekey, url });
  205. // Submit and hold the connection up to 30s for it to finish
  206. const maybeDone = await nc.solves.create({ type: "hcaptcha", sitekey, url }, { wait: 30 });
  207. // Poll one solve, long-polling up to 30s
  208. const solve = await nc.solves.retrieve(pending.id, { wait: 30 });
  209. // Cancel a pending or in-flight solve
  210. await nc.solves.cancel(pending.id);
  211. // List a page of solves
  212. const page = await nc.solves.list({ limit: 50, status: "solved" });
  213. // Or iterate every solve, newest first
  214. for await (const s of nc.solves.listAll()) {
  215. console.log(s.id, s.status);
  216. }
  217. // Your account and credit balance
  218. const me = await nc.me();
  219. console.log(me.credits_balance);
  220. // With a plan: what is left of today's solves, and when they reset (00:00 UTC).
  221. console.log(me.plan?.remaining_today, me.plan?.resets_at);
  222. ```
  223. ## Cancelling and timeouts
  224. Pass an `AbortSignal` to cancel any call, and a `timeout` to bound how long `solve()` waits.
  225. ```ts
  226. const ac = new AbortController();
  227. setTimeout(() => ac.abort(), 60_000);
  228. await nc.solve(
  229. { type: "hcaptcha", sitekey, url },
  230. { timeout: 120_000, signal: ac.signal },
  231. );
  232. ```
  233. ## Configuration
  234. ```ts
  235. new NoneCap({
  236. apiKey: "nc_live_...", // required
  237. baseURL: "https://api.nonecap.com", // override if you need to
  238. timeout: 100_000, // per HTTP request, ms
  239. fetch: customFetch, // inject your own fetch
  240. });
  241. ```
  242. ## License
  243. MIT, see [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.