capzy 0.0.1__py3-none-any.whl

capzy/__init__.py

@@ -0,0 +1,36 @@
+"""Capzy — official Python SDK.
+
+Quick start:
+
+    from capzy import CapzyClient
+
+    capzy = CapzyClient("capzy_xxxxxxxxxxxxxxxxxxxxxxxx")
+
+    solution = capzy.solve(
+        type="AntiTurnstileTaskProxyLess",
+        website_url="https://example.com",
+        website_key="0x4AAA...",
+    )
+    print(solution["token"])
+
+Find your API key at https://capzy.ai/dashboard.
+Every new account gets $0.10 in free credits — no card required.
+"""
+
+from capzy._version import __version__
+from capzy.client import CapzyClient
+from capzy.exceptions import (
+    ApiError,
+    CapzyError,
+    TaskFailedError,
+    TaskTimeoutError,
+)
+
+__all__ = [
+    "__version__",
+    "CapzyClient",
+    "CapzyError",
+    "ApiError",
+    "TaskFailedError",
+    "TaskTimeoutError",
+]

capzy/_version.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

capzy/client.py

@@ -0,0 +1,224 @@
+"""Sync HTTP client for the Capzy API.
+
+Most callers want the module-level shortcuts (`capzy.solve(...)`),
+not this class. Use ``CapzyClient`` directly only when you need to
+inject a custom ``requests.Session`` (proxy, retries, custom TLS).
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Mapping
+from urllib.parse import urljoin
+
+import requests
+
+from capzy._version import __version__
+from capzy.exceptions import (
+    ApiError,
+    CapzyError,
+    TaskFailedError,
+    TaskTimeoutError,
+)
+
+DEFAULT_BASE_URL = "https://api.capzy.ai"
+DEFAULT_TIMEOUT = 30.0       # per-request HTTP timeout
+DEFAULT_POLL_INTERVAL = 2.0  # seconds between getTaskResult polls
+DEFAULT_MAX_WAIT = 180.0     # cap on total polling time per .solve()
+
+
+# snake_case → camelCase wire-name remap. Anything not listed passes
+# through untouched, so you can also just write camelCase directly.
+_KEY_RENAME = {
+    "website_url": "websiteURL",
+    "website_key": "websiteKey",
+    "website_public_key": "websitePublicKey",
+    "is_invisible": "isInvisible",
+    "is_enterprise": "isEnterprise",
+    "page_action": "pageAction",
+    "min_score": "minScore",
+    "api_domain": "apiDomain",
+    "enterprise_payload": "enterprisePayload",
+    "data_s": "data-s",
+    "user_agent": "userAgent",
+    "proxy_address": "proxyAddress",
+    "proxy_port": "proxyPort",
+    "proxy_login": "proxyLogin",
+    "proxy_password": "proxyPassword",
+    "proxy_type": "proxyType",
+    "captcha_id": "captchaId",
+    "captcha_url": "captchaUrl",
+    "geetest_api_server_subdomain": "geetestApiServerSubdomain",
+    "geetest_get_lib": "geetestGetLib",
+    "funcaptcha_api_js_subdomain": "funcaptchaApiJSSubdomain",
+    "case_sensitive": "case",
+    "min_length": "minLength",
+    "max_length": "maxLength",
+    "app_id": "appId",
+    "validate_id": "validateId",
+    "aws_key": "awsKey",
+    "aws_iv": "awsIv",
+    "aws_context": "awsContext",
+    "aws_challenge_js": "awsChallengeJS",
+    "package_name": "packageName",
+    "device_id": "deviceId",
+    "device_name": "deviceName",
+}
+
+
+def _camelize_params(params: Mapping[str, Any]) -> dict[str, Any]:
+    """Pass-through with snake_case keys auto-converted, None values dropped."""
+    out: dict[str, Any] = {}
+    for k, v in params.items():
+        if v is None:
+            continue
+        out[_KEY_RENAME.get(k, k)] = v
+    return out
+
+
+class CapzyClient:
+    """Lower-level handle. Most callers use the module-level functions.
+
+    Args:
+        api_key:   API key from https://capzy.ai/dashboard
+        base_url:  override the API root (defaults to api.capzy.ai)
+        timeout:   per-request HTTP timeout in seconds
+        session:   inject a custom ``requests.Session``
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        session: requests.Session | None = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError(
+                "api_key is required (get one at https://capzy.ai/dashboard)"
+            )
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/") + "/"
+        self.timeout = timeout
+        self._session = session or requests.Session()
+        self._session.headers.setdefault("User-Agent", f"capzy-python/{__version__}")
+        self._session.headers.setdefault("Accept", "application/json")
+
+    # ── Public methods ──────────────────────────────────────────────────
+
+    def get_balance(self) -> float:
+        body = self._post("getBalance", {"clientKey": self.api_key})
+        return float(body.get("balance", 0.0))
+
+    def create_task(self, *, type: str, **params: Any) -> dict[str, Any]:
+        """Submit a task — returns the raw createTask response."""
+        task_body = {"type": type, **_camelize_params(params)}
+        return self._post(
+            "createTask",
+            {"clientKey": self.api_key, "task": task_body},
+        )
+
+    def get_task_result(self, task_id: str) -> dict[str, Any]:
+        return self._post(
+            "getTaskResult",
+            {"clientKey": self.api_key, "taskId": task_id},
+        )
+
+    def report_score(
+        self,
+        task_id: str,
+        score: float,
+        action: str | None = None,
+        hostname: str | None = None,
+    ) -> None:
+        """Report a reCAPTCHA v3 score for dashboard analytics."""
+        self._post(
+            "reportScore",
+            {
+                "clientKey": self.api_key,
+                "taskId": task_id,
+                "score": score,
+                "action": action,
+                "hostname": hostname,
+            },
+        )
+
+    def solve(
+        self,
+        *,
+        type: str,
+        poll_interval: float = DEFAULT_POLL_INTERVAL,
+        max_wait: float = DEFAULT_MAX_WAIT,
+        **params: Any,
+    ) -> dict[str, Any]:
+        """Submit + poll until ready. Returns the ``solution`` dict.
+
+        Raises:
+            ApiError: createTask was rejected (e.g. bad key, wrong type).
+            TaskFailedError: the task ran but failed (refunded).
+            TaskTimeoutError: ``max_wait`` elapsed (refunded).
+        """
+        created = self.create_task(type=type, **params)
+
+        # ImageToText / MathCaptcha return the solution synchronously.
+        if created.get("solution"):
+            return created["solution"]
+
+        task_id = created.get("taskId")
+        if not task_id:
+            raise CapzyError("createTask did not return a taskId")
+
+        server_timeout = created.get("timeout")
+        if isinstance(server_timeout, (int, float)) and server_timeout > 0:
+            max_wait = min(max_wait, float(server_timeout) + 5.0)
+
+        deadline = time.monotonic() + max_wait
+        while True:
+            time.sleep(poll_interval)
+            result = self.get_task_result(task_id)
+            status = result.get("status")
+            if status == "ready":
+                return result.get("solution") or {}
+            if status == "failed":
+                raise TaskFailedError(
+                    task_id,
+                    result.get("errorCode"),
+                    result.get("errorDescription"),
+                )
+            if time.monotonic() >= deadline:
+                raise TaskTimeoutError(task_id, max_wait)
+
+    # ── Internals ───────────────────────────────────────────────────────
+
+    def _post(self, path: str, body: Mapping[str, Any]) -> dict[str, Any]:
+        url = urljoin(self.base_url, path)
+        clean = {k: v for k, v in body.items() if v is not None}
+        try:
+            resp = self._session.post(url, json=clean, timeout=self.timeout)
+        except requests.RequestException as exc:
+            raise CapzyError(f"network error talking to {url}: {exc}") from exc
+
+        try:
+            data = resp.json()
+        except ValueError as exc:
+            raise CapzyError(
+                f"expected JSON from {url} (HTTP {resp.status_code}): "
+                f"{resp.text[:200]}"
+            ) from exc
+
+        if not isinstance(data, dict):
+            raise CapzyError(f"unexpected response shape from {url}: {data!r}")
+
+        error_id = data.get("errorId", 0) or 0
+        if error_id != 0:
+            raise ApiError(
+                error_id=int(error_id),
+                error_code=data.get("errorCode"),
+                error_description=data.get("errorDescription"),
+                recommended_task_type=data.get("recommendedTaskType"),
+                raw=data,
+            )
+
+        if resp.status_code >= 400:
+            raise CapzyError(f"HTTP {resp.status_code} from {url}: {resp.text[:200]}")
+        return data

capzy/exceptions.py

@@ -0,0 +1,61 @@
+"""Exceptions raised by the Capzy SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class CapzyError(Exception):
+    """Base class for every error raised by this SDK."""
+
+
+class ApiError(CapzyError):
+    """The API returned a non-zero errorId.
+
+    Attributes:
+        error_id: numeric errorId from the response.
+        error_code: short string code (e.g. "ERROR_KEY_DOES_NOT_EXIST").
+        error_description: human-readable explanation.
+        recommended_task_type: set when the API hints the caller picked
+            the wrong task type for the sitekey.
+        raw: full decoded JSON body, for debugging.
+    """
+
+    def __init__(
+        self,
+        error_id: int,
+        error_code: str | None,
+        error_description: str | None,
+        recommended_task_type: str | None = None,
+        raw: dict[str, Any] | None = None,
+    ) -> None:
+        self.error_id = error_id
+        self.error_code = error_code
+        self.error_description = error_description
+        self.recommended_task_type = recommended_task_type
+        self.raw = raw or {}
+        msg = f"[{error_code or error_id}] {error_description or 'API error'}"
+        if recommended_task_type:
+            msg += f" (hint: try {recommended_task_type})"
+        super().__init__(msg)
+
+
+class TaskFailedError(CapzyError):
+    """getTaskResult returned status='failed'."""
+
+    def __init__(self, task_id: str, error_code: str | None, error_description: str | None) -> None:
+        self.task_id = task_id
+        self.error_code = error_code
+        self.error_description = error_description
+        super().__init__(
+            f"Task {task_id} failed: [{error_code or '?'}] {error_description or 'no description'}"
+        )
+
+
+class TaskTimeoutError(CapzyError):
+    """The task did not return a solution before the polling deadline."""
+
+    def __init__(self, task_id: str, waited: float) -> None:
+        self.task_id = task_id
+        self.waited = waited
+        super().__init__(f"Task {task_id} did not finish within {waited:.0f}s")

capzy-0.0.1.dist-info/METADATA

@@ -0,0 +1,444 @@
+Metadata-Version: 2.4
+Name: capzy
+Version: 0.0.1
+Summary: Official Python SDK for the Capzy captcha-solving API
+Project-URL: Homepage, https://capzy.ai
+Project-URL: Documentation, https://capzy.ai/docs
+Project-URL: Source, https://github.com/capzy/capzy-pip
+Project-URL: Issues, https://github.com/capzy/capzy-pip/issues
+Author-email: Capzy <support@capzy.ai>
+License: MIT
+License-File: LICENSE
+Keywords: aws-waf,captcha,captcha-solver,capzy,cloudflare,datadome,funcaptcha,geetest,recaptcha,turnstile
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: responses>=0.24; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<img src="https://capzy.ai/capzy-logo.svg" alt="Capzy" width="220" />
+
+# `capzy` — official Python SDK
+
+**Solve every major captcha with a single line of Python.**
+
+[![PyPI version](https://img.shields.io/pypi/v/capzy.svg?color=%23ff5d2a)](https://pypi.org/project/capzy/)
+[![Python](https://img.shields.io/pypi/pyversions/capzy.svg?color=%23ff5d2a)](https://pypi.org/project/capzy/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-%23ff5d2a.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-capzy.ai-%23ff5d2a)](https://capzy.ai/docs)
+[![Status](https://img.shields.io/badge/uptime-99.9%25-%2322c55e)](https://capzy.ai)
+
+[Website](https://capzy.ai) · [Dashboard](https://capzy.ai/dashboard) · [Docs](https://capzy.ai/docs) · [Pricing](https://capzy.ai/pricing) · [Get free credits](https://capzy.ai/auth/register)
+
+</div>
+
+---
+
+## Why Capzy
+
+> Built by people who were tired of paying half a cent to get back `errorCode: ERROR_NO_AVAILABLE_WORKERS`.
+
+- ⚡️ **Fast.** Median solve <5s for Turnstile / reCAPTCHA v2 / hCaptcha.
+- 💸 **Cheap.** Token-bound captchas start at **$0.40 per 1,000 solves**.
+- 🧠 **Solves what others don't.** Native support for **Temu**, **Shopee** (slider + curve), **Binance bCAPTCHA2**, **CaptchaFox**, **MTCaptcha**, **Lemin**, **ALTCHA**, **Yidun**, **Capy** — not just the obvious ones. *(hCaptcha is in active development and not currently sold; status: see [roadmap](#roadmap).)*
+- 🧩 **Drop-in compatible.** Uses the same `createTask` / `getTaskResult` shape your existing scripts already speak. Migration is a one-line `base_url` change.
+- 🆓 **Free credits on sign-up.** Every new account gets **$0.10** in real credits to test in production. No card required.
+- 🔓 **No retainer, no minimum.** Pay-as-you-go. Top up when you want.
+- 📊 **Real dashboard.** Per-key analytics, score quality charts for v3, full payment audit log.
+
+> [**Create a free account →**](https://capzy.ai/auth/register)
+> Get **$0.10 in free credits** the moment you sign up — enough to verify integration end-to-end on roughly **80 reCAPTCHA v3** or **80 Turnstile** solves before you pay a cent.
+
+---
+
+## Install
+
+```bash
+pip install capzy
+```
+
+Requires Python ≥ 3.9 and `requests`. That's it.
+
+> ⚠️ While we wait for our PyPI listing to be approved, you can install straight from the repo:
+>
+> ```bash
+> pip install "git+https://github.com/capzy/capzy-pip.git"
+> ```
+
+---
+
+## 60-second quickstart
+
+```python
+from capzy import CapzyClient
+
+capzy = CapzyClient("capzy_xxxxxxxxxxxxxxxxxxxxxxxx")   # from capzy.ai/dashboard
+
+solution = capzy.solve(
+    type="AntiTurnstileTaskProxyLess",
+    website_url="https://example.com/login",
+    website_key="0x4AAAAAAA...",
+)
+print(solution["token"])     # paste into the cf-turnstile-response field
+```
+
+That's the whole pattern. `solve()` does `createTask` → polls `getTaskResult` → hands you the solution dict.
+
+Need to route the solve through your own proxy? Switch to the `…Task` (non-`ProxyLess`) type and add the proxy params:
+
+```python
+solution = capzy.solve(
+    type="AntiTurnstileTask",
+    website_url="https://example.com/login",
+    website_key="0x4AAAAAAA...",
+    proxy_type="http",
+    proxy_address="123.45.67.89",
+    proxy_port=8080,
+    proxy_login="user",
+    proxy_password="pass",
+)
+```
+
+Need lower-level control? Use the raw verbs:
+
+```python
+created = capzy.create_task(
+    type="AntiTurnstileTaskProxyLess",
+    website_url="https://example.com/login",
+    website_key="0x4AAAAAAA...",
+)
+task_id = created["taskId"]
+
+# Poll on your own schedule:
+status = capzy.get_task_result(task_id)
+```
+
+> **Param naming.** Pass either `website_url=` / `website_key=` (Python style) or
+> `websiteURL=` / `websiteKey=` (wire style). They're equivalent — the SDK
+> normalises snake_case to the camelCase the API expects.
+
+---
+
+## How it works
+
+```
+┌──────────────┐  createTask   ┌──────────┐    enqueue    ┌──────────┐
+│ your script  │ ────────────▶ │  Capzy   │ ────────────▶ │ solver   │
+│  (capzy SDK) │ ◀──────────── │   API    │ ◀──────────── │  cluster │
+└──────────────┘ getTaskResult └──────────┘   solution    └──────────┘
+                          (polls until "ready")
+```
+
+Submit → poll → done. No webhooks to set up, no SDK runtime required on the solver side, no captive browser to manage.
+
+---
+
+## Supported captchas
+
+Every captcha below is supported as a **proxyless** task (we handle the upstream routing) and a **proxy** task (you supply the upstream IP). All prices are USD per solve.
+
+### Token-based — the workhorses
+
+| Captcha | Task type | Price | Notes |
+|---|---|---|---|
+| Cloudflare Turnstile | `AntiTurnstileTaskProxyLess` | **$0.0012** | Including invisible variant |
+| Cloudflare Challenge | `AntiCloudflareTask` | $0.005 | Full JS-challenge page |
+| reCAPTCHA v2 | `ReCaptchaV2TaskProxyLess` | **$0.002** | Checkbox + invisible |
+| reCAPTCHA v2 Enterprise | `ReCaptchaV2EnterpriseTaskProxyLess` | $0.004 | |
+| reCAPTCHA v3 | `ReCaptchaV3TaskProxyLess` | **$0.0015** | Action + min-score |
+| reCAPTCHA v3 Enterprise | `ReCaptchaV3EnterpriseTaskProxyLess` | $0.005 | |
+| FunCaptcha (Arkose) | `FunCaptchaTaskProxyLess` | $0.004 | Including Roblox flow |
+| GeeTest v4 | `GeeTestTaskProxyLess` | **$0.003** | captchaId-based |
+| GeeTest v3 | `GeeTestV3TaskProxyLess` | $0.0035 | gt + challenge |
+| CaptchaFox | `CaptchaFoxTaskProxyLess` | **$0.0012** | |
+| MTCaptcha | `MtCaptchaTaskProxyLess` | $0.002 | |
+| Friendly Captcha | `FriendlyCaptchaTaskProxyLess` | $0.002 | |
+| ALTCHA | `AltchaTaskProxyLess` | $0.001 | Pure proof-of-work |
+| Lemin | `LeminTaskProxyLess` | $0.0015 | |
+| Capy Puzzle | `CapyTaskProxyLess` | $0.002 | |
+| NetEase Yidun | `YidunSliderTaskProxyLess` | $0.003 | |
+| Yandex SmartCaptcha | `YandexSmartCaptchaTaskProxyLess` | $0.025 | |
+| Binance bCAPTCHA2 | `BinanceCaptchaTask` | $0.003 | |
+| Tencent | `TencentTaskProxyLess` | $0.002 | |
+| Shopee Slider | `ShopeeSliderTaskProxyLess` | $0.002 | |
+| Shopee Curve Slider | `ShopeeCurveTaskProxyLess` | $0.003 | |
+| Temu | `TemuCaptchaTaskProxyLess` | $0.002 | |
+| Alibaba | `AntiAlibabaCaptchaTaskProxyLess` | $0.003 | |
+
+### Anti-bot platforms
+
+| Platform | Task type | Price | Notes |
+|---|---|---|---|
+| AWS WAF (full challenge) | `AntiAwsWafTaskProxyLess` | $0.012 | |
+| AWS WAF (image classify) | `AwsWafClassification` | **$0.0008** | Just the image piece |
+| DataDome Slider | `DataDomeSliderTask` | $0.04 | Proxy required |
+| PerimeterX | `AntiPerimeterXTaskProxyLess` | $0.04 | |
+| Imperva Incapsula | `AntiImpervaTaskProxyLess` | $0.04 | |
+| Akamai Bot Manager | `AntiAkamaiBMPTaskProxyLess` | $0.05 | Mobile (BMP) |
+| Kasada | `KasadaCaptchaTaskProxyLess` | $0.005 | |
+
+### Image-based
+
+| Type | Task type | Price | Use case |
+|---|---|---|---|
+| Image-to-Text | `ImageToTextTask` | **$0.001** | Generic OCR captchas |
+| Math Captcha | `MathCaptchaTask` | $0.001 | "What is 7 + 3?" |
+| Coordinates Click | `CoordinatesTask` | $0.001 | "Click the cat" |
+| Rotate | `RotateTask` | $0.001 | Rotate-to-upright |
+
+Full live pricing at **[capzy.ai/pricing](https://capzy.ai/pricing)** — these tables are scraped from the same source-of-truth.
+
+---
+
+## Examples per service
+
+### Cloudflare Turnstile
+
+```python
+from capzy import CapzyClient
+
+capzy = CapzyClient("capzy_xxx")
+sol = capzy.solve(
+    type="AntiTurnstileTaskProxyLess",
+    website_url="https://example.com",
+    website_key="0x4AAAAAAA...",
+    action="login",      # optional — must match data-action
+    cdata="user-123",    # optional — server-issued cdata
+)
+print(sol["token"])
+```
+
+### reCAPTCHA v2
+
+```python
+from capzy import CapzyClient
+
+capzy = CapzyClient("capzy_xxx")
+sol = capzy.solve(
+    type="ReCaptchaV2TaskProxyLess",
+    website_url="https://example.com",
+    website_key="6Lc_aCMTAAAAAB...",
+    is_invisible=False,
+)
+print(sol["gRecaptchaResponse"])
+```
+
+### reCAPTCHA v3 (score-based)
+
+```python
+from capzy import CapzyClient
+
+capzy = CapzyClient("capzy_xxx")
+created = capzy.create_task(
+    type="ReCaptchaV3TaskProxyLess",
+    website_url="https://example.com",
+    website_key="6Lc_aCMTAAAAAB...",
+    page_action="checkout",
+    min_score=0.7,
+)
+task_id = created["taskId"]
+
+# After you call Google siteverify with your secret, report the score back —
+# it lights up your v3 quality dashboard and helps us auto-route your traffic.
+capzy.report_score(task_id, score=0.9, action="checkout", hostname="example.com")
+```
+
+### GeeTest v4
+
+```python
+from capzy import CapzyClient
+
+capzy = CapzyClient("capzy_xxx")
+sol = capzy.solve(
+    type="GeeTestV4TaskProxyLess",
+    website_url="https://example.com",
+    captcha_id="abc123...",
+)
+# sol contains captcha_id, lot_number, pass_token, gen_time, captcha_output
+```
+
+### Image-to-Text (sync solve — no polling)
+
+```python
+import base64
+from capzy import CapzyClient
+
+capzy = CapzyClient("capzy_xxx")
+with open("captcha.png", "rb") as f:
+    body = base64.b64encode(f.read()).decode()
+
+sol = capzy.solve(type="ImageToTextTask", body=body, case="lower")
+print(sol["text"])
+```
+
+More copy-pasteable runners in [`examples/`](./examples).
+
+---
+
+## Free credits & getting an API key
+
+1. Create an account at **[capzy.ai/auth/register](https://capzy.ai/auth/register)**.
+2. We post a **$0.10 welcome bonus** as a real credit transaction on your dashboard. (Audit it like any other payment.)
+3. Generate an API key on **[capzy.ai/dashboard](https://capzy.ai/dashboard)** and drop it into `CapzyClient("capzy_…")`.
+
+The $0.10 is plenty to verify end-to-end:
+
+| Captcha | Solves you can run on $0.10 |
+|---|---|
+| reCAPTCHA v3 | ~66 |
+| Turnstile | ~83 |
+| reCAPTCHA v2 | ~50 |
+| Image-to-Text | ~100 |
+| GeeTest v4 | ~33 |
+
+When you run out, top up with **Stripe** (card / Apple Pay / Google Pay) or **MixPay** (USDT / BTC / 30+ coins). No subscription, no minimum.
+
+---
+
+## Handling errors
+
+```python
+from capzy import CapzyClient, ApiError, TaskFailedError, TaskTimeoutError
+
+capzy = CapzyClient("capzy_xxx")
+try:
+    sol = capzy.solve(
+        type="AntiTurnstileTaskProxyLess",
+        website_url="https://example.com",
+        website_key="0x4AAAAAAA...",
+    )
+except ApiError as e:
+    # createTask was rejected — bad key, wrong task type, insufficient funds, etc.
+    print("API rejected the task:", e.error_code, e.error_description)
+    if e.recommended_task_type:
+        print("Hint — submit as:", e.recommended_task_type)
+except TaskFailedError as e:
+    # Task ran but couldn't be solved. Refunded automatically.
+    print("Solver failed:", e.error_code, e.error_description)
+except TaskTimeoutError as e:
+    # We didn't get an answer within max_wait. Refunded automatically.
+    print(f"No answer after {e.waited:.0f}s")
+```
+
+**You are never charged for failed or timed-out tasks.** Refunds post as real credit transactions, visible in your dashboard.
+
+---
+
+## Configuration
+
+```python
+capzy = CapzyClient(
+    api_key="capzy_xxx",
+    base_url="https://api.capzy.ai",   # override for on-prem / staging
+    timeout=30.0,                       # per HTTP-request timeout
+)
+
+# Tune the polling behaviour per .solve() call:
+capzy.solve(type="AntiTurnstileTaskProxyLess", website_url=..., website_key=...,
+            poll_interval=1.0, max_wait=90.0)
+```
+
+Need a proxy on the SDK's own egress, retries, or custom TLS? Pass your own `requests.Session`:
+
+```python
+import requests
+from capzy import CapzyClient
+
+session = requests.Session()
+session.proxies = {"https": "http://user:pass@proxy.example:8080"}
+capzy = CapzyClient("capzy_xxx", session=session)
+```
+
+---
+
+## API reference
+
+`CapzyClient` is a thin wrapper around the Capzy HTTP API:
+
+| Method | Endpoint | Returns |
+|---|---|---|
+| `capzy.solve(type=..., **params)` | `POST /createTask` + polls `POST /getTaskResult` | the `solution` dict |
+| `capzy.create_task(type=..., **params)` | `POST /createTask` | `{taskId, status?, solution?, timeout?}` |
+| `capzy.get_task_result(task_id)` | `POST /getTaskResult` | `{status, solution?, cost?, ip?, …}` |
+| `capzy.report_score(task_id, score, action=None, hostname=None)` | `POST /reportScore` | `None` |
+| `capzy.get_balance()` | `POST /getBalance` | `float` USD |
+
+All task parameters travel as kwargs. Snake_case (`website_url`, `proxy_address`, `min_score`) and camelCase (`websiteURL`, `proxyAddress`, `minScore`) are equivalent — the SDK normalises to the wire format.
+
+---
+
+## FAQ
+
+**Do you need to supply a proxy?**
+No — every `*ProxyLess` task type runs against our own network. Bring your own only when the target binds the token to your egress IP (some anti-bot platforms do).
+
+**Do you support async?**
+Not in v0.0.1. The sync client is intentionally tiny — pair it with a thread pool, `anyio.to_thread`, or `asyncio.to_thread` if you need fan-out today. A native `AsyncCapzyClient` is on the roadmap.
+
+**What happens if a task fails?**
+The credit is automatically refunded as a `refund` transaction. The SDK raises `TaskFailedError` so you can retry with a different task type or proxy.
+
+**Can I run this in a long-running service?**
+Yes. Re-use one `CapzyClient` across threads — the underlying `requests.Session` is thread-safe for our usage pattern.
+
+**Where do I find my API key?**
+[capzy.ai/dashboard](https://capzy.ai/dashboard) → API keys → New key.
+
+**Do you have rate limits?**
+Per-key concurrency limits exist (visible on your dashboard). When you hit them, `createTask` returns `ERROR_RATE_LIMIT` and the SDK raises `ApiError(error_code="ERROR_RATE_LIMIT")` so you can back off.
+
+**Where do solutions need to be submitted?**
+- Turnstile → `cf-turnstile-response` form field
+- reCAPTCHA v2 / Enterprise → `g-recaptcha-response`
+- Others → service-specific; see the per-service guides at [capzy.ai/docs](https://capzy.ai/docs)
+
+---
+
+## Roadmap
+
+Captchas not yet on the price list but actively being worked on:
+
+- **hCaptcha** (incl. Enterprise) — local CV pipeline in late-stage testing; SDK task types (`HCaptchaTaskProxyLess`, etc.) already accepted so your code is forward-compatible.
+- **Native `AsyncCapzyClient`** — `asyncio`-native client, same API surface.
+- **Streaming `solveMany()`** — fan out N tasks, yield as they finish.
+
+Want something prioritised? Open a [GitHub issue](https://github.com/capzy/capzy-pip/issues) or email **support@capzy.ai**.
+
+---
+
+## Links
+
+- 🌐 **Website:** https://capzy.ai
+- 📚 **Documentation:** https://capzy.ai/docs
+- 💵 **Pricing:** https://capzy.ai/pricing
+- 🔑 **Dashboard / API keys:** https://capzy.ai/dashboard
+- 🆓 **Free credits on sign-up:** https://capzy.ai/auth/register
+- 📜 **Changelog:** [CHANGELOG.md](CHANGELOG.md)
+- 🐛 **Issues:** https://github.com/capzy/capzy-pip/issues
+- 💬 **Support:** support@capzy.ai
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE). Use it in proprietary software, redistribute it, fork it. Just don't blame us if your bot finds love.
+
+<div align="center">
+<sub>Built with care by the Capzy team — <a href="https://capzy.ai">capzy.ai</a></sub>
+</div>

capzy-0.0.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+capzy/__init__.py,sha256=yzxYssWh4htlPe4VENqooceMn7_pgS2f3inxzMgqwM8,763
+capzy/_version.py,sha256=sXLh7g3KC4QCFxcZGBTpG2scR7hmmBsMjq6LqRptkRg,22
+capzy/client.py,sha256=I8DLIHttAhoGDcgkzG0l-rgJ0NKJmpxwQLk5ViiOhpg,7857
+capzy/exceptions.py,sha256=LXcGltxLxZI_yUt19lI0VU11gB_FAPahewLVpg9c13I,2047
+capzy-0.0.1.dist-info/METADATA,sha256=hyFFK-jXENicO39t6k3PtiijSCtDX7w5KR7aBGUngZA,16670
+capzy-0.0.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+capzy-0.0.1.dist-info/licenses/LICENSE,sha256=GQcN_EQWmsYjtb7l_HCKJaTusmtaPe7i3KAr3P7lnLw,1062
+capzy-0.0.1.dist-info/RECORD,,

capzy-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

capzy-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Capzy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.