Easycaptcha Python SDK

Solve hCaptcha challenges with Easycaptcha from Python 3.10+. Includes synchronous and asynchronous clients.

Install

python -m pip install easycaptcha-sdk

Get an API key from the dashboard and set EASYCAPTCHA_API_KEY in your environment.

Solve a captcha

This example creates a token job, waits for it to finish, and prints the token:

import os
import time
from easycaptcha.backends.urllib import UrllibClient

with UrllibClient(os.environ["EASYCAPTCHA_API_KEY"]) as client:
    job = client.create_job({
        "type": "hcaptcha_token",
        "sitekey": "your-sitekey",
        "url": "https://example.com",
        "hold": 30,
    })

    while job["status"] in ("queued", "running"):
        time.sleep(1)
        job = client.get_job(job["task_id"])

    if job["status"] == "failed":
        raise RuntimeError(job["error"]["code"])
    print(job["result"]["token"])

hold: 30 lets creation wait up to 30 seconds for a result. If the job is still pending, keep checking with get_job. Ending an HTTP request does not cancel the job.

For enterprise tokens, use "type": "hcaptcha_enterprise_token" and include rqdata. For image recognition, use "type": "hcaptcha_recognition" and pass the challenge object as task; challenge media must be base64 data URIs. See the API documentation for request fields and result formats.

Async usage

Install the async HTTP dependency:

python -m pip install 'easycaptcha-sdk[httpx]'

import asyncio
import os
from easycaptcha.backends.httpx import AsyncHttpxClient

async def main():
    async with AsyncHttpxClient(os.environ["EASYCAPTCHA_API_KEY"]) as client:
        job = await client.create_job({
            "type": "hcaptcha_token",
            "sitekey": "your-sitekey",
            "url": "https://example.com",
            "hold": 30,
        })
        while job["status"] in ("queued", "running"):
            await asyncio.sleep(1)
            job = await client.get_job(job["task_id"])
        if job["status"] == "failed":
            raise RuntimeError(job["error"]["code"])
        print(job["result"]["token"])

asyncio.run(main())

Balance and feedback

Inside your client context:

balance = client.get_balance()
print(balance["balance_microcents"])

# After checking whether the result worked:
client.send_feedback(job["task_id"], success=True)

Async clients use the same methods with await. Balance values are integer strings: 100,000,000 microcents = USD 1. Use int for exact arithmetic.

Client options

with UrllibClient(os.environ["EASYCAPTCHA_API_KEY"], timeout=60) as client:
    balance = client.get_balance()

timeout is in seconds and defaults to 45. You can also set base_url or developer_tag.

If you already use another HTTP library, choose its client instead:

Install extras with python -m pip install 'easycaptcha-sdk[requests]', for example. The urllib and requests async clients run HTTP in a thread; httpx and curl_cffi support native async requests.

The optional-library clients accept a session for custom proxy or TLS settings. Use with or async with to close client-owned sessions; supplied sessions stay open.

Handle errors

from easycaptcha import APIError

try:
    with UrllibClient(os.environ["EASYCAPTCHA_API_KEY"]) as client:
        balance = client.get_balance()
except APIError as error:
    print(error.problem.get("code"), error.request_id)

HTTP errors raise APIError; network failures raise TransportError; invalid responses or extension downloads raise ProtocolError. A failed job is returned with status: "failed" and error.

The SDK does not retry requests automatically. A job submission may succeed even if its response is lost, so check its outcome before submitting again.

Download the browser extension

with UrllibClient() as client:  # No API key needed to download.
    extension = client.download_extension()

configured = extension.configure_settings({
    "apikey": os.environ["EASYCAPTCHA_API_KEY"],
    "enabled": True,
})
configured.save("extension.zip")

Downloads select the latest Chromium release and verify its checksum. Pass version_id="your-extension-version-id" to select a release, or use get_extension() for metadata only.

Extract the ZIP and load it as an unpacked extension. Settings support apikey, enabled, burst, and fast; saved popup preferences override these defaults. Keep configured ZIPs private because they contain your API key. See the extension setup guide.

Support

Open a support ticket with your SDK/runtime version, a minimal example, and the error code or request ID. Remove credentials. Development and release instructions are in CONTRIBUTING.md.

MIT license.