DeathByCaptcha

Introduction

DeathByCaptcha offers APIs of two types — HTTP and socket-based, with the latter being recommended for having faster responses and overall better performance. Switching between different APIs is usually as easy as changing the client class and/or package name, the interface stays the same.

When using the socket API, please make sure that outgoing TCP traffic to api.dbcapi.me to the ports range 8123–8130 is not blocked on your side.

How to Use DBC API Clients

Thread-safety notes

PHP itself is not multithreaded so the clients are not thread-safe.

Common Clients' Interface

All clients have to be instantiated with two string arguments: your DeathByCaptcha account's username and password.

All clients provides a few methods to handle your CAPTCHAs and your DBC account. Below you will find those methods' short summary and signatures in pseudo-code. Check the example scripts and the clients' source code for more details.

Upload()

Uploads a CAPTCHA to the DBC service for solving, returns uploaded CAPTCHA details on success, NULL otherwise. Here are the signatures in pseudo-code:

array DeathByCaptcha_Client->upload(resource $imageFile)

array DeathByCaptcha_Client->upload(string $imageFileName)

GetCaptcha()

Fetches uploaded CAPTCHA details, returns NULL on failures.

array DeathByCaptcha_Client->get_captcha(int $captchaId)

Report()

Reports incorrectly solved CAPTCHA for refund, returns true on success, false otherwise.

Please make sure the CAPTCHA you're reporting was in fact incorrectly solved, do not just report them thoughtlessly, or else you'll be flagged as abuser and banned.

bool DeathByCaptcha.Client->report(int $captchaId)

Decode()

This method uploads a CAPTCHA, then polls for its status until it's solved or times out; returns solved CAPTCHA details on success, NULL otherwise.

array DeathByCaptcha.Client->decode(resource $imageFile, int $timeout)

array DeathByCaptcha.Client->decode(string $imageFileName, int $timeout)

GetBalance()

Fetches your current DBC credit balance (in US cents).

float DeathByCaptcha.Client->get_balance()

CAPTCHA objects/details hashes

Use simple hashes (dictionaries, associative arrays etc.) to store CAPTCHA details, keeping numeric IDs under "captcha" key, CAPTCHA text under "text" key, and the correctness flag under "is_correct" key.

Example

Below you can find a DBC API client usage examples.

require_once "deathbycaptcha.php";

/* Put your DBC account username and password here.
   Use DeathByCaptcha_HttpClient for HTTP API. */
$client = new DeathByCaptcha_SocketClient($username, $password);
try {
    $balance = $client->get_balance();

    /* Put your CAPTCHA file name or opened file handler, and optional
       solving timeout (in seconds) here: */
    $captcha = $client->decode($captcha_file_name, $timeout);
    if ($captcha) {
        /* The CAPTCHA was solved; captcha["captcha"] item holds its
           numeric ID, and captcha["text"] item its text. */
        echo "CAPTCHA {$captcha["captcha"]} solved: {$captcha["text"]}";

        if (/* check if the CAPTCHA was incorrectly solved */) {
            $client->report($captcha["captcha"]);
        }
    }
} catch (DeathByCaptcha_AccessDeniedException) {
    /* Access to DBC API denied, check your credentials and/or balance */
}

New Recaptcha API support

What's "new reCAPTCHA/noCAPTCHA"?

They're new reCAPTCHA challenges that typically require the user to identify and click on certain images. They're not to be confused with traditional word/number reCAPTCHAs (those have no images).

For your convinience, we implemented support for New Recaptcha API. If your software works with it, and supports minimal configuration, you should be able to decode captchas using New Recaptcha API in no time.

We provide two different types of New Recaptcha API:

Coordinates API FAQ:

What's the Coordinates API URL?
To use the Coordinates API you will have to send a HTTP POST Request to http://api.dbcapi.me/api/captcha

What are the POST parameters for the Coordinates API?

What's the response from the Coordinates API?

Image Group API FAQ:

What's the Image Group API URL?
To use the Image Group API you will have to send a HTTP POST Request to http://api.dbcapi.me/api/captcha

What are the POST parameters for the Image Group API?

What's the response from the Image Group API?

New Recaptcha by Token API support (reCAPTCHA v2 and reCAPTCHA v3)

What's "new reCAPTCHA by Token"?

They're new reCAPTCHA challenges that typically require the user to identify and click on certain images. They're not to be confused with traditional word/number reCAPTCHAs (those have no images).

For your convenience, we implemented support for New Recaptcha by Token API. If your software works with it, and supports minimal configuration, you should be able to decode captchas using Death By Captcha in no time.

reCAPTCHA v2 API FAQ:

What's the Token Image API URL?
To use the Token Image API you will have to send a HTTP POST Request to http://api.dbcapi.me/api/captcha

What are the POST parameters for the Token image API?

The proxy parameter is optional, but we strongly recommend to use one to prevent token rejection by the provided page due to inconsistencies between the IP that solved the captcha (ours if no proxy is provided) and the IP that submitted the token for verification (yours).

Note: If proxy is provided, proxytype is a required parameter.

Full example of token_params:

{
  "proxy": "http://127.0.0.1:3128",
  "proxytype": "HTTP",
  "googlekey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
  "pageurl": "http://test.com/path_with_recaptcha"
}

Example of token_params for google search captchas:

{
  "googlekey": "6Le-wvkSA...",
  "pageurl": "...",
  "data-s": "IUdfh4rh0sd..."
}

What's the response from the Token image API?
The token image API response has the same structure as regular captchas' response. Refer to Polling for uploaded CAPTCHA status for details about the response. The token will come in the text key of the response. It's valid for one use and has a 2 minute lifespan. It will be a string like the following:

"03AOPBWq_RPO2vLzyk0h8gH0cA2X4v3tpYCPZR6Y4yxKy1s3Eo7CHZRQntxrdsaD2H0e6S3547xi1FlqJB4rob46J0-wfZMj6YpyVa0WGCfpWzBWcLn7tO_EYsvEC_3kfLNINWa5LnKrnJTDXTOz-JuCKvEXx0EQqzb0OU4z2np4uyu79lc_NdvL0IRFc3Cslu6UFV04CIfqXJBWCE5MY0Ag918r14b43ZdpwHSaVVrUqzCQMCybcGq0yxLQf9eSexFiAWmcWLI5nVNA81meTXhQlyCn5bbbI2IMSEErDqceZjf1mX3M67BhIb4"

What's "new reCAPTCHA v3"?

This API is quite similar to the tokens(reCAPTCHA v2) API. Only 2 new parameters were added, one for the action and other for the minimal score(min-score)

reCAPTCHA v3 returns a score from each user, that evaluate if user is a bot or human. Then the website uses the score value that could range from 0 to 1 to decide if will accept or not the requests. Lower scores near to 0 are identified as bot.

The action parameter at reCAPTCHA v3 is an additional data used to separate different captcha validations like for example login, register, sales, etc.

reCAPTCHA v3 API FAQ:

What is action in reCAPTCHA v3?
Is a new parameter that allows processing user actions on the website differently.

To find this we need to inspect the javascript code of the website looking for call of grecaptcha.execute function. Example: 

grecaptcha.execute('6Lc2fhwTAAAAAGatXTzFYfvlQMI2T7B6ji8UVV_f', {action: something})

Sometimes it's really hard to find it and we need to look through all javascript files. We may also try to find the value of action parameter inside ___grecaptcha_cfg configuration object. Also we can call grecaptcha.execute and inspect javascript code. The API will use "verify" default value it if we won't provide action in our request.

What is min-score in reCAPTCHA v3 API?
The minimal score needed for the captcha resolution. We recommend using the 0.3 min-score value, scores highers than 0.3 are hard to get.

What are the POST parameters for the reCAPTCHA v3 API?

The proxy parameter is optional, but we strongly recommend to use one to prevent rejection by the provided page due to inconsistencies between the IP that solved the captcha (ours if no proxy is provided) and the IP that submitted the solution for verification (yours).

Note: If proxy is provided, proxytype is a required parameter.

Full example of token_params:

{
  "proxy": "http://127.0.0.1:3128",
  "proxytype": "HTTP",
  "googlekey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
  "pageurl": "http://test.com/path_with_recaptcha",
  "action": "example/action",
  "min_score": 0.3
}

What's the response from reCAPTCHA v3 API?
The response has the same structure as regular captcha. Refer to Polling for uploaded CAPTCHA status for details about the response. The solution will come in the text key of the response. It's valid for one use and has a 1 minute lifespan.

New Funcaptcha

What's "new Funcaptcha"?

They're challenges that typically require the user to align and click on certain images.

For your convenience, we implemented support for Funcaptcha API. If your software works with it, and supports minimal configuration, you should be able to decode Funcaptchas using Death By Captcha in no time.

Funcaptcha API FAQ:

What's the Funcaptcha API URL?
To use the Funcaptcha API you will have to send a HTTP POST Request to http://api.dbcapi.me/api/captcha

What are the POST parameters for the Token image API?

The proxy parameter is optional, but we strongly recommend to use one to prevent token rejection by the provided page due to inconsistencies between the IP that solved the captcha (ours if no proxy is provided) and the IP that submitted the Funcaptcha for verification (yours).

Note: If proxy is provided, proxytype is a required parameter.

Full example of funcaptcha_params:

{
    "proxy": "http://user:password@127.0.0.1:1234",
    "proxytype": "HTTP",
    "publickey": "029EF0D3-41DE-03E1-6971-466539B47725",
    "pageurl": "https://testsite.com/xxx-test"
}

What's the response from the Funcaptcha API?
The Funcaptcha API response has the following structure. It's valid for one use and has a 2 minute lifespan. It will be a string like the following:

"CAPTCHA 1537354005 solved: 10005cc22946667676.7969450405|
r=eu-west-1|metabgclr=transparent|guitextcolor=%23000000|
metaiconclr=%23cccccc|meta=5|lang=en|pk=0"

New Hcaptcha

What's "new Hcaptcha"?

They're challenges that typically require the user to align and click on certain images.

For your convenience, we implemented support for Hcaptcha API. If your software works with it, and supports minimal configuration, you should be able to decode Hcaptchas using Death By Captcha in no time.

Hcaptcha API FAQ:

What's the Hcaptcha API URL?
To use the Hcaptcha API you will have to send a HTTP POST Request to http://api.dbcapi.me/api/captcha

What are the POST parameters for the Token image API?

The proxy parameter is optional, but we strongly recommend to use one to prevent token rejection by the provided page due to inconsistencies between the IP that solved the captcha (ours if no proxy is provided) and the IP that submitted the Hcaptcha for verification (yours).

Note: If proxy is provided, proxytype is a required parameter.

Full example of hcaptcha_params:

{
    "proxy": "http://user:password@127.0.0.1:1234",
    "proxytype": "HTTP",
    "sitekey": "56489210-0c02-58c0-00e5-1763b63dc9d4",
    "pageurl": "https://testsite.com/xxx-test"
}

What's the response from the Hcaptcha API?
The Hcaptcha API response has the following structure. It's valid for one use and has a 2 minute lifespan. It will be a string like the following:

"P0_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwYXNza2V5IjoiSm1LUHhreDdsVElwaWc5cEFuay81cjJ0NE5yVWxrT2lNV0VZQUJ6dmpobkJid29sbFNWKzJiQ0h6cmZ4TGRLU
Ww1NEdxcFN0ZzEzT01id1VROXhqYTVDa2d2NjFXSG9YOFNzS2twZU45M0gwRG1RTlQ0Vnlhdnp2T2QxcThFSGlNcVJ1VTZXVEZOMXdGYkdleVpQbllXZ1NRL2FXcjlhUkQyZHNTK2NnL0V
1VGJUam96RWtjMHR3a2tJTk9GcTVuMUdVVXh6b1k0NGpsUHJPaTAyWWRSZ2p3TVFrZXFGQVJFUEFJY3NDbjJEc2Flbzk0V0YzbmtBVWxQd3QxNTdHNUk1ZjFLbnN0S0FLRzVWNy8yUmY4d
GdxaTRJZVAwT3o0S200bmlqVC92SHkxdEpQT3Y1N2tMUkVDdzNDU1VMOTc3NXZvdEpuUVBkeUdZVmNxOFptQUZaRTlzQXB2QjllSDE3MTRXcFlhQW1aS1ZZc1B0OHN1Rk0vY1hYVjJabHJ
qY1pUeHFONmRPNUFwK0krNVQrZlRQaHBvS0VQeUtWWUI3Rmpkc3BQNWlFeDlIb3ZGWkJqOUpQVHBUa2JNNHJjM0hMVm4zbC9HTmwwRkM5VUM0SzAyVnhjekZnZ2ZlbmprZDdpU3N6dVMva
Hp0OFY3elFxYW42cTlGMEpmL01wT3J2cHZDQU9rSnAyb2hiQmx0QlhLSzBGZUt1U2VjQXZnQ2N5Ty9PdWRuWWdvZXFLTTAvVEdnUjByMk10bVZpRlJFZnJ6cVFGNzlNcGE0NkdpMk ..."