Skip to content
24 changes: 16 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,8 @@ CapmonsterClient(api_key, timeout=30.0, max_retries=120, retry_delay=2.0)
| `create_task(task)` | Create a task, returns `task_id` |
| `join_task_result(task_id)` | Poll until result is ready |
| `get_task_result(task_id)` | Single poll (no waiting) |
| `solve_detailed(task)` | Like `solve`, but returns a `TaskResult` with `solution` and `cost` |
| `join_task_result_detailed(task_id)` / `get_task_result_detailed(task_id)` | Same, for polling |
| `get_balance()` | Get account balance |
| `get_user_agent()` | Get current valid User-Agent string |
| `report_incorrect_image(task_id)` | Report bad image captcha solution |
Expand All @@ -106,22 +108,22 @@ Both sync and async context managers are supported for proper connection cleanup
| reCAPTCHA v2 Enterprise | `RecaptchaV2EnterpriseTask` | Optional |
| reCAPTCHA v3 | `RecaptchaV3Task` | No |
| reCAPTCHA v3 Enterprise | `RecaptchaV3EnterpriseTask` | No |
| reCAPTCHA Click | `RecaptchaClickTask` | Optional |
| reCAPTCHA Click | `RecaptchaClickTask` (deprecated, use `ComplexImageRecaptchaTask`) | Optional |

### Cloudflare

| CAPTCHA Type | Class | Proxy |
|---|---|---|
| Turnstile | `TurnstileTask` | No |
| Turnstile Challenge (cf_clearance) | `TurnstileCloudFlareTask` | Required |
| Turnstile Challenge (token / cf_clearance) | `TurnstileCloudFlareTask` | Optional / Required |
| Turnstile Waiting Room | `TurnstileWaitingRoomTask` | Required |

### Image-Based

| CAPTCHA Type | Class | Proxy |
|---|---|---|
| Image-to-Text OCR | `ImageToTextTask` | No |
| Complex Image (reCAPTCHA grid) | `ComplexImageRecaptchaTask` | No |
| Complex Image (reCAPTCHA click/grid) | `ComplexImageRecaptchaTask` | No |
| Complex Image Recognition | `ComplexImageRecognitionTask` | No |

### Behavioral / Interactive
Expand All @@ -130,8 +132,11 @@ Both sync and async context managers are supported for proper connection cleanup
|---|---|---|
| GeeTest v3 | `GeeTestV3Task` | Optional |
| GeeTest v4 | `GeeTestV4Task` | Optional |
| FunCaptcha (Arkose Labs) | `FunCaptchaTask` | Optional |
| Hunt | `HuntTask` | Optional |
| FunCaptcha (Arkose Labs) | `FunCaptchaTask` | Required |
| Hunt | `HuntTask` | Required |
| Alibaba | `AlibabaTask` | Optional |
| Friendly Captcha | `FriendlyTask` | Optional |
| ARCaptcha | `ARCaptchaTask` | No |

### Enterprise Protection

Expand All @@ -147,16 +152,19 @@ Both sync and async context managers are supported for proper connection cleanup
| CAPTCHA Type | Class | Proxy |
|---|---|---|
| Binance | `BinanceTask` | Required |
| Temu | `TemuTask` | No |
| TenDI | `TenDITask` | Required |
| Temu | `TemuTask` (deprecated) | No |
| TenDI | `TenDITask` | Optional |
| FengkongCloud | `FengkongCloudTask` | No |
| HeyTap | `HeyTapTask` | No |
| Proton | `ProtonTask` | Required |

### Other

| CAPTCHA Type | Class | Proxy |
|---|---|---|
| Altcha | `AltchaTask` | No |
| Basilisk | `BasiliskTask` | No |
| Castle | `CastleTask` | No |
| Castle | `CastleTask` (deprecated) | No |
| MTCaptcha | `MTCaptchaTask` | Optional |
| Prosopo | `ProsopoTask` | Optional |
| Yidun | `YidunTask` | Optional |
Expand Down
276 changes: 273 additions & 3 deletions docs/examples.md
Original file line number Diff line number Diff line change
Expand Up @@ -628,7 +628,7 @@ async def main():
websiteURL="https://example.com",
metadata=ImpervaTaskMetadata(
incapsulaScriptUrl="https://example.com/js.inc",
incapsulaCookie="visid_incap_12345=...",
incapsulaCookies="visid_incap_12345=...",
)
)
task_id = await client.create_task_async(task)
Expand All @@ -646,7 +646,7 @@ task_id = client.create_task(ImpervaTask(
websiteURL="https://example.com",
metadata=ImpervaTaskMetadata(
incapsulaScriptUrl="https://example.com/js.inc",
incapsulaCookie="visid_incap_12345=...",
incapsulaCookies="visid_incap_12345=...",
)
))
result = client.get_task_result(task_id)
Expand Down Expand Up @@ -815,6 +815,10 @@ print(result)

## Temu

!!!warning Deprecated
`TemuTask` emits a `DeprecationWarning` and will be removed in 6.0: Temu is no longer in the CapMonster Cloud docs.
!!!

Used to bypass CAPTCHA challenges on Temu using extracted cookies.

+++ Async
Expand Down Expand Up @@ -1023,7 +1027,11 @@ print(result)

---

## Castle [!badge text="NEW" variant="success"]
## Castle

!!!warning Deprecated
`CastleTask` emits a `DeprecationWarning` and will be removed in 6.0: Castle is no longer in the CapMonster Cloud docs.
!!!

Used for solving Castle challenges.

Expand Down Expand Up @@ -1118,3 +1126,265 @@ result = client.get_task_result(task_id)
print(result)
```
+++

---

## Hunt [!badge text="NEW" variant="success"]

Solves Hunt captcha through `widgetUrl` (or `data` with the site's `meta.token`). Proxy is required.

!!!
The old `HuntTask(websiteKey=...)` form is deprecated; it still works but emits a `DeprecationWarning`.
!!!

+++ Async
```python
import asyncio
from capmonster_python import CapmonsterClient, HuntTask, HuntMetadata, ProxyPayload

async def main():
async with CapmonsterClient(api_key="<API_KEY>") as client:
task = HuntTask(
websiteURL="https://example.com/page-with-hunt",
metadata=HuntMetadata(
apiGetLib="https://example.com/hd-api/external/apps/<app-hash>/api.js",
widgetUrl="https://captcha.example.com/widget?hash=<widget-hash>"
),
proxy=ProxyPayload(proxyType="http", proxyAddress="1.2.3.4", proxyPort=8080,
proxyLogin="<login>", proxyPassword="<password>")
)
result = await client.solve_async(task)
print(result)

asyncio.run(main())
```
+++ Sync
```python
from capmonster_python import CapmonsterClient, HuntTask, HuntMetadata, ProxyPayload

with CapmonsterClient(api_key="<API_KEY>") as client:
task = HuntTask(
websiteURL="https://example.com/page-with-hunt",
metadata=HuntMetadata(
apiGetLib="https://example.com/hd-api/external/apps/<app-hash>/api.js",
widgetUrl="https://captcha.example.com/widget?hash=<widget-hash>"
),
proxy=ProxyPayload(proxyType="http", proxyAddress="1.2.3.4", proxyPort=8080,
proxyLogin="<login>", proxyPassword="<password>")
)
result = client.solve(task)
print(result)
```
+++

---

## Alibaba [!badge text="NEW" variant="success"]

Solves Alibaba captcha. Use `punishUrl` instead of `sceneId`/`prefix` for sites that return a `/punish` URL.

+++ Async
```python
import asyncio
from capmonster_python import CapmonsterClient, AlibabaTask, AlibabaMetadata

async def main():
async with CapmonsterClient(api_key="<API_KEY>") as client:
task = AlibabaTask(
websiteURL="https://www.example.com",
metadata=AlibabaMetadata(sceneId="<scene_id>", prefix="<prefix>")
)
result = await client.solve_async(task)
print(result)

asyncio.run(main())
```
+++ Sync
```python
from capmonster_python import CapmonsterClient, AlibabaTask, AlibabaMetadata

with CapmonsterClient(api_key="<API_KEY>") as client:
task = AlibabaTask(
websiteURL="https://www.example.com",
metadata=AlibabaMetadata(sceneId="<scene_id>", prefix="<prefix>")
)
result = client.solve(task)
print(result)
```
+++

---

## Friendly Captcha [!badge text="NEW" variant="success"]

Solves Friendly Captcha V1 and V2.

+++ Async
```python
import asyncio
from capmonster_python import CapmonsterClient, FriendlyTask, FriendlyMetadata

async def main():
async with CapmonsterClient(api_key="<API_KEY>") as client:
task = FriendlyTask(
websiteURL="https://example.com",
websiteKey="<site_key>",
metadata=FriendlyMetadata(apiGetLib="https://cdn.jsdelivr.net/npm/@friendlycaptcha/sdk@X.Y.Z/site.min.js")
)
result = await client.solve_async(task)
print(result)

asyncio.run(main())
```
+++ Sync
```python
from capmonster_python import CapmonsterClient, FriendlyTask, FriendlyMetadata

with CapmonsterClient(api_key="<API_KEY>") as client:
task = FriendlyTask(
websiteURL="https://example.com",
websiteKey="<site_key>",
metadata=FriendlyMetadata(apiGetLib="https://cdn.jsdelivr.net/npm/@friendlycaptcha/sdk@X.Y.Z/site.min.js")
)
result = client.solve(task)
print(result)
```
+++

---

## FengkongCloud [!badge text="NEW" variant="success"]

Solves FengkongCloud captcha. No proxy.

+++ Async
```python
import asyncio
from capmonster_python import CapmonsterClient, FengkongCloudTask, FengkongCloudMetadata

async def main():
async with CapmonsterClient(api_key="<API_KEY>") as client:
task = FengkongCloudTask(
websiteURL="https://example.com",
websiteKey="<site_key>",
metadata=FengkongCloudMetadata(apiJsUrl="https://castatic.fengkongcloud.com/pr/vX.X.X/smcp.min.js")
)
result = await client.solve_async(task)
print(result)

asyncio.run(main())
```
+++ Sync
```python
from capmonster_python import CapmonsterClient, FengkongCloudTask, FengkongCloudMetadata

with CapmonsterClient(api_key="<API_KEY>") as client:
task = FengkongCloudTask(
websiteURL="https://example.com",
websiteKey="<site_key>",
metadata=FengkongCloudMetadata(apiJsUrl="https://castatic.fengkongcloud.com/pr/vX.X.X/smcp.min.js")
)
result = client.solve(task)
print(result)
```
+++

---

## ARCaptcha [!badge text="NEW" variant="success"]

Solves ARCaptcha. No proxy.

+++ Async
```python
import asyncio
from capmonster_python import CapmonsterClient, ARCaptchaTask

async def main():
async with CapmonsterClient(api_key="<API_KEY>") as client:
task = ARCaptchaTask(websiteURL="https://example.com", websiteKey="<site_key>")
result = await client.solve_async(task)
print(result)

asyncio.run(main())
```
+++ Sync
```python
from capmonster_python import CapmonsterClient, ARCaptchaTask

with CapmonsterClient(api_key="<API_KEY>") as client:
task = ARCaptchaTask(websiteURL="https://example.com", websiteKey="<site_key>")
result = client.solve(task)
print(result)
```
+++

---

## HeyTap [!badge text="NEW" variant="success"]

Solves HeyTap captcha. No proxy.

+++ Async
```python
import asyncio
from capmonster_python import CapmonsterClient, HeyTapTask

async def main():
async with CapmonsterClient(api_key="<API_KEY>") as client:
task = HeyTapTask(websiteURL="https://example.com", websiteKey="<site_key>")
result = await client.solve_async(task)
print(result)

asyncio.run(main())
```
+++ Sync
```python
from capmonster_python import CapmonsterClient, HeyTapTask

with CapmonsterClient(api_key="<API_KEY>") as client:
task = HeyTapTask(websiteURL="https://example.com", websiteKey="<site_key>")
result = client.solve(task)
print(result)
```
+++

---

## Proton Captcha [!badge text="NEW" variant="success"]

Solves Proton Captcha. Proxy is required.

+++ Async
```python
import asyncio
from capmonster_python import CapmonsterClient, ProtonTask, ProtonMetadata, ProxyPayload

async def main():
async with CapmonsterClient(api_key="<API_KEY>") as client:
task = ProtonTask(
websiteURL="https://example.com/",
metadata=ProtonMetadata(HumanVerificationToken="<token>", pageAction="login"),
proxy=ProxyPayload(proxyType="http", proxyAddress="1.2.3.4", proxyPort=8080,
proxyLogin="<login>", proxyPassword="<password>")
)
result = await client.solve_async(task)
print(result)

asyncio.run(main())
```
+++ Sync
```python
from capmonster_python import CapmonsterClient, ProtonTask, ProtonMetadata, ProxyPayload

with CapmonsterClient(api_key="<API_KEY>") as client:
task = ProtonTask(
websiteURL="https://example.com/",
metadata=ProtonMetadata(HumanVerificationToken="<token>", pageAction="login"),
proxy=ProxyPayload(proxyType="http", proxyAddress="1.2.3.4", proxyPort=8080,
proxyLogin="<login>", proxyPassword="<password>")
)
result = client.solve(task)
print(result)
```
+++
7 changes: 4 additions & 3 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,10 +42,11 @@ Image-to-Text, and more — with both sync and async support out of the box.
| **reCAPTCHA** | V2, V2 Enterprise, V3, V3 Enterprise [!badge text="NEW" variant="success"] |
| **Turnstile** | Token, CloudFlare (cf_clearance), Waiting Room [!badge text="NEW" variant="success"] |
| **GeeTest** | V3, V4 |
| **Image-Based** | ImageToText, ComplexImageRecaptcha, ComplexImageRecognition |
| **Image-Based** | ImageToText, ComplexImageRecaptcha (reCAPTCHA click), ComplexImageRecognition |
| **Enterprise** | DataDome, Imperva, Amazon WAF [!badge text="NEW" variant="success"] |
| **Platform** | Binance, Temu, TenDI |
| **Other** | Prosopo, Basilisk, FunCaptcha [!badge text="NEW" variant="success"], MTCaptcha [!badge text="NEW" variant="success"], Yidun [!badge text="NEW" variant="success"], Altcha [!badge text="NEW" variant="success"], Castle [!badge text="NEW" variant="success"], TSPD [!badge text="NEW" variant="success"] |
| **Platform** | Binance, TenDI, Alibaba [!badge text="NEW" variant="success"], HeyTap [!badge text="NEW" variant="success"], Proton [!badge text="NEW" variant="success"], FengkongCloud [!badge text="NEW" variant="success"] |
| **Other** | Prosopo, Basilisk, FunCaptcha [!badge text="NEW" variant="success"], MTCaptcha [!badge text="NEW" variant="success"], Yidun [!badge text="NEW" variant="success"], Altcha [!badge text="NEW" variant="success"], TSPD [!badge text="NEW" variant="success"], Hunt, Friendly Captcha [!badge text="NEW" variant="success"], ARCaptcha [!badge text="NEW" variant="success"] |
| **Deprecated** | Temu, Castle, RecaptchaClickTask (removed in 6.0) |

---

Expand Down
Loading
Loading