ad-m · ad-m · Mar 7, 2026 · Mar 7, 2026 · Mar 7, 2026 · Mar 7, 2026
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -7,6 +7,9 @@ Unreleased
 Added
 #####
 
+- Add ``AsyncAnticaptchaClient`` and ``AsyncJob`` for async/await usage with ``httpx`` (``pip install python-anticaptcha[async]``)
+- Rename ``base.py`` → ``sync_client.py`` for symmetry with ``async_client.py``; backward-compatible ``base.py`` shim preserved
+- Rename sync example files with ``sync_`` prefix to match ``async_`` examples
 - Add context manager support to ``AnticaptchaClient`` (``__enter__``, ``__exit__``, ``close``)
 - Add ``ANTICAPTCHA_API_KEY`` environment variable fallback for ``AnticaptchaClient``
 - Add ``Proxy`` frozen dataclass with ``parse_url()`` and ``to_kwargs()`` methods

diff --git a/README.md b/README.md
@@ -20,6 +20,12 @@ Install as standard Python package using:
 pip install python-anticaptcha
 ```
 
+For async support (FastAPI, aiohttp, Starlette, etc.):
+
+```
+pip install python-anticaptcha[async]
+```
+
 ## Usage
 
 To use this library you need [Anticaptcha.com](http://getcaptchasolution.com/p9bwplkicx) API key.
@@ -42,6 +48,29 @@ with AnticaptchaClient(api_key) as client:
     job.join()
 ```
 
+## Async Usage
+
+For async frameworks, use `AsyncAnticaptchaClient` — the API mirrors the sync
+client but all methods are awaitable:
+
+```python
+from python_anticaptcha import AsyncAnticaptchaClient, NoCaptchaTaskProxylessTask
+
+api_key = '174faff8fbc769e94a5862391ecfd010'
+site_key = '6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-'
+url = 'https://www.google.com/recaptcha/api2/demo'
+
+async with AsyncAnticaptchaClient(api_key) as client:
+    task = NoCaptchaTaskProxylessTask(url, site_key)
+    job = await client.create_task(task)
+    await job.join()
+    print(job.get_solution_response())
+```
+
+The full integration example is available in file `examples/async_recaptcha_request.py`.
+
+## Sync Usage
+
 ### Solve recaptcha
 
 Example snippet for Recaptcha:
@@ -60,7 +89,7 @@ job.join()
 print(job.get_solution_response())
 ```
 
-The full integration example is available in file `examples/recaptcha_request.py`.
+The full integration example is available in file `examples/sync_recaptcha_request.py`.
 
 If you process the same page many times, to increase reliability you can specify
 whether the captcha is visible or not. This parameter is not required, as the

diff --git a/docs/api.rst b/docs/api.rst
@@ -1,10 +1,17 @@
 API
 ===
 
-Base
-----
+Sync Client
+-----------
 
- .. automodule:: python_anticaptcha.base
+ .. automodule:: python_anticaptcha.sync_client
+   :members:
+   :undoc-members:
+
+Async Client
+------------
+
+ .. automodule:: python_anticaptcha.async_client
    :members:
    :undoc-members:
 

diff --git a/docs/usage.rst b/docs/usage.rst
@@ -21,6 +21,35 @@ The client can be used as a context manager to ensure the underlying session is
         job = client.create_task(task)
         job.join()
 
+Async client
+############
+
+.. note::
+
+   Requires the ``async`` extra: ``pip install python-anticaptcha[async]``
+
+For async frameworks (FastAPI, aiohttp, Starlette) use ``AsyncAnticaptchaClient`` —
+the API mirrors the sync client but all methods are awaitable:
+
+.. code:: python
+
+    from python_anticaptcha import AsyncAnticaptchaClient, NoCaptchaTaskProxylessTask
+
+    api_key = '174faff8fbc769e94a5862391ecfd010'
+    site_key = '6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-'
+    url = 'https://www.google.com/recaptcha/api2/demo'
+
+    async with AsyncAnticaptchaClient(api_key) as client:
+        task = NoCaptchaTaskProxylessTask(url, site_key)
+        job = await client.create_task(task)
+        await job.join()
+        print(job.get_solution_response())
+
+The full integration example is available in file ``examples/async_recaptcha_request.py``.
+
+Sync client
+###########
+
 Solve recaptcha
 ###############
 
@@ -40,7 +69,7 @@ Example snippet for Recaptcha:
     job.join()
     print(job.get_solution_response())
 
-The full integration example is available in file ``examples/recaptcha_request.py``.
+The full integration example is available in file ``examples/sync_recaptcha_request.py``.
 
 If you process the same page many times, to increase reliability you can specify
 whether the captcha is visible or not. This parameter is not required, as the

diff --git a/examples/async_balance.py b/examples/async_balance.py
@@ -0,0 +1,17 @@
+import asyncio
+from os import environ
+from pprint import pprint
+
+from python_anticaptcha import AsyncAnticaptchaClient
+
+api_key = environ["KEY"]
+
+
+async def process():
+    async with AsyncAnticaptchaClient(api_key) as client:
+        balance = await client.get_balance()
+        pprint(balance)
+
+
+if __name__ == "__main__":
+    asyncio.run(process())
diff --git a/examples/async_recaptcha_request.py b/examples/async_recaptcha_request.py
@@ -0,0 +1,40 @@
+import asyncio
+import re
+from os import environ
+
+import httpx
+
+from python_anticaptcha import AsyncAnticaptchaClient, NoCaptchaTaskProxylessTask
+
+api_key = environ["KEY"]
+site_key_pattern = 'data-sitekey="(.+?)"'
+url = "https://www.google.com/recaptcha/api2/demo?invisible=false"
+EXPECTED_RESULT = "Verification Success... Hooray!"
+
+
+async def get_form_html(session: httpx.AsyncClient) -> str:
+    return (await session.get(url)).text
+
+
+async def get_token(client: AsyncAnticaptchaClient, form_html: str) -> str:
+    site_key = re.search(site_key_pattern, form_html).group(1)
+    task = NoCaptchaTaskProxylessTask(website_url=url, website_key=site_key)
+    job = await client.create_task(task)
+    await job.join()
+    return job.get_solution_response()
+
+
+async def form_submit(session: httpx.AsyncClient, token: str) -> str:
+    return (await session.post(url, data={"g-recaptcha-response": token})).text
+
+
+async def process():
+    async with AsyncAnticaptchaClient(api_key) as client, httpx.AsyncClient() as session:
+        html = await get_form_html(session)
+        token = await get_token(client, html)
+        return await form_submit(session, token)
+
+
+if __name__ == "__main__":
+    result = asyncio.run(process())
+    assert "Verification Success... Hooray!" in result
diff --git a/examples/antigate.py → examples/sync_antigate.py b/examples/antigate.py → examples/sync_antigate.py
diff --git a/examples/app_stat.py → examples/sync_app_stat.py b/examples/app_stat.py → examples/sync_app_stat.py
diff --git a/examples/balance.py → examples/sync_balance.py b/examples/balance.py → examples/sync_balance.py
diff --git a/examples/funcaptcha_request.py → examples/sync_funcaptcha_request.py b/examples/funcaptcha_request.py → examples/sync_funcaptcha_request.py
diff --git a/examples/funcaptcha_selenium.py → examples/sync_funcaptcha_selenium.py b/examples/funcaptcha_selenium.py → examples/sync_funcaptcha_selenium.py
diff --git a/examples/funcaptcha_selenium_callback.py → ...ples/sync_funcaptcha_selenium_callback.py b/examples/funcaptcha_selenium_callback.py → ...ples/sync_funcaptcha_selenium_callback.py
diff --git a/examples/hcaptcha_request.py → examples/sync_hcaptcha_request.py b/examples/hcaptcha_request.py → examples/sync_hcaptcha_request.py
diff --git a/examples/hcaptcha_request_proxy.py → examples/sync_hcaptcha_request_proxy.py b/examples/hcaptcha_request_proxy.py → examples/sync_hcaptcha_request_proxy.py
diff --git a/examples/recaptcha3_request.py → examples/sync_recaptcha3_request.py b/examples/recaptcha3_request.py → examples/sync_recaptcha3_request.py
diff --git a/examples/recaptcha_request.py → examples/sync_recaptcha_request.py b/examples/recaptcha_request.py → examples/sync_recaptcha_request.py
diff --git a/examples/recaptcha_selenium.py → examples/sync_recaptcha_selenium.py b/examples/recaptcha_selenium.py → examples/sync_recaptcha_selenium.py
diff --git a/examples/recaptcha_selenium_callback.py → examples/sync_recaptcha_selenium_callback.py b/examples/recaptcha_selenium_callback.py → examples/sync_recaptcha_selenium_callback.py
diff --git a/examples/remote_image.py → examples/sync_remote_image.py b/examples/remote_image.py → examples/sync_remote_image.py
diff --git a/examples/text.py → examples/sync_text.py b/examples/text.py → examples/sync_text.py
diff --git a/examples/text_stream.py → examples/sync_text_stream.py b/examples/text_stream.py → examples/sync_text_stream.py
diff --git a/pyproject.toml b/pyproject.toml
@@ -10,7 +10,7 @@ license = "MIT"
 requires-python = ">=3.9"
 dependencies = ["requests"]
 dynamic = ["version"]
-keywords = ["recaptcha", "captcha", "development"]
+keywords = ["recaptcha", "captcha", "development", "asyncio", "async", "httpx"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
@@ -21,14 +21,16 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Framework :: AsyncIO",
+    "Topic :: Internet :: WWW/HTTP",
 ]
 
 [project.urls]
 Homepage = "https://github.com/ad-m/python-anticaptcha"
 
 [project.optional-dependencies]
 async = ["httpx>=0.24"]
-tests = ["pytest", "retry", "selenium"]
+tests = ["pytest", "pytest-asyncio", "httpx>=0.24", "retry", "selenium", "six"]
 docs = ["sphinx", "sphinx-rtd-theme"]
 
 [tool.setuptools.package-data]

diff --git a/python_anticaptcha/__init__.py b/python_anticaptcha/__init__.py
@@ -1,9 +1,9 @@
 import contextlib
 from importlib.metadata import PackageNotFoundError, version
 
-from .base import AnticaptchaClient, Job
 from .exceptions import AnticaptchaException
 from .proxy import Proxy
+from .sync_client import AnticaptchaClient, Job
 from .tasks import (
     AntiGateTask,
     AntiGateTaskProxyless,
@@ -28,6 +28,17 @@
 with contextlib.suppress(PackageNotFoundError):
     __version__ = version(__name__)
 
+
+def __getattr__(name: str) -> type:
+    if name in ("AsyncAnticaptchaClient", "AsyncJob"):
+        from .async_client import AsyncAnticaptchaClient, AsyncJob
+
+        globals()["AsyncAnticaptchaClient"] = AsyncAnticaptchaClient
+        globals()["AsyncJob"] = AsyncJob
+        return globals()[name]
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
 __all__ = [
     "AnticaptchaClient",
     "Job",
@@ -50,4 +61,6 @@
     "AntiGateTask",
     "AnticaptchaException",
     "AnticatpchaException",
+    "AsyncAnticaptchaClient",
+    "AsyncJob",
 ]