---
name: captcha-third-party-services
description: Unified captcha workflow for 2Captcha, YesCaptcha, and Anti-Captcha. Use when users need official API-based task submission (`createTask`), polling (`getTaskResult`), balance checks (`getBalance`), provider fallback, or debugging captcha token pipelines for reCAPTCHA/hCaptcha/Turnstile/FunCaptcha and similar challenge types.
---

# Captcha Third Party Services

## Overview

Use official APIs to create captcha tasks, poll completion, and return solve tokens with consistent behavior across providers.

Read `references/official-docs-and-analysis.md` when you need provider-specific details, method URLs, and compatibility notes.

## Inputs To Collect

- Provider: `2captcha`, `yescaptcha`, or `anti-captcha`
- Captcha task type (for example `RecaptchaV2TaskProxyless`, `TurnstileTaskProxyless`, `HCaptchaTaskProxyless`)
- Target metadata: `websiteURL`, `websiteKey` and task-specific fields
- API key (runtime secret, not hardcoded into committed files)

## API Key Handling

Prefer environment variables:

- `CAPTCHA_2CAPTCHA_KEY`
- `CAPTCHA_YESCAPTCHA_KEY`
- `CAPTCHA_ANTI_CAPTCHA_KEY`

Only use direct `--api-key` arguments for one-off tests.

## Unified Workflow

1. Check balance before creating tasks.
2. Build a `task` payload that matches provider-supported task schema.
3. Submit `createTask`.
4. Poll `getTaskResult` every 3-5 seconds until `status=ready` or timeout.
5. Return `solution` token and timing/cost metadata.

## Provider Selection Strategy

- Start with preferred provider from user.
- If provider returns permanent task validation errors, fix payload first.
- If provider returns transient capacity/timeouts, fail over to next provider.
- Keep task type and site parameters identical during failover to isolate provider variance.

Recommended fallback order:

1. `yescaptcha`
2. `2captcha`
3. `anti-captcha`

Adjust order using account balance, measured solve latency, and recent success rate.

## Use The Bundled CLI

Use `scripts/captcha_api_cli.py` for deterministic API calls.

### Balance

```bash
python3 scripts/captcha_api_cli.py balance --provider 2captcha
python3 scripts/captcha_api_cli.py balance --provider yescaptcha
python3 scripts/captcha_api_cli.py balance --provider anti-captcha
```

### Create Task

```bash
python3 scripts/captcha_api_cli.py create-task \
  --provider 2captcha \
  --task-json '{"type":"RecaptchaV2TaskProxyless","websiteURL":"https://example.com","websiteKey":"SITE_KEY"}'
```

### Poll Task Result

```bash
python3 scripts/captcha_api_cli.py get-task-result \
  --provider 2captcha \
  --task-id 123456789
```

### End-To-End Solve (Create + Poll)

```bash
python3 scripts/captcha_api_cli.py solve \
  --provider yescaptcha \
  --task-json '{"type":"TurnstileTaskProxyless","websiteURL":"https://example.com","websiteKey":"SITE_KEY"}' \
  --poll-interval 3 \
  --timeout 180
```

## Raw Curl Patterns

Use these when a user explicitly asks for direct HTTP examples.

### createTask

```bash
curl -sS https://api.<provider-domain>/createTask \
  -H 'Content-Type: application/json' \
  -d '{
    "clientKey":"<API_KEY>",
    "task":{
      "type":"RecaptchaV2TaskProxyless",
      "websiteURL":"https://example.com",
      "websiteKey":"SITE_KEY"
    }
  }'
```

### getTaskResult

```bash
curl -sS https://api.<provider-domain>/getTaskResult \
  -H 'Content-Type: application/json' \
  -d '{
    "clientKey":"<API_KEY>",
    "taskId":123456789
  }'
```

### getBalance

```bash
curl -sS https://api.<provider-domain>/getBalance \
  -H 'Content-Type: application/json' \
  -d '{"clientKey":"<API_KEY>"}'
```

## Troubleshooting

- `errorId != 0`: treat as API-level failure and inspect `errorCode`/`errorDescription`.
- Stuck in `processing`: extend timeout or switch provider.
- Invalid key/site params: validate task type and required fields from official docs.
- Low balance: call `getBalance` and select another provider if needed.

## Compliance

- Use these services only for authorized security testing and legitimate automation.
- Respect target website Terms of Service and applicable laws.