Skip to content

deathbycaptcha/deathbycaptcha-api-client-c11

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

21 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Python Node.js .NET Java PHP Perl C C++ Go

πŸ“– Introduction

The DeathByCaptcha C client is the official C11 library for DeathByCaptcha β€” the best captcha solving service for developers who need a reliable bypass captcha service in their automation pipelines. It provides a simple, well-documented interface for integrating CAPTCHA solving into any workflow β€” a particularly common need when used as a captcha solver for web scraping, where CAPTCHAs block access to the pages you need to extract data from. It supports both the HTTPS API (encrypted transport via libcurl β€” recommended when security is a priority) and the socket-based API (faster and lower latency, recommended for high-throughput production workloads).

Key features:

  • 🧩 Send image, audio and modern token-based CAPTCHA types (reCAPTCHA v2/v3, Turnstile, GeeTest, etc.).
  • πŸ”„ Unified client API across HTTPS and socket transports β€” switching is a single dbc_set_transport() call.
  • πŸ” Built-in support for proxies, timeouts and advanced token parameters for modern CAPTCHA flows.
  • πŸ—οΈ Multiplatform CMake build system for Linux, macOS and Windows.

Quick start example (socket transport):

#include "deathbycaptcha.h"

dbc_client  client;
dbc_captcha captcha;

dbc_init(&client, "your_username", "your_password");

FILE *f = fopen("captcha.jpg", "rb");
if (dbc_decode_file(&client, &captcha, f, DBC_TIMEOUT) == 0)
    printf("Solved: %s\n", captcha.text);
fclose(f);

dbc_close(&client);

🚌 Transport options: Use DBC_TRANSPORT_HTTPS for encrypted communication via libcurl β€” credentials and data travel over TLS. Use DBC_TRANSPORT_SOCKET (the default) for lower latency and higher throughput β€” it is faster but communicates over a plain TCP connection to api.dbcapi.me on port 8123.


Tests Status

CI Coverage


πŸ—‚οΈ Index

πŸ› οΈ Installation

Build requirements and platform notes are in doc/BUILD.md.

# Clone the repository
git clone https://github.com/deathbycaptcha/deathbycaptcha-api-client-c11.git
cd deathbycaptcha-api-client-c11

# Development build (debug symbols, assertions enabled)
cmake --preset default
cmake --build --preset default

# Optimised release build
cmake --preset release
cmake --build --preset release

πŸš€ How to Use DBC API Clients

πŸ”Œ Common Clients' Interface

All clients must be initialised with your DeathByCaptcha credentials β€” either username and password, or an authtoken (available in the DBC user panel). Call dbc_set_transport() to switch between socket (default) and HTTPS transports.

#include "deathbycaptcha.h"

dbc_client client;

/* Username + password β€” socket transport (default, faster, lower latency) */
dbc_init(&client, username, password);

/* Username + password β€” HTTPS transport (encrypted TLS, recommended when security matters) */
dbc_init(&client, username, password);
dbc_set_transport(&client, DBC_TRANSPORT_HTTPS);

/* Authtoken only */
dbc_init_token(&client, authtoken);

/* Always release resources when done */
dbc_close(&client);
Transport Constant Best for
Socket DBC_TRANSPORT_SOCKET Plain TCP β€” faster and lower latency, recommended for high-throughput production workloads
HTTPS DBC_TRANSPORT_HTTPS Encrypted TLS via libcurl β€” safer for credential handling and network-sensitive environments

All clients share the same interface. Below is a summary of every available function.

Function Returns Description
dbc_get_balance() double Current account balance in US cents.
dbc_decode_file() 0 / -1 Upload an image CAPTCHA from a FILE* stream and poll until solved. timeout 0 β†’ 60 s.
dbc_decode() 0 / -1 Upload an image CAPTCHA from a memory buffer and poll until solved. timeout 0 β†’ 60 s.
dbc_decode_recaptcha_v2() 0 / -1 Solve reCAPTCHA v2 (type 4). Takes sitekey, pageurl, optional proxy/proxytype. timeout 0 β†’ 120 s.
dbc_decode_recaptcha_v3() 0 / -1 Solve reCAPTCHA v3 (type 5). Takes sitekey, pageurl, action, min_score, optional proxy. timeout 0 β†’ 120 s.
dbc_decode_recaptcha_enterprise() 0 / -1 Solve reCAPTCHA v2 Enterprise (type 25). Takes sitekey, pageurl, optional proxy. timeout 0 β†’ 120 s.
dbc_decode_token() 0 / -1 Generic token solver. Takes numeric type, params_field name, and params_json string. timeout 0 β†’ 120 s.
dbc_get_captcha() 0 / -1 Fetch the status and result of a previously uploaded CAPTCHA by numeric id.
dbc_report() 0 / -1 Report a CAPTCHA as incorrectly solved to request a refund. Only report genuine errors.

πŸ“¬ CAPTCHA Result Structure

All solve functions populate a dbc_captcha struct when successful:

Field Type Description
.id unsigned int Numeric CAPTCHA ID assigned by DBC
.text char[] Solved text or token (the value you inject into the page)
/* Example usage after a successful solve */
dbc_captcha captcha;
if (dbc_decode_recaptcha_v2(&client, &captcha, sitekey, pageurl,
                             NULL, NULL, DBC_TOKEN_TIMEOUT) == 0) {
    printf("ID: %u  Token: %s\n", captcha.id, captcha.text);
    dbc_close_captcha(&captcha);
}

πŸ’‘ Full Usage Example

#include <stdio.h>
#include <stdlib.h>
#include "deathbycaptcha.h"

int main(void)
{
    dbc_client  client;
    dbc_captcha captcha;

    if (dbc_init(&client, "your_username", "your_password") != 0) {
        fprintf(stderr, "Failed to initialize client\n");
        return EXIT_FAILURE;
    }

    printf("Balance: %.2f US cents\n", dbc_get_balance(&client));

    FILE *f = fopen("captcha.jpg", "rb");
    if (f && dbc_decode_file(&client, &captcha, f, DBC_TIMEOUT) == 0) {
        printf("Solved CAPTCHA %u: %s\n", captcha.id, captcha.text);

        /* Report only if you are certain the solution is wrong: */
        /* dbc_report(&client, &captcha); */

        dbc_close_captcha(&captcha);
    } else {
        printf("Failed (timeout or error)\n");
    }
    if (f) fclose(f);

    dbc_close(&client);
    return EXIT_SUCCESS;
}

πŸ”‘ Credentials & Configuration

Credentials are compiled directly into example programs via #define constants, or passed to dbc_init() at runtime. For CI environments, set DBC_USERNAME and DBC_PASSWORD as repository secrets and pass them at build or test time.

⚑ Quick Setup

# β‘  Build the library and CLI
cmake --preset default && cmake --build --preset default

# β‘‘ Edit an example with your credentials and compile it
#    (replace USERNAME / PASSWORD defines inside the .c file)
cd examples
gcc -o example.Normal_Captcha \
    example.Normal_Captcha.c \
    ../build/default/lib/libdeathbycaptcha.so \
    -I../src
./example.Normal_Captcha

# β‘’ Run the full test suite
cd ..
cmake --build --preset default --target test

# β‘£ Push to repo for GitHub Actions CI
git push

🧩 CAPTCHA Types Quick Reference & Examples

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

🏁 Quick Start

  1. πŸ”¨ Build the library (see Installation)
  2. πŸ“‚ Navigate to the examples/ directory and compile the example for the type you need:
cd examples

# Balance check
gcc -o get_balance get_balance.c ../build/default/lib/libdeathbycaptcha.so -I../src
./get_balance

# Standard image CAPTCHA (requires test.jpg in the examples/ directory)
gcc -o example.Normal_Captcha example.Normal_Captcha.c \
    ../build/default/lib/libdeathbycaptcha.so -I../src
./example.Normal_Captcha

⚠️ Always compile examples from the examples/ directory so relative paths (e.g. test.jpg) are resolved correctly.

Before compiling, add your DBC credentials inside the example file:

#define USERNAME  "your_username"
#define PASSWORD  "your_password"

πŸ“‹ Type Reference

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

Type ID CAPTCHA Type Use Case Quick Use C Sample
0 Standard Image Basic image CAPTCHA snippet open
2 reCAPTCHA Coordinates Deprecated β€” do not use for new integrations β€” β€”
3 reCAPTCHA Image Group Deprecated β€” do not use for new integrations β€” β€”
4 reCAPTCHA v2 Token reCAPTCHA v2 token solving snippet open
5 reCAPTCHA v3 Token reCAPTCHA v3 with risk scoring snippet open
25 reCAPTCHA v2 Enterprise reCAPTCHA v2 Enterprise tokens snippet open
8 GeeTest v3 Geetest v3 verification snippet open
9 GeeTest v4 Geetest v4 verification snippet open
11 Text CAPTCHA Text-based question solving snippet open
12 Cloudflare Turnstile Cloudflare Turnstile token snippet open
13 Audio CAPTCHA Audio CAPTCHA solving snippet open
14 Lemin Lemin CAPTCHA snippet open
15 Capy Capy CAPTCHA snippet open
16 Amazon WAF Amazon WAF verification snippet open
17 Siara Siara CAPTCHA snippet open
18 MTCaptcha Mtcaptcha CAPTCHA snippet open
19 Cutcaptcha Cutcaptcha CAPTCHA snippet open
20 Friendly Captcha Friendly Captcha snippet open
21 DataDome Datadome verification snippet open
23 Tencent Tencent CAPTCHA snippet open
24 ATB ATB CAPTCHA snippet open

πŸ“ Per-Type Code Snippets

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

πŸ–ΌοΈ Sample Type 0: Standard Image

Official description: Supported CAPTCHAs Full sample: example.Normal_Captcha.c

FILE *f = fopen("captcha.jpg", "rb");
dbc_decode_file(&client, &captcha, f, DBC_TIMEOUT);
fclose(f);

πŸ€– Sample Type 4: reCAPTCHA v2 Token

Official description: reCAPTCHA Token API (v2) Full sample: example.reCAPTCHA_v2.c

dbc_decode_recaptcha_v2(&client, &captcha,
    "sitekey",
    "https://target",
    "http://user:pass@127.0.0.1:1234", "HTTP",
    DBC_TOKEN_TIMEOUT);

πŸ€– Sample Type 5: reCAPTCHA v3 Token

Official description: reCAPTCHA v3 Full sample: example.reCAPTCHA_v3.c

dbc_decode_recaptcha_v3(&client, &captcha,
    "sitekey",
    "https://target",
    "verify", 0.3,
    "http://user:pass@127.0.0.1:1234", "HTTP",
    DBC_TOKEN_TIMEOUT);

🏒 Sample Type 25: reCAPTCHA v2 Enterprise

Official description: reCAPTCHA v2 Enterprise Full sample: example.reCAPTCHA_v2_Enterprise.c

dbc_decode_recaptcha_enterprise(&client, &captcha,
    "sitekey",
    "https://target",
    "http://user:pass@127.0.0.1:1234", "HTTP",
    DBC_TOKEN_TIMEOUT);

🧩 Sample Type 8: GeeTest v3

Official description: GeeTest Full sample: example.Geetest_v3.c

const char *params =
    "{\"proxy\":\"http://user:pass@127.0.0.1:1234\","
    "\"proxytype\":\"HTTP\","
    "\"gt\":\"gt_value\","
    "\"challenge\":\"challenge_value\","
    "\"pageurl\":\"https://target\"}";
dbc_decode_token(&client, &captcha, 8, "geetest_params", params, DBC_TOKEN_TIMEOUT);

🧩 Sample Type 9: GeeTest v4

Official description: GeeTest Full sample: example.Geetest_v4.c

const char *params =
    "{\"proxy\":\"http://user:pass@127.0.0.1:1234\","
    "\"proxytype\":\"HTTP\","
    "\"captcha_id\":\"captcha_id\","
    "\"pageurl\":\"https://target\"}";
dbc_decode_token(&client, &captcha, 9, "geetest_params", params, DBC_TOKEN_TIMEOUT);

πŸ’¬ Sample Type 11: Text CAPTCHA

Official description: Text CAPTCHA Full sample: example.Textcaptcha.c

const char *params = "{\"textcaptcha\":\"What is two plus two?\"}";
dbc_decode_token(&client, &captcha, 11, "textcaptcha", params, DBC_TOKEN_TIMEOUT);

☁️ Sample Type 12: Cloudflare Turnstile

Official description: Cloudflare Turnstile Full sample: example.Turnstile.c

const char *params =
    "{\"proxy\":\"http://user:pass@127.0.0.1:1234\","
    "\"proxytype\":\"HTTP\","
    "\"sitekey\":\"sitekey\","
    "\"pageurl\":\"https://target\"}";
dbc_decode_token(&client, &captcha, 12, "turnstile_params", params, DBC_TOKEN_TIMEOUT);

πŸ”Š Sample Type 13: Audio CAPTCHA

Official description: Audio CAPTCHA Full sample: example.Audio.c

/* audio value must be prefixed with "base64:"; language is e.g. "en" */
const char *params =
    "{\"audio\":\"base64:<audio_base64>\","
    "\"language\":\"en\"}";
dbc_decode_token(&client, &captcha, 13, "audio", params, DBC_TOKEN_TIMEOUT);

πŸ”΅ Sample Type 14: Lemin

Official description: Lemin Full sample: example.Lemin.c

const char *params =
    "{\"proxy\":\"http://user:pass@127.0.0.1:1234\","
    "\"proxytype\":\"HTTP\","
    "\"captchaid\":\"CROPPED_xxx\","
    "\"pageurl\":\"https://target\"}";
dbc_decode_token(&client, &captcha, 14, "lemin_params", params, DBC_TOKEN_TIMEOUT);

🏴 Sample Type 15: Capy

Official description: Capy Full sample: example.Capy.c

const char *params =
    "{\"proxy\":\"http://user:pass@127.0.0.1:1234\","
    "\"proxytype\":\"HTTP\","
    "\"captchakey\":\"PUZZLE_xxx\","
    "\"api_server\":\"https://api.capy.me/\","
    "\"pageurl\":\"https://target\"}";
dbc_decode_token(&client, &captcha, 15, "capy_params", params, DBC_TOKEN_TIMEOUT);

πŸ›‘οΈ Sample Type 16: Amazon WAF

Official description: Amazon WAF Full sample: example.Amazon_Waf.c

const char *params =
    "{\"proxy\":\"http://user:pass@127.0.0.1:1234\","
    "\"proxytype\":\"HTTP\","
    "\"sitekey\":\"sitekey\","
    "\"pageurl\":\"https://target\","
    "\"iv\":\"iv_value\","
    "\"context\":\"context_value\"}";
dbc_decode_token(&client, &captcha, 16, "waf_params", params, DBC_TOKEN_TIMEOUT);

πŸ” Sample Type 17: Siara

Official description: Siara Full sample: example.Siara.c

const char *params =
    "{\"proxy\":\"http://user:pass@127.0.0.1:1234\","
    "\"proxytype\":\"HTTP\","
    "\"slideurlid\":\"slide_master_url_id\","
    "\"pageurl\":\"https://target\","
    "\"useragent\":\"Mozilla/5.0\"}";
dbc_decode_token(&client, &captcha, 17, "siara_params", params, DBC_TOKEN_TIMEOUT);

πŸ”’ Sample Type 18: MTCaptcha

Official description: MTCaptcha Full sample: example.Mtcaptcha.c

const char *params =
    "{\"proxy\":\"http://user:pass@127.0.0.1:1234\","
    "\"proxytype\":\"HTTP\","
    "\"sitekey\":\"MTPublic-xxx\","
    "\"pageurl\":\"https://target\"}";
dbc_decode_token(&client, &captcha, 18, "mtcaptcha_params", params, DBC_TOKEN_TIMEOUT);

βœ‚οΈ Sample Type 19: Cutcaptcha

Official description: Cutcaptcha Full sample: example.Cutcaptcha.c

const char *params =
    "{\"proxy\":\"http://user:pass@127.0.0.1:1234\","
    "\"proxytype\":\"HTTP\","
    "\"apikey\":\"api_key\","
    "\"miserykey\":\"misery_key\","
    "\"pageurl\":\"https://target\"}";
dbc_decode_token(&client, &captcha, 19, "cutcaptcha_params", params, DBC_TOKEN_TIMEOUT);

πŸ’š Sample Type 20: Friendly Captcha

Official description: Friendly Captcha Full sample: example.Friendly.c

const char *params =
    "{\"proxy\":\"http://user:pass@127.0.0.1:1234\","
    "\"proxytype\":\"HTTP\","
    "\"sitekey\":\"FCMG...\","
    "\"pageurl\":\"https://target\"}";
dbc_decode_token(&client, &captcha, 20, "friendly_params", params, DBC_TOKEN_TIMEOUT);

πŸ›‘οΈ Sample Type 21: DataDome

Official description: DataDome Full sample: example.Datadome.c

const char *params =
    "{\"proxy\":\"http://user:pass@127.0.0.1:1234\","
    "\"proxytype\":\"HTTP\","
    "\"pageurl\":\"https://target\","
    "\"captcha_url\":\"https://target/captcha\"}";
dbc_decode_token(&client, &captcha, 21, "datadome_params", params, DBC_TOKEN_TIMEOUT);

🌐 Sample Type 23: Tencent

Official description: Tencent Full sample: example.Tencent.c

const char *params =
    "{\"proxy\":\"http://user:pass@127.0.0.1:1234\","
    "\"proxytype\":\"HTTP\","
    "\"appid\":\"appid\","
    "\"pageurl\":\"https://target\"}";
dbc_decode_token(&client, &captcha, 23, "tencent_params", params, DBC_TOKEN_TIMEOUT);

🏷️ Sample Type 24: ATB

Official description: ATB Full sample: example.Atb.c

const char *params =
    "{\"proxy\":\"http://user:pass@127.0.0.1:1234\","
    "\"proxytype\":\"HTTP\","
    "\"appid\":\"appid\","
    "\"apiserver\":\"https://cap.aisecurius.com\","
    "\"pageurl\":\"https://target\"}";
dbc_decode_token(&client, &captcha, 24, "atb_params", params, DBC_TOKEN_TIMEOUT);

πŸ“š CAPTCHA Types Extended Reference

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


β›” reCAPTCHA Image-Based API β€” Deprecated (Types 2 & 3)

⚠️ 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.


πŸ” reCAPTCHA Token API (v2 & v3)

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.

❓ 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?

  • 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:

    • proxytype: your proxy connection protocol. For supported proxy types refer to Which proxy types are supported?. Example:

      • HTTP
    • googlekey: the google recaptcha site key of the website with the recaptcha. For more details about the site key refer to What is a recaptcha site key?. Example:

      • 6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-
    • pageurl: the url of the page with the recaptcha challenges. This url has to include the path in which the recaptcha is loaded. 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 solve the google search tokens, the ones visible, while google search trigger the robot protection. Use the data-s value inside the google search response html. For regulars 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 field of dbc_captcha. 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 is reCAPTCHA v3?

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 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?

  • 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 json payload structure:
    • proxy: your proxy url and credentials (if any). Examples:

    • proxytype: your proxy connection protocol. For supported proxy types refer to Which proxy types are supported?. Example:

      • HTTP
    • googlekey: the google recaptcha site key of the website with the recaptcha. For more details about the site key refer to What is a recaptcha site key?. Example:

      • 6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-
    • pageurl: the url of the page with the recaptcha challenges. This url has to include the path in which the recaptcha is loaded. 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.

    • action: The action name.

    • min_score: The minimal score, usually 0.3

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 field of dbc_captcha. It's valid for one use and has a 1 minute lifespan.


πŸ›‘οΈ Amazon WAF API (Type 16)

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.

API URL: Send a HTTP POST request to http://api.dbcapi.me/api/captcha

POST parameters:

  • username: Your DBC account username
  • password: Your DBC account password
  • type=16: Type 16 specifies this is the Amazon WAF API
  • waf_params=json(payload): The data needed to access the Amazon WAF challenge

waf_params payload fields:

Parameter Required Description
proxy Optional* Proxy URL with credentials. E.g. http://user:password@127.0.0.1:3128
proxytype Required if proxy set Proxy protocol. Currently only HTTP is supported.
sitekey Required Amazon WAF site key found in the page's captcha script (value of the key parameter)
pageurl Required Full URL of the page showing the Amazon WAF challenge (must include the path)
iv Required Value of the iv parameter found in the captcha script on the page
context Required Value of the context parameter found in the captcha script on the page
challengejs Optional URL of the challenge.js script referenced on the page
captchajs Optional URL of the captcha.js script referenced on the page

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: The API returns a token string valid for one use with a 1-minute lifespan. Once received, set it as the aws-waf-token cookie on the target page before submitting the form.


🌐 Cloudflare Turnstile API (Type 12)

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.

API URL: Send a HTTP POST request to http://api.dbcapi.me/api/captcha

POST Parameter Description
username Your DBC account username
password Your DBC account password
type 12 β€” specifies this is a Turnstile API request
turnstile_params JSON-encoded payload (see fields below)

turnstile_params payload fields:

Field Required Description
proxy Optional Proxy URL with optional credentials. E.g. http://user:password@127.0.0.1:3128
proxytype Required if proxy set Proxy connection protocol. Currently only HTTP is supported.
sitekey Required The Turnstile site key found in data-sitekey attribute, the captcha iframe URL, or the turnstile.render call. E.g. 0x4AAAAAAAGlwMzq_9z6S9Mh
pageurl Required Full URL of the page hosting the Turnstile challenge, including path. E.g. https://testsite.com/xxx-test
action Optional Value of the data-action attribute or the action option passed to turnstile.render.

πŸ“Œ 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 (basic):

{
    "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).

Tests and CI

Workflow Status
CI (unit + integration) CI
Tests Linux Tests Linux
Tests Windows Tests Windows
Tests macOS Tests macOS
CI 32-bit CI 32-bit
Release CLI Binaries Release CLI Binaries
Coverage Coverage

Coverage badge notes:

  • Served via GitHub Pages as a shields.io endpoint JSON.
  • No external service (Codecov, etc.) is used.
  • No workflow commits back to master.

Project Layout

  • src/: core library (deathbycaptcha.h, deathbycaptcha.c) and CLI (client.c).
  • doc/: build guide, CLI guide, library guide, and dynamic loading examples.
  • examples/: standalone .c programs β€” one per CAPTCHA type.
  • tests/: unit and integration test harnesses.
  • CMakeLists.txt, CMakePresets.json: multiplatform build system (Linux, macOS, Windows).

Documentation

βš–οΈ Responsible Use

See Responsible Use Agreement.

Contributing

Contributions should keep API behavior compatible with existing official clients and include tests for new functionality.

Changelog / Releases

See CHANGELOG.md and the Releases page.

License

See LICENSE.

Badge Details

  • CI indicates the main ci.yml workflow status on master. Runs build + unit + integration tests on Linux, macOS and Windows.
  • Coverage reflects the latest coverage percentage published to GitHub Pages as a shields.io endpoint JSON. Updated on each push to master. No external service (Codecov, etc.) is used.
  • Release CLI Binaries indicates packaging/release workflow status.
  • OS-specific test badges in Tests and CI show per-platform validation coverage for Linux, Windows, and macOS.