Integrating Custom Solver

Custom Captcha Solver Integration

This document explains how to connect a custom captcha solving service to the bot.

Your solver must expose an HTTP endpoint that accepts captcha solving requests and returns the solved captcha key.

---

1. Endpoint Requirements

Your solver must expose an HTTP POST endpoint.

Example:

POST https://your-solver-domain.com/solve

The platform will send a request to this endpoint whenever a captcha needs to be solved.

Timeout limit:

150 seconds

If your solver does not respond within this time, the request will be treated as failed.

---

2. Request Format

The platform will send a JSON payload.

Headers

Content-Type: application/json

Request Body

{
  "captcha_sitekey": "SITE_KEY_HERE",
  "captcha_rqdata": "RQDATA_VALUE",
  "website_url": "https://example.com"
}

Fields

Field	Type	Required	Description
captcha_sitekey	string	Yes	Captcha sitekey extracted from the target website
captcha_rqdata	string	Optional	rqdata parameter required for some captcha providers (ex: hCaptcha enterprise)
website_url	string	Optional	The URL where the captcha is located

---

3. Expected Response

Your solver must return a JSON response with the captcha solution.

Success Response

HTTP Status:

200 OK

Response Body:

{
  "captcha_key": "SOLVED_CAPTCHA_TOKEN"
}

Field Description

Field	Type	Description
captcha_key	string	The solved captcha token returned by your solver

---

4. Response Requirements

Your endpoint must:

• Return HTTP 200

• Return JSON

• Include the captcha_key field

If any of these conditions are not met, the platform will treat the request as a failure.

---

5. Error Handling

The platform will consider the request failed if:

• The request times out

• HTTP status code is not 200

• Response is not JSON

• captcha_key is missing or empty

Example failure response (optional):

{
  "error": "solver_failed"
}

---

---

6. Request Flow

Bot
   │
   │ POST request
   ▼
Custom Solver Endpoint
   │
   │ Solve captcha
   ▼
Return captcha_key
   │
   ▼
Platform uses captcha_key

---

7. Best Practices

Recommended for reliable integration:

• Average solve time under 60 seconds

• Always return valid JSON

• Handle concurrent requests

• Implement retry logic in your solver

• Log failed captcha attempts

---