IRCaptcha REST API

Authentication

Bearer token enforced at nginx on the public domain. Localhost has no auth.

# Header on every protected call
Authorization: Bearer <SOLVER_TOKEN>

# Token lives on the server (chmod 600), not in this page:
# /root/projects/captcha-solver/.solver-token.env

Dashboard stores the token in localStorage on your browser only. Never commit or paste the raw token into chat logs.

Endpoints

All JSON. Content-Type for POST: application/json.

POST /solve — body fields

Required fields depend on type. SSRF guard rejects private/loopback URLs unless SOLVER_ALLOW_PRIVATE=1.

Arkose: surl / max_waves are not request fields (older docs were wrong). Service URL auto-detects from gfct; waves capped internally at 10. Multi-wave solves often need timeout_s 90–120.

Captcha types

Pass as type on POST /solve.

Honest matrix: reCAPTCHA v2 image is still failing on the free path. Arkose ONNX pack is production-ready for classify (23/24 variants from funcaptchamodel.unix.do); full token harvest needs a live target that fires /fc/gfct/ — public demos usually do not. Missing model: threed_rollball_animal.onnx.

Response contract

Two rules cover every response. Never mix them.

{
  "type": "turnstile",
  "solved": true,
  "token": "…",
  "method": "route",
  "elapsed": 4.1
}

{
  "detail": "url is required"
}

cURL examples

Replace $TOKEN. Do not hardcode secrets in scripts that get committed.

# Health (public)
curl -sS https://ircaptcha.isrealllairdrop.net/health

# Status (Bearer)
curl -sS https://ircaptcha.isrealllairdrop.net/status \
  -H "Authorization: Bearer $TOKEN"

# Logs (last 20)
curl -sS "https://ircaptcha.isrealllairdrop.net/logs?lines=20" \
  -H "Authorization: Bearer $TOKEN"

# Turnstile
curl -sS -X POST https://ircaptcha.isrealllairdrop.net/solve \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "turnstile",
    "sitekey": "0x4AAAAAAA…",
    "url": "https://target.com"
  }'

# reCAPTCHA v3 Enterprise
curl -sS -X POST https://ircaptcha.isrealllairdrop.net/solve \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "recaptcha",
    "version": "v3",
    "enterprise": true,
    "sitekey": "6Lc…",
    "url": "https://target.com",
    "action": "login"
  }'

# Cloudflare clearance (IP-bound — pass proxy)
curl -sS -X POST https://ircaptcha.isrealllairdrop.net/solve \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "cloudflare",
    "url": "https://protected.example.com",
    "proxy": "http://user:pass@host:port",
    "timeout_s": 60
  }'

# Arkose FunCaptcha — needs real page that fires /fc/gfct/ (placeholder will fail honestly)
curl -sS -X POST https://ircaptcha.isrealllairdrop.net/solve \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "arkose",
    "public_key": "A0DE7B75-1138-44F2-B132-ED188CEB66F3",
    "url": "https://login.example.com/login",
    "timeout_s": 120
  }'

# Local (no Bearer needed on :8877)
curl -sS -X POST http://127.0.0.1:8877/solve \
  -H "Content-Type: application/json" \
  -d '{"type":"turnstile","sitekey":"0x4AAAAAAA…","url":"https://target.com"}'

Errors

Operator notes

• Cookie solvers (cloudflare, awswaf, datadome, perimeterx, akamai): replay from the same proxy IP + matching UA/TLS when possible.
• Success signal: always read top-level solved — do not branch only on token (cloudflare uses cf_clearance).
• Interactive docs: open /docs, click Authorize, paste Bearer, then Try it out. Operator HTML: /api-docs.
• Dashboard: / → /ui stores token in localStorage and calls the same REST endpoints.
• Arkose: models from funcaptchamodel.unix.do (23/24 loadable). No public full-E2E demo. See arkose/README.md.
• Scope: solver harvests tokens/cookies only — account creation / form recon is the caller's job.