capjs.js.org/guide/

Public Link
Created by:
****ad@vlad.studio
Starting URLs:
https://capjs.js.org/guide/
CSS Selector:
main
Crawl Prefixes:
https://capjs.js.org/guide/
Exclude Patterns:
https://capjs.js.org/guide/workings.html
https://capjs.js.org/guide/benchmark.html
https://capjs.js.org/guide/effectiveness.html
https://capjs.js.org/guide/demo.html
https://capjs.js.org/guide/alternatives.html
## Page: https://capjs.js.org/guide/

# Quickstart 

Cap is a modern, lightweight, open-source CAPTCHA alternative using SHA-256 proof-of-work.

Unlike traditional CAPTCHAs, Cap:

*   Is fast and unobtrusive
*   Uses no tracking or cookies
*   Uses proof-of-work instead of intrusive puzzles
*   Is fully accessible and self-hostable

Here, try it yourself:

I'm a human

Secured by Cap

## Components 

Cap consists mainly of the **widget** (can be used invisibly) and **server** (you can use the Standalone server instead). Alternatively, M2M is also supported and there's also a checkpoint middleware similar to Cloudflare.

This guide details how to use the usual setup. You can find guides on using the Standalone server, M2M solver, and checkpoint middleware in their respective sections.

## Client-side 

Start by adding importing the Cap widget library from a CDN:

jsdelivrunpkg

html

    <script src="https://cdn.jsdelivr.net/npm/@cap.js/widget"></script>

html

    <script src="https://unpkg.com/@cap.js/widget"></script>

WARNING

We're using the latest version of the library here for simplicity, but you should optimally pin a specific version to avoid breaking changes in the future.

Next, add the `<cap-widget>` component to your HTML.

html

    <cap-widget id="cap" data-cap-api-endpoint="<your cap endpoint>"></cap-widget>

INFO

You'll need to start a server with the Cap API running at the same URL as specified in the `data-cap-api-endpoint` attribute. In the server-side example we provided, it's set to `/api`, but you can change this by replacing every `app.post('/api/...', ...)` to `app.post('/<endpoint>/...', ...)`.

Then, in your JavaScript, listen for the `solve` event to capture the token when generated:

js

    const widget = document.querySelector("#cap");  widget.addEventListener("solve", function (e) {  const token = e.detail.token;   // Handle the token as needed });

Alternatively, you can use `onsolve=""` directly within the widget or wrap the widget in a `<form></form>` (where Cap will automatically submit the token alongside other form data. for this, it'll create a hidden field with name set to its `data-cap-hidden-field-name` attribute or `cap-token`).

## Server-side 

Cap is fully self-hosted, so you'll need to start a server exposing an API for Cap's methods running at the same URL as specified in the `data-cap-api-endpoint` attribute. This is easy since we've already pre-made a library to help you generate and validate challenges for you.

At least Node 14 is required. Most modern Bun or Deno versions should work too. If you don't use JavaScript in your server, consider using the Standalone server.

Start by installing it:

bunnpmpnpm

bash

    bun add @cap.js/server

bash

    npm i @cap.js/server

bash

    pnpm i @cap.js/server

TIP

Don't use JavaScript on your backend? Try the Standalone mode.

Now, you'll need to change your server code to add the routes that Cap needs to work. Here's an example:

elysiafastifybun.servehonoexpress

js

    import { Elysia } from "elysia"; import Cap from "@cap.js/server";  const cap = new Cap({  tokens_store_path: ".data/tokensList.json", });  new Elysia()  .post("/api/challenge", () => {  return cap.createChallenge();  })   .post("/api/redeem", async ({ body, set }) => {  const { token, solutions } = body;   if (!token || !solutions) {  set.status = 400;  return { success: false };  }   return await cap.redeemChallenge({ token, solutions });  })  .listen(3000);  console.log(`🦊 Elysia is running at http://localhost:3000`);

js

    import Fastify from "fastify"; import Cap from "@cap.js/server";  const fastify = Fastify(); const cap = new Cap({  tokens_store_path: ".data/tokensList.json", });  fastify.post("/api/challenge", (req, res) => {  res.send(cap.createChallenge()); });  fastify.post("/api/redeem", async (req, res) => {  const { token, solutions } = req.body;  if (!token || !solutions) {  return res.code(400).send({ success: false });  }   res.send(await cap.redeemChallenge({ token, solutions })); });  fastify.listen({ port: 3000, host: "0.0.0.0" }).then(() => {  console.log("Server is running on http://localhost:3000"); });

js

    import Cap from "@cap.js/server";  const cap = new Cap({  tokens_store_path: ".data/tokensList.json", });  Bun.serve({  port: 3000,  routes: {  "/api/challenge": {  POST: () => {  return Response.json(cap.createChallenge());  },  },  "/api/redeem": {  POST: async (req) => {  const body = await req.json();  const { token, solutions } = body;   if (!token || !solutions) {  return Response.json({ success: false }, { status: 400 });  }   return Response.json(await cap.redeemChallenge({ token, solutions }));  },  },  }, });  console.log(`Server running at http://localhost:3000`);

js

    import { Hono } from "hono"; import Cap from "@cap.js/server";  const app = new Hono(); const cap = new Cap({  tokens_store_path: ".data/tokensList.json", });  app.post("/api/challenge", (c) => {  return c.json(cap.createChallenge()); });  app.post("/api/redeem", async (c) => {  const { token, solutions } = await c.req.json();  if (!token || !solutions) {  return c.json({ success: false }, 400);  }   return c.json(await cap.redeemChallenge({ token, solutions })); });  export default {  port: 3000,  fetch: app.fetch, };

js

    import express from "express"; import Cap from "@cap.js/server";  const app = express(); app.use(express.json());  const cap = new Cap({  tokens_store_path: ".data/tokensList.json", });  app.post("/api/challenge", (req, res) => {  res.json(cap.createChallenge()); });  app.post("/api/redeem", async (req, res) => {  const { token, solutions } = req.body;  if (!token || !solutions) {  return res.status(400).json({ success: false });  }  res.json(await cap.redeemChallenge({ token, solutions })); });  app.listen(3000, () => {  console.log("Listening on port 3000"); });

### Token validation 

Once the token is generated and captured, you can use it later to validate the user's identity. You can do this by calling `await cap.validateToken` in your server-side code:

js

    await cap.validateToken("..."); // returns { success: Boolean }

Note that the token will immediately be deleted after this. To prevent this, use `await cap.validateToken("...", { keepToken: true })`.

---

## Page: https://capjs.js.org/guide/index.html

# Quickstart 

Cap is a modern, lightweight, open-source CAPTCHA alternative using SHA-256 proof-of-work.

Unlike traditional CAPTCHAs, Cap:

*   Is fast and unobtrusive
*   Uses no tracking or cookies
*   Uses proof-of-work instead of intrusive puzzles
*   Is fully accessible and self-hostable

Here, try it yourself:

I'm a human

Secured by Cap

## Components 

Cap consists mainly of the **widget** (can be used invisibly) and **server** (you can use the Standalone server instead). Alternatively, M2M is also supported and there's also a checkpoint middleware similar to Cloudflare.

This guide details how to use the usual setup. You can find guides on using the Standalone server, M2M solver, and checkpoint middleware in their respective sections.

## Client-side 

Start by adding importing the Cap widget library from a CDN:

jsdelivrunpkg

html

    <script src="https://cdn.jsdelivr.net/npm/@cap.js/widget"></script>

html

    <script src="https://unpkg.com/@cap.js/widget"></script>

WARNING

We're using the latest version of the library here for simplicity, but you should optimally pin a specific version to avoid breaking changes in the future.

Next, add the `<cap-widget>` component to your HTML.

html

    <cap-widget id="cap" data-cap-api-endpoint="<your cap endpoint>"></cap-widget>

INFO

You'll need to start a server with the Cap API running at the same URL as specified in the `data-cap-api-endpoint` attribute. In the server-side example we provided, it's set to `/api`, but you can change this by replacing every `app.post('/api/...', ...)` to `app.post('/<endpoint>/...', ...)`.

Then, in your JavaScript, listen for the `solve` event to capture the token when generated:

js

    const widget = document.querySelector("#cap");  widget.addEventListener("solve", function (e) {  const token = e.detail.token;   // Handle the token as needed });

Alternatively, you can use `onsolve=""` directly within the widget or wrap the widget in a `<form></form>` (where Cap will automatically submit the token alongside other form data. for this, it'll create a hidden field with name set to its `data-cap-hidden-field-name` attribute or `cap-token`).

## Server-side 

Cap is fully self-hosted, so you'll need to start a server exposing an API for Cap's methods running at the same URL as specified in the `data-cap-api-endpoint` attribute. This is easy since we've already pre-made a library to help you generate and validate challenges for you.

At least Node 14 is required. Most modern Bun or Deno versions should work too. If you don't use JavaScript in your server, consider using the Standalone server.

Start by installing it:

bunnpmpnpm

bash

    bun add @cap.js/server

bash

    npm i @cap.js/server

bash

    pnpm i @cap.js/server

TIP

Don't use JavaScript on your backend? Try the Standalone mode.

Now, you'll need to change your server code to add the routes that Cap needs to work. Here's an example:

elysiafastifybun.servehonoexpress

js

    import { Elysia } from "elysia"; import Cap from "@cap.js/server";  const cap = new Cap({  tokens_store_path: ".data/tokensList.json", });  new Elysia()  .post("/api/challenge", () => {  return cap.createChallenge();  })   .post("/api/redeem", async ({ body, set }) => {  const { token, solutions } = body;   if (!token || !solutions) {  set.status = 400;  return { success: false };  }   return await cap.redeemChallenge({ token, solutions });  })  .listen(3000);  console.log(`🦊 Elysia is running at http://localhost:3000`);

js

    import Fastify from "fastify"; import Cap from "@cap.js/server";  const fastify = Fastify(); const cap = new Cap({  tokens_store_path: ".data/tokensList.json", });  fastify.post("/api/challenge", (req, res) => {  res.send(cap.createChallenge()); });  fastify.post("/api/redeem", async (req, res) => {  const { token, solutions } = req.body;  if (!token || !solutions) {  return res.code(400).send({ success: false });  }   res.send(await cap.redeemChallenge({ token, solutions })); });  fastify.listen({ port: 3000, host: "0.0.0.0" }).then(() => {  console.log("Server is running on http://localhost:3000"); });

js

    import Cap from "@cap.js/server";  const cap = new Cap({  tokens_store_path: ".data/tokensList.json", });  Bun.serve({  port: 3000,  routes: {  "/api/challenge": {  POST: () => {  return Response.json(cap.createChallenge());  },  },  "/api/redeem": {  POST: async (req) => {  const body = await req.json();  const { token, solutions } = body;   if (!token || !solutions) {  return Response.json({ success: false }, { status: 400 });  }   return Response.json(await cap.redeemChallenge({ token, solutions }));  },  },  }, });  console.log(`Server running at http://localhost:3000`);

js

    import { Hono } from "hono"; import Cap from "@cap.js/server";  const app = new Hono(); const cap = new Cap({  tokens_store_path: ".data/tokensList.json", });  app.post("/api/challenge", (c) => {  return c.json(cap.createChallenge()); });  app.post("/api/redeem", async (c) => {  const { token, solutions } = await c.req.json();  if (!token || !solutions) {  return c.json({ success: false }, 400);  }   return c.json(await cap.redeemChallenge({ token, solutions })); });  export default {  port: 3000,  fetch: app.fetch, };

js

    import express from "express"; import Cap from "@cap.js/server";  const app = express(); app.use(express.json());  const cap = new Cap({  tokens_store_path: ".data/tokensList.json", });  app.post("/api/challenge", (req, res) => {  res.json(cap.createChallenge()); });  app.post("/api/redeem", async (req, res) => {  const { token, solutions } = req.body;  if (!token || !solutions) {  return res.status(400).json({ success: false });  }  res.json(await cap.redeemChallenge({ token, solutions })); });  app.listen(3000, () => {  console.log("Listening on port 3000"); });

### Token validation 

Once the token is generated and captured, you can use it later to validate the user's identity. You can do this by calling `await cap.validateToken` in your server-side code:

js

    await cap.validateToken("..."); // returns { success: Boolean }

Note that the token will immediately be deleted after this. To prevent this, use `await cap.validateToken("...", { keepToken: true })`.

---

## Page: https://capjs.js.org/guide/philosophy.html

# Philosophy 

Most CAPTCHA systems today are built around surveillance — tracking users, fingerprinting browsers, and collecting data in exchange for access. Cap rejects that model.

Cap is designed around a few core ideas:

*   **Privacy by default** — no trackers, no third-party requests, no hidden profiling.
*   **Simplicity over complexity** — no image labeling, no click-the-fire-hydrant puzzles.
*   **Speed matters** — fast to render, fast to solve, fast to validate.
*   **User-first** — designed to be unintrusive and accessible, with invisible and floating modes.
*   **Self-hostable, not centralized** — you control the infra, tokens, and behavior.

By using proof-of-work instead of user behavior analysis, Cap shifts the burden from identity to computation. That means anyone can prove they're human — no cookies, no accounts, no friction.

Cap is what a CAPTCHA should've been all along: **simple, honest, and yours.**

---

## Page: https://capjs.js.org/guide/standalone.html

# Standalone server 

## Installation 

Cap Standalone is a self-hosted version of Cap's backend that allows you to spin up a server to validate and create challenges so you can use it with languages other than JS.

To install Cap Standalone, you need to have Docker installed on your server. Once you have it installed, you can run the following command to pull the image:

bash

    docker pull tiago2/cap:latest

Both \`x86\_64\` (amd64) and \`arm64\` architectures are supported. Docker Engine 20.10 or higher is recommended

Then, to run the server, use the following command:

bash

    docker run -d \  -p 3000:3000 \  -v cap-data:/usr/src/app/.data \  -e ADMIN_KEY=your_secret_key \  --name cap-standalone \  tiago2/cap:latest

This will start the server on port 3000 and create a `cap-standalone` folder in your current directory to store the data. Change the port if needed.

Make sure to replace `your_secret_key` with a strong secret key, as anyone with it will be able to log into the dashboard and create keys.

Then, you can access the dashboard at `http://localhost:3000`, log in, and create a key. The key ID and secret will be used to configure the widget and verify the token on your server. You'll also need to make the server publicly accessible from the internet, as the widget needs to be able to reach it.

### CORS 

You can change the default CORS settings for redeeming tokens and generating challenges by setting the `CORS_ORIGIN` environment variable when running the server. This defaults to `*`, which allows all origins. This will directly assign to Access-Control-Allow-Origin header.

## Usage 

### Client-side 

First, add the Cap widget to your website by following this guide.

Then, you need to configure the widget to use your self-hosted Cap Standalone server. To do this, set the widget's API endpoint option to:

    https://<instance_url>/<key_id>/api/

Make sure to replace:

*   `<instance_url>`: The actual URL where your Cap Standalone instance is running. This URL must be publicly accessible from the internet.
*   `<key_id>`: Your key ID from this dashboard.

Example:

html

    <cap-widget  data-cap-api-endpoint="https://cap.example.com/d9256640cb53/api/" ></cap-widget>

### Server-side 

After a user completes the CAPTCHA on your site, your backend needs to verify their token using this server's API.

You can do this by sending a `POST` request from your server to the following endpoint:

    https://<instance_url>/<key_id>/siteverify

Your request needs to include the following data:

*   `secret`: Your key secret from this dashboard
*   `response`: The CAPTCHA token generated by the widget on the client-side

Example using `curl`:

bash

    curl "https://<instance_url>/<key_id>/siteverify" \  -X POST \  -H "Content-Type: application/json" \  -d '{ "secret": "<key_secret>", "response": "<captcha_token>" }'

Remember to replace:

*   `<instance_url>`: This server's URL
*   `<key_id>`: Your key ID from this dashboard
*   `<key_secret>`: Your key secret from this dashboard
*   `<captcha_token>`: The token value received from the client

The response should look like this:

json

    {  "success": true }

If `success` is true, you can proceed with your app logic.

### Client-side library storage 

By default, Cap Standalone updates and stores multiple files for Cap's client-side `cap.js/widget` library. This helps Cap be truly self-hosted and not depend on any external resources.

These files are stored in the `.data` folder and exposed in the following paths:

*   /assets/widget.js
*   /assets/floating.js
*   /assets/cap\_wasm\_bg.wasm
*   /assets/cap\_wasm.js

You can use these in your app by setting the widget's script source to the appropriate path, like this:

html

    <script src="https://<server url>/assets/widget.js"></script>

For the floating mode, use:

html

    <script src="https://<server url>/assets/floating.js"></script>

And by setting `window.CAP_CUSTOM_WASM_URL` to the path of the `cap_wasm_bg.wasm` file, like this:

js

    window.CAP_CUSTOM_WASM_URL = "https://<server url>/assets/cap_wasm_bg.wasm";

---

## Page: https://capjs.js.org/guide/floating.html

# Floating mode 

Cap can automatically hide the CAPTCHA until a button is pressed. To use this, add the `data-cap-floating` attribute to your trigger with the query selector of the `cap-widget` element you want to use.

html

    <cap-widget  id="floating"  onsolve="console.log(`token: ${event.detail.token}`)"  data-cap-api-endpoint="<api endpoint>" ></cap-widget>  <button data-cap-floating="#floating" data-cap-floating-position="bottom">  Trigger floating mode </button>

You'll also need to import both the Cap library and the floating mode script from JSDelivr:

html

    <script src="https://cdn.jsdelivr.net/npm/@cap.js/widget"></script> <script src="https://cdn.jsdelivr.net/npm/@cap.js/widget/cap-floating.min.js"></script> 

Or from the standalone server:

html

    <script src="https://<server url>/assets/widget.js"></script> <script src="https://<server url>/assets/floating.js"></script> 

The following attributes are supported:

*   `data-cap-floating`: The CSS selector of the `cap-widget` element you want to use.
*   `data-cap-floating-position`: The position of the floating widget. Can be `top` or `bottom`.
*   `data-cap-floating-offset`: The offset of the floating widget from the trigger element.

---

## Page: https://capjs.js.org/guide/invisible.html

# Invisible mode 

You can use `new Cap({ ... })` in your client-side JavaScript to create a new Cap instance and use the `solve()` method to solve the challenge. This is helpful for situations where you don't want the Cap widget to be visible but still want security, e.g. on a social media app when posting something.

js

    const cap = new Cap({  apiEndpoint: "/api/" }); const solution = await cap.solve();  console.log(solution.token);

You can also set up event listeners:

js

    const cap = new Cap({  apiEndpoint: "/api/" });  cap.addEventListener("progress", (event) => {   console.log(`Solving... ${event.detail.progress}% done`);  }); 

Behind the scenes, Cap creates a hidden `cap-widget` element and uses it to solve the challenge.

## Supported methods and arguments 

The following methods are supported:

#### `new Cap({ ... })` 

Creates a new Cap instance. If a 2nd argument is provided, it will use that element instead of creating a new one in memory.

**Arguments**

json

    {  apiEndpoint: ..., // api endpoint, similar to the widget `data-cap-api-endpoint` attribute  workers: navigator.hardwareConcurrency || 8 // number of worker threads to use }

#### `cap.solve()` 

Requests and solves a challenge.

**Output:** `{ token }`

#### `cap.token` 

Returns the token from the latest solve

#### `cap.reset()` 

Resets `cap.token`

#### `cap.addEventListener(..., function () { ... })` 

Listens for an event for the cap widget. See supported events

---

## Page: https://capjs.js.org/guide/server.html

# @cap.js/server 

`@cap.js/server` is Cap's server-side library. It helps you create and validate challenges for your users. Start by installing it using bun (recommended), npm, or pnpm:

bunnpmpnpm

bash

    bun add @cap.js/server

bash

    npm i @cap.js/server

bash

    pnpm i @cap.js/server

## Example code 

ElysiaFastifyBun.servehonoExpress

js

    import { Elysia } from "elysia"; import Cap from "@cap.js/server";  const cap = new Cap({  tokens_store_path: ".data/tokensList.json", });  new Elysia()  .post("/api/challenge", () => {  return cap.createChallenge();  })   .post("/api/redeem", async ({ body, set }) => {  const { token, solutions } = body;   if (!token || !solutions) {  set.status = 400;  return { success: false };  }   return await cap.redeemChallenge({ token, solutions });  })  .listen(3000);  console.log(`🦊 Elysia is running at http://localhost:3000`);

js

    import Fastify from "fastify"; import Cap from "@cap.js/server";  const fastify = Fastify(); const cap = new Cap({  tokens_store_path: ".data/tokensList.json", });  fastify.post("/api/challenge", (req, res) => {  res.send(cap.createChallenge()); });  fastify.post("/api/redeem", async (req, res) => {  const { token, solutions } = req.body;  if (!token || !solutions) {  return res.code(400).send({ success: false });  }   res.send(await cap.redeemChallenge({ token, solutions })); });  fastify.listen({ port: 3000, host: "0.0.0.0" }).then(() => {  console.log("Server is running on http://localhost:3000"); });

js

    import Cap from "@cap.js/server";  const cap = new Cap({  tokens_store_path: ".data/tokensList.json", });  Bun.serve({  port: 3000,  routes: {  "/api/challenge": {  POST: () => {  return Response.json(cap.createChallenge());  },  },  "/api/redeem": {  POST: async (req) => {  const body = await req.json();  const { token, solutions } = body;   if (!token || !solutions) {  return Response.json({ success: false }, { status: 400 });  }   return Response.json(await cap.redeemChallenge({ token, solutions }));  },  },  }, });  console.log(`Server running at http://localhost:3000`);

js

    import { Hono } from "hono"; import Cap from "@cap.js/server";  const app = new Hono(); const cap = new Cap({  tokens_store_path: ".data/tokensList.json", });  app.post("/api/challenge", (c) => {  return c.json(cap.createChallenge()); });  app.post("/api/redeem", async (c) => {  const { token, solutions } = await c.req.json();  if (!token || !solutions) {  return c.json({ success: false }, 400);  }   return c.json(await cap.redeemChallenge({ token, solutions })); });  export default {  port: 3000,  fetch: app.fetch, };

js

    import express from "express"; import Cap from "@cap.js/server";  const app = express(); app.use(express.json());  const cap = new Cap({  tokens_store_path: ".data/tokensList.json", });  app.post("/api/challenge", (req, res) => {  res.json(cap.createChallenge()); });  app.post("/api/redeem", async (req, res) => {  const { token, solutions } = req.body;  if (!token || !solutions) {  return res.status(400).json({ success: false });  }  res.json(await cap.redeemChallenge({ token, solutions })); });  app.listen(3000, () => {  console.log("Listening on port 3000"); });

Then, you can verify the CAPTCHA tokens on your server by calling the `await cap.validateToken("<token>")` method. Example:

js

    const { success } = await cap.validateToken("9363220f...");   if (success) {  console.log("Valid token"); } else {  console.log("Invalid token"); }

## Supported methods and arguments 

The following methods are supported:

#### `new Cap({ ... })` 

Creates a new Cap instance.

**Arguments**

json

    {  "tokens_store_path": ".data/tokensList.json",  "noFSState": false,  "state": {  "challengesList": {},  "tokensList": {}  } }

You can always access or set the options of the `Cap` class by accessing or modifying the `cap.config` object.

#### `cap.createChallenge({ ... })` 

**Arguments**

json

    {  "challengeCount": 18,  "challengeSize": 32,  "challengeDifficulty": 4,  "expiresMs": 600000 }

**Response:** `{ challenge, expires }`

> if `noFSState` is set to `true`, the state will be stored in memory only. You can use this together with setting `config.state` to use a custom db such as redis for storing tokens. Added by #16

#### `cap.redeemChallenge({ ... })` 

json

    {  token,  solutions }

**Response:** `{ success, token }`

#### `await cap.validateToken("...", { ... })` 

**Arguments:**

json

    {  "keepToken": false }

**Response:** `{ success }`

---

## Page: https://capjs.js.org/guide/widget.html

# @cap.js/widget 

NOTE

**Requirements:** All modern browsers should be supported, but the build script specifically targets the last 10 versions of Chrome, Firefox, Safari and Edge.

`@cap.js/widget` is Cap's client-side library. It includes the `cap-widget` web component, the invisible mode and the Captcha solver. First, add it to your client-side code:

jsdelivrunpkgstandalone server

html

    <script src="https://cdn.jsdelivr.net/npm/@cap.js/widget"></script>

html

    <script src="https://unpkg.com/@cap.js/widget"></script>

html

    <script src="https://<server url>/assets/widget.js"></script>  <!-- tip: make sure to set the wasm endpoint too! -->

WARNING

We're using the latest version of the library here for simplicity, but you should optimally pin a specific version to avoid breaking changes in the future.

You can now use the `<cap-widget>` component in your HTML.

html

    <cap-widget id="cap" data-cap-api-endpoint="<your cap endpoint>"></cap-widget>

NOTE

You'll need to start a server with an API exposing the Cap methods running at the same URL as specified in the `data-cap-api-endpoint` attribute.

The following attributes are supported:

*   `data-cap-api-endpoint`: API endpoint (required)
*   `data-cap-worker-count`: Number of workers to use (defaults to `navigator.hardwareConcurrency || 8`)

Then, in your JavaScript, listen for the `solve` event to capture the token when generated:

js

    const widget = document.querySelector("#cap");  widget.addEventListener("solve", function (e) {  const token = e.detail.token;   // Handle the token as needed });

Alternatively, you can use `onsolve=""` directly within the widget or wrap the widget in a `<form></form>` (where Cap will automatically submit the token alongside other form data. for this, it'll create a hidden field with name set to its `data-cap-hidden-field-name` attribute or `cap-token`).

## Supported events 

The following custom events are supported:

*   `solve`: Triggered when the token is generated.
*   `error`: Triggered when an error occurs.
*   `reset`: Triggered when the widget is reset.
*   `progress`: Triggered when there's a progress update while in verification.

## i18n 

You can change the text on each label of the widget by setting the `data-cap-i18n-*` attribute, like this:

html

    <cap-widget  id="cap"  data-cap-api-endpoint="<your cap endpoint>"  data-cap-i18n-verifying-label="Verifying..."  data-cap-i18n-initial-state="I'm a human"  data-cap-i18n-solved-label="I'm a human"  data-cap-i18n-error-label="Error" ></cap-widget>

## Custom fetch 

You can override the default fetch implementation by setting `window.CAP_CUSTOM_FETCH` to a custom function. This function will receive the URL and options as arguments and should return a promise that resolves to the response.

js

    window.CAP_CUSTOM_FETCH = function (url, options) {  // Custom fetch implementation  return fetch(url, options); };

## Custom WASM URL 

You can override the default WASM URL by setting `window.CAP_CUSTOM_WASM_URL` to a custom URL. This URL will be used to load the WASM module. This defaults to `https://cdn.jsdelivr.net/npm/@cap.js/wasm@0.0.4/browser/cap_wasm.min.js`

---

## Page: https://capjs.js.org/guide/solver.html

# @cap.js/solver 

`@cap.js/solver` is a standalone library that can be used to solve Cap challenges from the server. It's extremely simple (no dependencies, one single file) yet very fast and efficient. Note that it can only be used with Bun.

## Installation 

bash

    bun add @cap.js/solver

## Usage 

js

    import solver from "@cap.js/solver";  const CHALLENGES = [  ["a5b6fda4aaed97cf61d7dd9259f733b5", "d455"],  ["286bcc39249f9ee698314b600c32e40f", "f0ff"],  ["501350aa7c46573cb604284554045703", "4971"],  ["a55c02f3b9b4cd088a5a7ee3d4941c14", "eab7"],  ["5f3362c12e2779f56f4ef75b4494f5e6", "999f"],  /* ... */ ];  console.log(await solver(CHALLENGES));

**Output:**

json

    [  ["a5b6fda4aaed97cf61d7dd9259f733b5", "d455", 67302],  ["286bcc39249f9ee698314b600c32e40f", "f0ff", 64511],  ["501350aa7c46573cb604284554045703", "4971", 40440],  ["a55c02f3b9b4cd088a5a7ee3d4941c14", "eab7", 27959],  ["5f3362c12e2779f56f4ef75b4494f5e6", "999f", 71259],  ... ]

## FAQ 

### Why is this needed? 

Mainly for M2M interactions, where you want to solve Cap challenges on the server without user interaction.

### Doesn't this defeat the purpose of Cap? 

Not really. Server-side solving is a core use case of proof-of-work CAPTCHAs like Cap or altcha. It's about proving effort, not necessarily involving a human. Learn more

---

## Page: https://capjs.js.org/guide/cli.html

# @cap.js/cli 

`cli` is a simple command-line interface for solving CAPTCHAs made with Cap. It's mainly designed for testing and when you need to solve these CAPTCHAs in a browser without JavaScript support.

bash

    ❯ bunx '@cap.js/cli'

    @cap.js/cli cli solver for cap challenges  Usage:  $ bunx '@cap.js/cli' <challenges>  Options:  <challenges> The challenges to solve in  format `salt:target`

If you're on Windows, you might need to use `bunx '@cap.js/cli'` (with quotes) instead of `bunx @cap.js/cli` to avoid issues with the `@` symbol.

## Usage 

To use `cli`, you need to pass the challenges to solve in the format `salt:target`, separated by a space. For example:

bash

    ❯ bunx '@cap.js/cli' e455cea65e98b:dceb fb8d25f6abac:93f1 ...

    @cap.js/cli 2 challenges  e455cea65e98b:dceb:9100 fb8d25f6abac:93f1:76570 ...

The output format is `salt:target:nonce`, where `nonce` is the solution nonce. You can then turn this into JSON to send to the Cap server helper:

js

    const input = "e455cea65e98b:dceb:9100\nfb8d25f6abac:93f1:76570";  console.log(input.split("\n").map((l) => l.split(":")));

json

    [  ["e455cea65e98b", "dceb", "9100"],  ["fb8d25f6abac", "93f1", "76570"] ]

## Generating the command 

You can generate code to call `cap.js/cli` from the challenges using this:

js

    const response = {  "challenge": [  [ "e455cea65e98b", "dceb" ],  [ "fb8d25f6abac", "93f1" ],  ...  ],  "token": "...",  "expires": 1745343553913 };  const challenges = response.challenge.map((c) => c.join(":")).join(" "); const command = `bunx '@cap.js/cli' ${challenges}`;  console.log(command); // bunx '@cap.js/cli' e455cea65e98b:dceb fb8d25f6abac:93f1 ...

WARNING

The code above doesn't validate if the challenges are valid and not potentially malicious. If you're getting the challenge list from an untrusted source, make sure to validate it before giving them to the user.

---

## Page: https://capjs.js.org/guide/middleware/index.html

# About checkpoints 

Cap's Checkpoints (previously known as middlewares) allow you to replicate Cloudflare's browser check interstitial. This helps prevent bots, LLMs and automated abuse from ever reaching your website.

They're extremely simple to set up and use, with you only having to add a few lines of code to your server, unlike moving your entire website over to cloudflare.

![Example of Cap's checkpoint](/assets/demo.ByJk_mHo.png)

Note that this is kind of a nuclear solution, as it _will_ also impact good bots such as search engine crawlers.

---

## Page: https://capjs.js.org/guide/middleware/elysia.html

# Elysia checkpoint 

## Installation 

bash

    bun add elysia @cap.js/middleware-elysia

## Usage 

javascript

    import { Elysia, file } from "elysia"; import { capMiddleware } from "@cap.js/middleware-elysia";  new Elysia()  .use(  capMiddleware({  token_validity_hours: 32, // how long the token is valid for  tokens_store_path: ".data/tokensList.json",  token_size: 16, // token size in bytes  verification_template_path: join(  dirname(fileURLToPath(import.meta.url)),  "./index.html"  ),  scoping: "scoped", // 'global' | 'scoped'  })  )  .get("/", () => "Hello Elysia!")  .listen(3000);

That's it! You can now use the middleware to protect your routes.

---

## Page: https://capjs.js.org/guide/middleware/hono.html

# Hono checkpoint 

## Installation 

bash

    bun add hono @cap.js/checkpoint-hono

## Usage 

javascript

    import { Hono } from "hono"; import { serveStatic } from "hono/bun"; import { capCheckpoint } from "@cap.js/checkpoint-hono";  const app = new Hono();  app.use(  "*",  capCheckpoint({  token_validity_hours: 32, // how long the token is valid for  tokens_store_path: ".data/tokensList.json",  token_size: 16, // token size in bytes  verification_template_path: join(  dirname(fileURLToPath(import.meta.url)),  "./index.html"  ),  }) );  app.get("/", (c) => c.text("Hello Hono!"));  export default app;

That's it! You can now use the middleware to protect your routes.

---

## Page: https://capjs.js.org/guide/middleware/express.html

# Express checkpoint 

## Installation 

bash

    bun add express cookie-parser @cap.js/middleware-express

## Usage 

javascript

    import express from "express"; import cookieParser from "cookie-parser"; import path from "path"; import { dirname } from "path"; import { fileURLToPath } from "url"; import { capCheckpoint } from "@cap.js/checkpoint-express";  const app = express(); const __dirname = dirname(fileURLToPath(import.meta.url));  app.use(express.json()); app.use(cookieParser());  app.use(  capCheckpoint({  /*  token_validity_hours: 32,  tokens_store_path: ".data/tokensList.json",  token_size: 16,  verification_template_path: join(__dirname, "./index.html"),  */  }) );  app.get("/", (req, res) => {  res.sendFile(path.join(__dirname, "success.html")); });  app.listen(3000, () => {  console.log(`Server running on http://localhost:3000`); });

That's it! You can now use the middleware to protect your routes.

---

## Page: https://capjs.js.org/guide/middleware/

# About checkpoints 

Cap's Checkpoints (previously known as middlewares) allow you to replicate Cloudflare's browser check interstitial. This helps prevent bots, LLMs and automated abuse from ever reaching your website.

They're extremely simple to set up and use, with you only having to add a few lines of code to your server, unlike moving your entire website over to cloudflare.

![Example of Cap's checkpoint](/assets/demo.ByJk_mHo.png)

Note that this is kind of a nuclear solution, as it _will_ also impact good bots such as search engine crawlers.