Metadata-Version: 2.5
Name: scarnox
Version: 0.1.0
Summary: Official Python client for the Scarnox captcha-solving API: one call, one token, pay only for successful solves.
Project-URL: Homepage, https://solver.scarnox.com
Project-URL: Documentation, https://solver.scarnox.com/docs
Project-URL: Pricing, https://solver.scarnox.com/pricing
License-Expression: MIT
License-File: LICENSE
Keywords: captcha,captcha-api,captcha-solver,playwright,selenium,testing,web-automation
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: requests>=2.25
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Description-Content-Type: text/markdown

# scarnox-python

Official Python client for the [Scarnox](https://solver.scarnox.com) captcha-solving API.

One call in, one token out. No task ids, no polling loop, and you only pay for captchas that were actually solved.

```python
from scarnox import Scarnox

client = Scarnox()   # reads SCARNOX_KEY from the environment
token = client.solve(site_key="SITEKEY", site_url="https://example.com/signup").token
```

## Why Scarnox

- **Synchronous**: `solve()` returns the token. There is no create-then-poll dance to write or debug.
- **Pay per success**: failed solves are never charged. Proxyless solving is **$0.75 per 1,000** successful solves ([pricing](https://solver.scarnox.com/pricing)).
- **Retries built in**: the client follows the API's retry policy. Busy and timeout errors back off with jitter, an unsolvable board gets one more try, and account errors are raised straight away.
- **No proxy needed**: bring your own proxy only if the target site checks that the token was solved from the same IP that submits it.

## Install

```bash
pip install scarnox
```

Get an API key at [solver.scarnox.com/register](https://solver.scarnox.com/register), then:

```bash
export SCARNOX_KEY=scarnox_XXXXXXXXXXXXXXXXXXXX
```

## Usage

```python
from scarnox import Scarnox, ScarnoxError

client = Scarnox()

try:
    s = client.solve(
        site_key="SITEKEY",                    # the page's data-sitekey attribute
        site_url="https://example.com/signup", # the page the captcha is on
        # proxy="http://user:pass@host:port",  # optional: solve through your own IP
        # invisible=True,                      # optional: invisible widget (no checkbox)
    )
    print(s.token, s.cost, s.balance)
except ScarnoxError as e:
    print(e.code, e.description)               # e.g. ERROR_INSUFFICIENT_BALANCE
```

Submit the token right away. Tokens expire within about two minutes. Put it in the page's `h-captcha-response` field (and `g-recaptcha-response` if present), or pass it to the widget's JavaScript callback.

### Playwright

[`examples/playwright_example.py`](examples/playwright_example.py) opens a page, reads its sitekey, solves it, fills the response fields and submits the form, in about 30 lines.

### Balance

```python
client.balance()   # 9.994 (USD)
```

Every successful solve also returns `balance`, so most integrations never call this.

## Errors

| `e.code` | what to do |
|---|---|
| `ERROR_NO_SLOT_AVAILABLE`, `ERROR_CAPTCHA_TIMEOUT`, `ERROR_INTERNAL`, `ERROR_TOO_MANY_REQUESTS` | retried for you with backoff |
| `ERROR_CAPTCHA_UNSOLVABLE` | retried once for you |
| `ERROR_INSUFFICIENT_BALANCE` | top up at [solver.scarnox.com](https://solver.scarnox.com) |
| `ERROR_KEY_INVALID` | check `SCARNOX_KEY` |
| `ERROR_PROXY_REQUIRED`, `ERROR_PROXY_FAILED` | pass a working `proxy=` |

Full list: [API docs](https://solver.scarnox.com/docs).

## Links

- Docs: https://solver.scarnox.com/docs
- OpenAPI spec: https://solver.scarnox.com/openapi.json
- Guides: [Python](https://solver.scarnox.com/p/solve-captcha-with-python) · [Playwright & Puppeteer](https://solver.scarnox.com/p/solve-captcha-playwright-puppeteer) · [Error handling](https://solver.scarnox.com/p/captcha-solver-error-handling)

## License

MIT
