The DeathByCaptcha Perl client is the official library for the DeathByCaptcha captcha solving service, designed for teams that need a reliable recaptcha solver API in automation and scraping pipelines. It provides a simple, well-documented interface for integrating image, audio, and token-based CAPTCHA workflows, and it helps evaluate captcha solving API pricing in real projects by giving a consistent implementation across HTTPS and socket transports. It supports both the HTTPS API (encrypted transport — recommended when security is a priority) and the socket-based API (faster and lower latency, recommended for high-throughput production workloads). Requires Perl 5.20+.

Key features:

• 🧩 Send image, audio and modern token-based CAPTCHA types (reCAPTCHA v2/v3, Turnstile, GeeTest, etc.).
• 🔄 Unified client API across HTTP and socket transports — switching implementations is straightforward.
• 🔐 Built-in support for proxies, timeouts and advanced token parameters for modern CAPTCHA flows.

Quick start example (HTTP):

use FindBin qw($Bin);
use lib "$Bin/";  # Adjust to where DeathByCaptcha/ is in your project

use DeathByCaptcha::HttpClient;
use DeathByCaptcha::Client;

my $client = DeathByCaptcha::HttpClient->new('your_username', 'your_password');
my $captcha = $client->decode('path/to/captcha.jpg', +DeathByCaptcha::Client::DEFAULT_TIMEOUT);
if (defined $captcha) {
    print $captcha->{text}, "\n";
}

If your script is in a different folder, update use lib so Perl can find DeathByCaptcha/. For example:

use FindBin qw($Bin);
use lib "$Bin/../";
# or (when running from repository root): use lib './';

🚌 Transport options: Use HttpClient for encrypted HTTPS communication — credentials and data travel over TLS. Use SocketClient for lower latency and higher throughput — it is faster but communicates over a plain TCP connection to api.dbcapi.me on ports 8123–8130.

• Installation
• How to Use DBC API Clients
  • Common Clients' Interface
  • Available Methods
• Credentials & Configuration
  • Quick Setup
• CAPTCHA Types Quick Reference & Examples
  • Quick Start
  • Type Reference
  • Per-Type Code Snippets
• CAPTCHA Types Extended Reference
  • reCAPTCHA Image-Based API — Deprecated (Types 2 & 3)
  • reCAPTCHA Token API (v2 & v3)
  • reCAPTCHA v2 API FAQ
  • What is reCAPTCHA v3?
  • reCAPTCHA v3 API FAQ
  • Amazon WAF API (Type 16)
  • Cloudflare Turnstile API (Type 12)

Clone the repository:

git clone https://github.com/deathbycaptcha/deathbycaptcha-api-client-perl.git
cd deathbycaptcha-api-client-perl

Then install dependencies using cpanm (recommended):

cpanm --installdeps .

Or install modules manually:

cpanm LWP::UserAgent LWP::Protocol::https HTTP::Request::Common HTTP::Status JSON IO::Socket MIME::Base64

When running scripts from this repository (or another local checkout), add the local library path before importing modules:

use FindBin qw($Bin);
use lib "$Bin/";      # if DeathByCaptcha/ is next to your script
# use lib "$Bin/../"; # if your script is under samples/
# use lib './';         # from repository root

use DeathByCaptcha::HttpClient;

Choose the use lib path according to your folder layout so Perl can locate DeathByCaptcha/.

All clients must be instantiated with your DeathByCaptcha credentials — either username and password, or an authtoken (available in the DBC user panel). Replace HttpClient with SocketClient to use the socket transport instead.

use DeathByCaptcha::HttpClient;
use DeathByCaptcha::SocketClient;

# Username + password (HTTPS transport — encrypted, recommended when security matters)
my $client = DeathByCaptcha::HttpClient->new($username, $password);

# Username + password (socket transport — faster, lower latency, recommended for high throughput)
# my $client = DeathByCaptcha::SocketClient->new($username, $password);

# Authtoken — set $username to 'authtoken' and $password to the token
# my $client = DeathByCaptcha::HttpClient->new('authtoken', $authtoken);

All clients share the same interface. Below is a summary of every available method and its signature.

⚠️ Thread safety: Perl clients in this repo are not thread-safe. Use one client instance per thread.

Constants:

• DeathByCaptcha::Client::DEFAULT_TIMEOUT — 60 s (image captchas)
• DeathByCaptcha::Client::DEFAULT_TOKEN_TIMEOUT — 120 s (token captchas)

All methods that return a solved CAPTCHA return a plain hashref with the following keys:

# Example result hashref
{
    captcha    => 123456789,
    text       => '03AOPBWq_...',
    is_correct => 1,
}

use DeathByCaptcha::HttpClient;
use DeathByCaptcha::Client;

my $client = DeathByCaptcha::HttpClient->new($username, $password);

printf("Balance: %.4f US cents\n", $client->getBalance());

my $captcha = $client->decode('path/to/captcha.jpg', +DeathByCaptcha::Client::DEFAULT_TIMEOUT);
if (defined $captcha) {
    printf("Solved CAPTCHA %d: %s\n", $captcha->{captcha}, $captcha->{text});

    # Report only if you are certain the solution is wrong:
    # $client->report($captcha->{captcha});
}

The integration test reads credentials from a .env file in the project root. Credential values may be provided with or without surrounding quotes.

# ① Copy template and add credentials
cp .env.example .env
# Edit .env with your username and password
# Supported formats:
#   DBC_USERNAME=user
#   DBC_PASSWORD=pass
#   DBC_USERNAME='user'
#   DBC_PASSWORD='pass'

# ② Run unit tests locally
prove -l t/0[0-4]-*.t

# ③ Run integration test (requires valid DBC credentials and network)
prove -l t/05-integration.t

# ④ Push to repo for GitHub Actions
git push

This section covers every supported CAPTCHA type, how to run the corresponding example scripts, and ready-to-copy code snippets. Start with the Quick Start below, then use the Type Reference to find the type you need.

1. 📦 Install dependencies (see Installation)
2. 📂 Navigate to the samples/ directory and run the script for the type you need:

cd samples
perl example.pl your_username your_password path/to/captcha.jpg

Before running any script, set your DBC credentials at the top of the file:

my $USERNAME = 'your_username';
my $PASSWORD = 'your_password';

The table below maps every supported type to its use case, a code snippet, and the corresponding example file in samples/.

Minimal usage snippet for each supported type. Use these as a starting point and refer to the full sample files in samples/ for complete implementations.

Official description: Supported CAPTCHAs Full sample: samples/example.pl

my $captcha = $client->decode('images/normal.jpg', +DeathByCaptcha::Client::DEFAULT_TIMEOUT);

Official description: reCAPTCHA Token API (v2) Full sample: samples/recaptcha_v2_http.pl

my $captcha = $client->decodeToken(
    4,
    'token_params',
    {
        proxy     => 'http://user:pass@127.0.0.1:1234',
        proxytype => 'HTTP',
        googlekey => 'sitekey',
        pageurl   => 'https://target',
    },
    +DeathByCaptcha::Client::DEFAULT_TOKEN_TIMEOUT,
);

Official description: reCAPTCHA v3 Full sample: samples/recaptcha_v3_http.pl

my $captcha = $client->decodeToken(
    5,
    'token_params',
    {
        proxy     => 'http://user:pass@127.0.0.1:1234',
        proxytype => 'HTTP',
        googlekey => 'sitekey',
        pageurl   => 'https://target',
        action    => 'verify',
        min_score => 0.3,
    },
    +DeathByCaptcha::Client::DEFAULT_TOKEN_TIMEOUT,
);

Official description: reCAPTCHA v2 Enterprise Full sample: samples/recaptcha_enterprise_http.pl

my $captcha = $client->decodeToken(
    25,
    'token_enterprise_params',
    {
        proxy     => 'http://user:pass@127.0.0.1:1234',
        proxytype => 'HTTP',
        googlekey => 'sitekey',
        pageurl   => 'https://target',
    },
    +DeathByCaptcha::Client::DEFAULT_TOKEN_TIMEOUT,
);

Official description: GeeTest Full sample: samples/example.Geetest_v3.pl

my $captcha = $client->decodeToken(
    8,
    'geetest_params',
    {
        proxy     => 'http://user:pass@127.0.0.1:1234',
        proxytype => 'HTTP',
        gt        => 'gt_value',
        challenge => 'challenge_value',
        pageurl   => 'https://target',
    },
    +DeathByCaptcha::Client::DEFAULT_TOKEN_TIMEOUT,
);

Official description: GeeTest Full sample: samples/example.Geetest_v4.pl

my $captcha = $client->decodeToken(
    9,
    'geetest_params',
    {
        proxy      => 'http://user:pass@127.0.0.1:1234',
        proxytype  => 'HTTP',
        captcha_id => 'captcha_id',
        pageurl    => 'https://target',
    },
    +DeathByCaptcha::Client::DEFAULT_TOKEN_TIMEOUT,
);

Official description: Text CAPTCHA Full sample: samples/example.Textcaptcha.pl

my $captcha = $client->decodeToken(
    11,
    'textcaptcha',
    { textcaptcha => 'What is two plus two?' },
    +DeathByCaptcha::Client::DEFAULT_TOKEN_TIMEOUT,
);

Official description: Cloudflare Turnstile Full sample: samples/turnstile_http.pl

my $captcha = $client->decodeToken(
    12,
    'turnstile_params',
    {
        proxy     => 'http://user:pass@127.0.0.1:1234',
        proxytype => 'HTTP',
        sitekey   => 'sitekey',
        pageurl   => 'https://target',
    },
    +DeathByCaptcha::Client::DEFAULT_TOKEN_TIMEOUT,
);

Official description: Audio CAPTCHA Full sample: samples/example.Audio.pl

use MIME::Base64 qw(encode_base64);

open my $fh, '<:raw', 'audio.mp3' or die $!;
my $audio_b64 = encode_base64(do { local $/; <$fh> }, '');
close $fh;

my $captcha = $client->decodeToken(
    13,
    'audio',
    { audio => $audio_b64, language => 'en' },
    +DeathByCaptcha::Client::DEFAULT_TOKEN_TIMEOUT,
);

Official description: Lemin Full sample: samples/example.Lemin.pl

my $captcha = $client->decodeToken(
    14,
    'lemin_params',
    {
        proxy     => 'http://user:pass@127.0.0.1:1234',
        proxytype => 'HTTP',
        captchaid => 'CROPPED_xxx',
        pageurl   => 'https://target',
    },
    +DeathByCaptcha::Client::DEFAULT_TOKEN_TIMEOUT,
);

Official description: Capy Full sample: samples/example.Capy.pl

my $captcha = $client->decodeToken(
    15,
    'capy_params',
    {
        proxy      => 'http://user:pass@127.0.0.1:1234',
        proxytype  => 'HTTP',
        captchakey => 'PUZZLE_xxx',
        api_server => 'https://api.capy.me/',
        pageurl    => 'https://target',
    },
    +DeathByCaptcha::Client::DEFAULT_TOKEN_TIMEOUT,
);

Official description: Amazon WAF Full sample: samples/amazon_waf_http.pl

my $captcha = $client->decodeToken(
    16,
    'waf_params',
    {
        proxy     => 'http://user:pass@127.0.0.1:1234',
        proxytype => 'HTTP',
        sitekey   => 'sitekey',
        pageurl   => 'https://target',
        iv        => 'iv_value',
        context   => 'context_value',
    },
    +DeathByCaptcha::Client::DEFAULT_TOKEN_TIMEOUT,
);

Official description: Siara Full sample: samples/example.Siara.pl

my $captcha = $client->decodeToken(
    17,
    'siara_params',
    {
        proxy      => 'http://user:pass@127.0.0.1:1234',
        proxytype  => 'HTTP',
        slideurlid => 'slide_master_url_id',
        pageurl    => 'https://target',
        useragent  => 'Mozilla/5.0',
    },
    +DeathByCaptcha::Client::DEFAULT_TOKEN_TIMEOUT,
);

Official description: MTCaptcha Full sample: samples/example.Mtcaptcha.pl

my $captcha = $client->decodeToken(
    18,
    'mtcaptcha_params',
    {
        proxy     => 'http://user:pass@127.0.0.1:1234',
        proxytype => 'HTTP',
        sitekey   => 'MTPublic-xxx',
        pageurl   => 'https://target',
    },
    +DeathByCaptcha::Client::DEFAULT_TOKEN_TIMEOUT,
);

Official description: Cutcaptcha Full sample: samples/example.Cutcaptcha.pl

my $captcha = $client->decodeToken(
    19,
    'cutcaptcha_params',
    {
        proxy     => 'http://user:pass@127.0.0.1:1234',
        proxytype => 'HTTP',
        apikey    => 'api_key',
        miserykey => 'misery_key',
        pageurl   => 'https://target',
    },
    +DeathByCaptcha::Client::DEFAULT_TOKEN_TIMEOUT,
);

Official description: Friendly Captcha Full sample: samples/example.Friendly.pl

my $captcha = $client->decodeToken(
    20,
    'friendly_params',
    {
        proxy     => 'http://user:pass@127.0.0.1:1234',
        proxytype => 'HTTP',
        sitekey   => 'FCMG...',
        pageurl   => 'https://target',
    },
    +DeathByCaptcha::Client::DEFAULT_TOKEN_TIMEOUT,
);

Official description: DataDome Full sample: samples/example.Datadome.pl

my $captcha = $client->decodeToken(
    21,
    'datadome_params',
    {
        proxy       => 'http://user:pass@127.0.0.1:1234',
        proxytype   => 'HTTP',
        pageurl     => 'https://target',
        captcha_url => 'https://target/captcha',
    },
    +DeathByCaptcha::Client::DEFAULT_TOKEN_TIMEOUT,
);

Official description: Tencent Full sample: samples/example.Tencent.pl

my $captcha = $client->decodeToken(
    23,
    'tencent_params',
    {
        proxy     => 'http://user:pass@127.0.0.1:1234',
        proxytype => 'HTTP',
        appid     => 'appid',
        pageurl   => 'https://target',
    },
    +DeathByCaptcha::Client::DEFAULT_TOKEN_TIMEOUT,
);

Official description: ATB Full sample: samples/example.Atb.pl

my $captcha = $client->decodeToken(
    24,
    'atb_params',
    {
        proxy     => 'http://user:pass@127.0.0.1:1234',
        proxytype => 'HTTP',
        appid     => 'appid',
        apiserver => 'https://cap.aisecurius.com',
        pageurl   => 'https://target',
    },
    +DeathByCaptcha::Client::DEFAULT_TOKEN_TIMEOUT,
);

Full API-level documentation for selected CAPTCHA types: parameter references, payload schemas, request/response formats, token lifespans, and integration notes.

⚠️ Deprecated. Types 2 (Coordinates) and 3 (Image Group) are legacy image-based reCAPTCHA challenge methods that are no longer used at captcha solving. Do not use them for new integrations — use the reCAPTCHA Token API (v2 & v3) instead.

The Token-based API solves reCAPTCHA challenges by returning a token you inject directly into the page form, rather than clicking images. Given a site URL and site key, DBC solves the challenge on its side and returns a token valid for one submission.

• Token Image API: Provided a site URL and site key, the API returns a token that you use to submit the form on the page with the reCAPTCHA challenge.

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?

• username: Your DBC account username
• password: Your DBC account password
• type=4: Type 4 specifies this is the reCAPTCHA v2 Token API
• token_params=json(payload): the data to access the recaptcha challenge json payload structure:

  • proxy: your proxy url and credentials (if any). Examples:

    • http://127.0.0.1:3128
    • http://user:password@127.0.0.1:3128

  • proxytype: your proxy connection protocol. Example:

    • HTTP

  • googlekey: the google recaptcha site key of the website with the recaptcha. Example:

    • 6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-

  • pageurl: the url of the page with the recaptcha challenges. Example: if the recaptcha you want to solve is in http://test.com/path1, pageurl has to be http://test.com/path1 and not http://test.com.

  • data-s: This parameter is only required for solving google search tokens. Use the data-s value inside the google search response html. For regular tokens don't use this parameter.

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"

This API extends the reCAPTCHA v2 Token API with two additional parameters: action and minimal score (min_score).

reCAPTCHA v3 returns a score from each user, that evaluates if the 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.

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. The API will use "verify" default value 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 higher than 0.3 are hard to get.

What are the POST parameters for the reCAPTCHA v3 API?

• username: Your DBC account username
• password: Your DBC account password
• type=5: Type 5 specifies this is reCAPTCHA v3 API
• token_params=json(payload): the data to access the recaptcha challenge

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 a regular captcha. The solution will come in the text key of the response. It's valid for one use and has a 1 minute lifespan.

Amazon WAF Captcha (also referred to as AWS WAF Captcha) is part of the Intelligent Threat Mitigation system within Amazon AWS. It presents image-alignment challenges that DBC solves by returning a token you set as the aws-waf-token cookie on the target page.

• Official documentation: deathbycaptcha.com/api/amazonwaf
• Perl sample: samples/amazon_waf_http.pl

waf_params payload fields:

The proxy parameter is optional but strongly recommended — using a proxy prevents token rejection caused by IP inconsistencies between the solving machine (DBC) and the submitting machine (yours). 📌 Note: If proxy is provided, proxytype is required.

Full example of waf_params:

{
  "proxy": "http://user:password@127.0.0.1:1234",
  "proxytype": "HTTP",
  "sitekey": "AQIDAHjcYu/GjX+QlghicBgQ/7bFaQZ+m5FKCMDnO+vTbNg96AHDh0IR5vgzHNceHYqZR+GO...",
  "pageurl": "https://efw47fpad9.execute-api.us-east-1.amazonaws.com/latest",
  "iv": "CgAFRjIw2vAAABSM",
  "context": "zPT0jOl1rQlUNaldX6LUpn4D6Tl9bJ8VUQ/NrWFxPii..."
}

Response: Once received, set the token as the aws-waf-token cookie on the target page before submitting the form.

Cloudflare Turnstile is a CAPTCHA alternative that protects pages without requiring user interaction in most cases. DBC solves it by returning a token you inject into the target form or pass to the page's callback.

• Official documentation: deathbycaptcha.com/api/turnstile
• Perl sample: samples/turnstile_http.pl

turnstile_params payload fields:

📌 Note: The proxy parameter is optional but strongly recommended to avoid rejection due to IP inconsistency between the solver and the submitter. If proxy is provided, proxytype becomes required.

Example turnstile_params:

{
    "proxy": "http://user:password@127.0.0.1:1234",
    "proxytype": "HTTP",
    "sitekey": "0x4AAAAAAAGlwMzq_9z6S9Mh",
    "pageurl": "https://testsite.com/xxx-test"
}

Response: The API returns a token string valid for one use with a 2-minute lifespan. Submit it via the input[name="cf-turnstile-response"] field (or input[name="g-recaptcha-response"] when reCAPTCHA compatibility mode is enabled), or pass it to the callback defined in turnstile.render / data-callback.

CI / Quality	Status
Unit Tests (Perl 5.38)
Unit Tests (Perl 5.40)
Unit Tests (Perl 5.42)
Integration Tests (Perl 5.42)
Coverage (Perl 5.42)

See Responsible Use Agreement.