Browser extension

Install the Chromium extension and control its use on each site.

Download and configure

Download the extension from the public download page. Follow the installation instructions there for your package and browser. The first release targets Chromium browsers.

Open the popup and choose Free plan for 25 recognition groups a day, with no account or payment required. Accept the terms and privacy policy to activate it.

For paid usage, choose I have an API key and paste a dedicated key. The extension checks the key and available balance. Follow account and setup to create a paid account.

Enable solving

The popup’s Solve hCaptcha switch controls new task submissions. Turn it off to stop solving. Paid users can also enable burst and fast.

A task that has already been submitted may still finish and use credit. Closing the popup does not cancel it.

Read the popup

The popup shows connection status, your available balance, the current task state and the most recent actionable error. Use the refresh control to update the balance.

An invalid key stops API activity and shows the API-key form so you can correct it. You can also switch to the free plan, which removes the paid key. An insufficient-balance message means you need to add credit in the dashboard.

Replace a key

Revoke the old key in the dashboard, create a new one and replace it in the extension settings. Clearing the saved key disables new submissions.

Use a separate key for each installation. Do not paste your account password into the API-key field.

Configure defaults in the manifest

For an unpacked or custom installation, add easycaptcha_settings to the root manifest.json before loading the extension:

{
  "easycaptcha_settings": {
    "apikey": "your-dedicated-api-key",
    "developer_tag": "your-activated-developer-tag",
    "enabled": true,
    "burst": false,
    "fast": false
  }
}

This block goes alongside the manifest’s existing fields. Keep the rest of the manifest unchanged.

Every field is optional. Use JSON booleans, not strings such as "false". Invalid configuration is ignored. Free-plan keys and enrollment timestamps cannot be supplied through the manifest; activate the free plan in the popup.

developer_tag is sent in the body of each recognition task creation request. It can only be configured in the manifest: the popup, settings RPC, and saved sync settings cannot change it. Use the exact tag activated in the dashboard; see developer tag integration for attribution rules and eligible paid usage.

Saved popup settings override the other manifest defaults, including a removed API key. Editing the manifest does not override preferences in an existing browser profile. Reload the extension after editing it. Rebuilding or replacing the package replaces the manifest, so apply your defaults to each new package.

The Python and JavaScript SDK helpers can configure a downloaded ZIP before you extract it. They return a new package and validate field names and types. A configured package contains its API key in plain text: use a separately revocable key for each installation and keep that package private.

If a task does not finish

Check that solving is enabled, the key is valid and your account has enough credit. Read the current task message before trying again.

A network timeout does not tell you whether a submitted task finished. Avoid submitting the same challenge again just because a request timed out.

If you report a problem, include the extension version, task ID and request ID when available. Never include your password or full API key.

Use an automation framework

Read extension automation for Chrome for Testing examples with nodriver, Playwright, and Selenium. The examples keep extension settings in a persistent browser profile.