skills/captcha-third-party-services/SKILL.md

name, description

name	description
captcha-third-party-services	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

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

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

Poll Task Result

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

End-To-End Solve (Create + Poll)

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

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

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

getBalance

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.