The DeathByCaptcha .NET client is a library for automated captcha solving in C# and VB.NET applications. It provides a simple, well-documented interface to the DeathByCaptcha solving service β covering everything from basic image CAPTCHAs to modern token-based challenges. A common use case is captcha solving for data extraction pipelines, where CAPTCHAs block access to the pages you need to scrape. 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).
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):
using DeathByCaptcha;
Client client = new DeathByCaptcha.HttpClient("your_username", "your_password");
Captcha captcha = client.Decode("path/to/captcha.jpg", 120);
if (captcha != null)
Console.WriteLine(captcha.Text);π Transport options: Use
DeathByCaptcha.HttpClientfor encrypted HTTPS communication β credentials and data travel over TLS. UseDeathByCaptcha.SocketClientfor lower latency and higher throughput β it is faster but communicates over a plain TCP connection toapi.dbcapi.meon ports8123β8130.
- Installation
- How to Use DBC API Clients
- Credentials & Configuration
- CAPTCHA Types Quick Reference & Examples
- CAPTCHA Types Extended Reference
- Running Tests
- CI Status Badges
- Changelog
- Selenium Test Sample
- C# and VB Samples Guide
dotnet add package DeathByCaptcha --version 4.7.1Or add it directly in your project file:
<ItemGroup>
<PackageReference Include="DeathByCaptcha" Version="4.7.1" />
</ItemGroup>For the latest development version or to contribute:
git clone https://github.com/deathbycaptcha/deathbycaptcha-api-client-dotnet.git
cd deathbycaptcha-api-client-dotnet
dotnet restore dbc_api_net.slnAll clients must be instantiated with your DeathByCaptcha credentials β either username and password, or an authtoken (available in the DBC user panel). Replace DeathByCaptcha.HttpClient with DeathByCaptcha.SocketClient to use the socket transport instead.
using DeathByCaptcha;
// Username + password (HTTPS transport β encrypted, recommended when security matters)
Client client = new DeathByCaptcha.HttpClient(username, password);
// Username + password (socket transport β faster, lower latency, recommended for high throughput)
// Client client = new DeathByCaptcha.SocketClient(username, password);
// Authtoken β pass the literal string "authtoken" as username and the token as password
// Client client = new DeathByCaptcha.HttpClient("authtoken", token_from_panel);π‘ Note: If your project also uses
System.Net.Http, qualify the class asDeathByCaptcha.HttpClientto avoid type ambiguity.
| Transport | Class | Best for |
|---|---|---|
| HTTPS | DeathByCaptcha.HttpClient |
Encrypted TLS transport β safer for credential handling and network-sensitive environments |
| Socket | DeathByCaptcha.SocketClient |
Plain TCP β faster and lower latency, recommended for high-throughput production workloads |
The .NET clients are thread-safe β it is perfectly fine to share a single client between multiple threads (although in heavily multithreaded applications a pool of clients is preferable).
All clients share the same interface. Below is a summary of every available method and its signature.
| Method | Signature | Returns | Description |
|---|---|---|---|
Upload() |
Upload(string imageFileName) |
Captcha or null |
Upload a CAPTCHA for solving without waiting. |
Decode() |
Decode(string imageFileName) |
Captcha or null |
Upload and poll until solved using the default timeout (Client.DefaultTimeout). |
Decode() |
Decode(string imageFileName, int timeout) |
Captcha or null |
Upload and poll until solved or timed out. Preferred method for most integrations. |
Decode() |
Decode(int timeout, Hashtable ext_data) |
Captcha or null |
Upload token/vendor CAPTCHA types using the ext_data hashtable. |
GetCaptcha() |
GetCaptcha(int captchaId) |
Captcha or null |
Fetch status and result of a previously uploaded CAPTCHA by its numeric ID. |
Report() |
Report(Captcha captcha) |
bool |
Report a CAPTCHA as incorrectly solved to request a refund. Only report genuine errors. |
GetBalance() |
GetBalance() |
double |
Return the current account balance in US cents. |
All methods that return a solved CAPTCHA return a DeathByCaptcha.Captcha object exposing the following properties:
| Property | Type | Description |
|---|---|---|
Id |
int |
Numeric CAPTCHA ID assigned by DBC |
Text |
string |
Solved text or token (the value you inject into the page) |
Correct |
bool |
Whether DBC considers the solution correct |
Solved |
bool |
Whether the CAPTCHA has been solved |
Uploaded |
bool |
Whether the CAPTCHA was successfully uploaded |
using System;
using DeathByCaptcha;
string username = Environment.GetEnvironmentVariable("DBC_USERNAME") ?? "your_username";
string password = Environment.GetEnvironmentVariable("DBC_PASSWORD") ?? "your_password";
Client client = new DeathByCaptcha.HttpClient(username, password);
try
{
Console.WriteLine("Balance: " + client.GetBalance() + " US cents");
Captcha captcha = client.Decode("path/to/captcha.jpg", 120);
if (captcha != null)
{
Console.WriteLine($"Solved CAPTCHA {captcha.Id}: {captcha.Text}");
// Report only if you are certain the solution is wrong:
// client.Report(captcha);
}
}
catch (AccessDeniedException)
{
Console.WriteLine("Access denied β check your credentials and/or balance");
}Keep credentials in environment variables instead of hardcoding them:
export DBC_USERNAME="your_username"
export DBC_PASSWORD="your_password"For CI environments set repository secrets DBC_USERNAME and DBC_PASSWORD. Integration tests read these variables automatically and skip gracefully if they are absent.
# β Clone and restore
git clone https://github.com/deathbycaptcha/deathbycaptcha-api-client-dotnet.git
cd deathbycaptcha-api-client-dotnet
dotnet restore dbc_api_net.sln
# β‘ Copy credentials template and add credentials
cp .env.sample .env
# Edit .env with your DBC_USERNAME and DBC_PASSWORD
# β’ Run unit tests locally
dotnet test DeathByCaptcha/DeathByCaptcha.Tests/DeathByCaptcha.Tests.csproj -c Release --filter "Category!=Integration"
# β£ Run a C# example (replace startup class as needed)
dotnet run --project DBC_Examples/DBC_Examples.csproj -c Release -f net10.0 \
-p:ExamplesStartupObject=DeathByCaptcha.ExampleSimple \
-- "$DBC_USERNAME" "$DBC_PASSWORD" DBC_Examples/images/normal.jpgSee EXAMPLES_CSHARP_VB.md for a complete startup class map and run commands for all C# and VB samples.
This repository already includes SDK-style .NET projects for the library and examples. You do not need to create a new console project to use the included samples.
Projects:
- Main library:
DeathByCaptcha/DeathByCaptcha/DeathByCaptcha.csproj - Internal JSON dependency:
DeathByCaptcha/SimpleJson/SimpleJson.csproj - C# examples:
DBC_Examples/DBC_Examples.csproj - VB examples:
DBC_Examples_VB/DBC_Examples_VB.vbproj
Target frameworks: net6.0, net8.0, net10.0 β prefer net10.0 for regular development.
Canonical dotnet CLI commands:
dotnet restore dbc_api_net.sln
dotnet build dbc_api_net.sln -c Release
dotnet test DeathByCaptcha/DeathByCaptcha.Tests/DeathByCaptcha.Tests.csproj -c Release
# Run C# example with explicit startup class:
dotnet run --project DBC_Examples/DBC_Examples.csproj -c Release -f net10.0 \
-p:ExamplesStartupObject=DeathByCaptcha.ExampleSimple \
-- "$DBC_USERNAME" "$DBC_PASSWORD" DBC_Examples/images/normal.jpg
# Run Selenium sample:
dotnet run --project DBC_Examples/DBC_Examples.csproj -c Release -f net10.0 \
-p:ExamplesStartupObject=DeathByCaptcha.SeleniumRecaptchaV2ExampleOptional Make wrapper:
make -f Makefile-dotnet build
make -f Makefile-dotnet test
make -f Makefile-dotnet run-cs CS_STARTUP=DeathByCaptcha.RecaptchaV2Example
make -f Makefile-dotnet run-vb VB_STARTUP=DBC_Examples_VB.RecaptchaV2This section covers every supported CAPTCHA type, how to run the corresponding example files, and ready-to-copy code snippets. Start with the Quick Start below, then use the Type Reference to find the type you need.
- π¦ Install or restore the library (see Installation)
- π Navigate to the project and run the example for the type you need using
dotnet run:
dotnet run --project DBC_Examples/DBC_Examples.csproj -c Release -f net10.0 \
-p:ExamplesStartupObject=DeathByCaptcha.NormalCaptchaExample \
-- "$DBC_USERNAME" "$DBC_PASSWORD" DBC_Examples/images/normal.jpg
# Balance check:
dotnet run --project DBC_Examples/DBC_Examples.csproj -c Release -f net10.0 \
-p:ExamplesStartupObject=DeathByCaptcha.ExampleSimple \
-- "$DBC_USERNAME" "$DBC_PASSWORD"Before running any example, set DBC_USERNAME and DBC_PASSWORD in your environment or .env file.
The table below maps every supported type to its use case, a code snippet, and the corresponding example files in DBC_Examples/ and DBC_Examples_VB/.
| Type ID | CAPTCHA Type | Use Case | Quick Use | C# Sample | VB Sample |
|---|---|---|---|---|---|
| 0 | Standard Image | Basic image CAPTCHA | snippet | NormalCaptchaExample.cs | Normal_Captcha.vb |
| 2 | Deprecated β do not use for new integrations | β | β | β | |
| 3 | Deprecated β do not use for new integrations | β | β | β | |
| 4 | reCAPTCHA v2 Token | reCAPTCHA v2 token solving | snippet | RecaptchaV2Example.cs | RecaptchaV2.vb |
| 5 | reCAPTCHA v3 Token | reCAPTCHA v3 with risk scoring | snippet | RecaptchaV3Example.cs | RecaptchaV3.vb |
| 25 | reCAPTCHA v2 Enterprise | reCAPTCHA v2 Enterprise tokens | snippet | RecaptchaV2EnterpriseExample.cs | RecaptchaV2Enterprise.vb |
| 8 | GeeTest v3 | Geetest v3 verification | snippet | GeetestV3Example.cs | GeetestV3.vb |
| 9 | GeeTest v4 | Geetest v4 verification | snippet | GeetestV4Example.cs | GeetestV4.vb |
| 11 | Text CAPTCHA | Text-based question solving | snippet | TextcaptchaExample.cs | Textcaptcha.vb |
| 12 | Cloudflare Turnstile | Cloudflare Turnstile token | snippet | TurnstileExample.cs | Turnstile.vb |
| 13 | Audio CAPTCHA | Audio CAPTCHA solving | snippet | AudioExample.cs | Audio.vb |
| 14 | Lemin | Lemin CAPTCHA | snippet | LeminExample.cs | Lemin.vb |
| 15 | Capy | Capy CAPTCHA | snippet | CapyExample.cs | Capy.vb |
| 16 | Amazon WAF | Amazon WAF verification | snippet | AmazonWafExample.cs | AmazonWaf.vb |
| 17 | Siara | Siara CAPTCHA | snippet | SiaraExample.cs | Siara.vb |
| 18 | MTCaptcha | Mtcaptcha CAPTCHA | snippet | MtcaptchaExample.cs | Mtcaptcha.vb |
| 19 | Cutcaptcha | Cutcaptcha CAPTCHA | snippet | CutcaptchaExample.cs | Cutcaptcha.vb |
| 20 | Friendly Captcha | Friendly Captcha | snippet | FriendlycaptchaExample.cs | Friendlycaptcha.vb |
| 21 | DataDome | Datadome verification | snippet | DatadomeExample.cs | Datadome.vb |
| 23 | Tencent | Tencent CAPTCHA | snippet | TencentExample.cs | Tencent.vb |
| 24 | ATB | ATB CAPTCHA | snippet | AtbExample.cs | Atb.vb |
Minimal usage snippet for each supported type. Use these as a starting point and refer to the full example files in DBC_Examples/ and DBC_Examples_VB/ for complete implementations.
Official description: Supported CAPTCHAs Full C# sample: NormalCaptchaExample.cs
Captcha captcha = client.Decode("images/normal.jpg", 120);Official description: reCAPTCHA Token API (v2) Full C# sample: RecaptchaV2Example.cs
string tokenParams = "{\"proxy\":\"http://user:pass@127.0.0.1:1234\",\"proxytype\":\"HTTP\",\"googlekey\":\"sitekey\",\"pageurl\":\"https://target\"}";
Captcha captcha = client.Decode(Client.DefaultTimeout, new Hashtable { {"type", 4}, {"token_params", tokenParams} });Official description: reCAPTCHA v3 Full C# sample: RecaptchaV3Example.cs
string tokenParams = "{\"proxy\":\"http://user:pass@127.0.0.1:1234\",\"proxytype\":\"HTTP\",\"googlekey\":\"sitekey\",\"pageurl\":\"https://target\",\"action\":\"verify\",\"min_score\":0.3}";
Captcha captcha = client.Decode(Client.DefaultTimeout, new Hashtable { {"type", 5}, {"token_params", tokenParams} });Official description: reCAPTCHA v2 Enterprise Full C# sample: RecaptchaV2EnterpriseExample.cs
string tokenParams = "{\"proxy\":\"http://user:pass@127.0.0.1:1234\",\"proxytype\":\"HTTP\",\"googlekey\":\"sitekey\",\"pageurl\":\"https://target\"}";
Captcha captcha = client.Decode(Client.DefaultTimeout, new Hashtable { {"type", 25}, {"token_enterprise_params", tokenParams} });Official description: GeeTest Full C# sample: GeetestV3Example.cs
string geetestParams = "{\"proxy\":\"http://user:pass@127.0.0.1:1234\",\"proxytype\":\"HTTP\",\"gt\":\"gt_value\",\"challenge\":\"challenge_value\",\"pageurl\":\"https://target\"}";
Captcha captcha = client.Decode(Client.DefaultTimeout, new Hashtable { {"type", 8}, {"geetest_params", geetestParams} });Official description: GeeTest Full C# sample: GeetestV4Example.cs
string geetestParams = "{\"proxy\":\"http://user:pass@127.0.0.1:1234\",\"proxytype\":\"HTTP\",\"captcha_id\":\"captcha_id\",\"pageurl\":\"https://target\"}";
Captcha captcha = client.Decode(Client.DefaultTimeout, new Hashtable { {"type", 9}, {"geetest_params", geetestParams} });Official description: Text CAPTCHA Full C# sample: TextcaptchaExample.cs
Captcha captcha = client.Decode(Client.DefaultTimeout, new Hashtable { {"type", 11}, {"textcaptcha", "What is two plus two?"} });Official description: Cloudflare Turnstile Full C# sample: TurnstileExample.cs
string turnstileParams = "{\"proxy\":\"http://user:pass@127.0.0.1:1234\",\"proxytype\":\"HTTP\",\"sitekey\":\"sitekey\",\"pageurl\":\"https://target\"}";
Captcha captcha = client.Decode(Client.DefaultTimeout, new Hashtable { {"type", 12}, {"turnstile_params", turnstileParams} });Official description: Audio CAPTCHA Full C# sample: AudioExample.cs
string audioBase64 = Convert.ToBase64String(File.ReadAllBytes("images/audio.mp3"));
Captcha captcha = client.Decode(Client.DefaultTimeout, new Hashtable { {"type", 13}, {"audio", audioBase64}, {"language", "en"} });Official description: Lemin Full C# sample: LeminExample.cs
string leminParams = "{\"proxy\":\"http://user:pass@127.0.0.1:1234\",\"proxytype\":\"HTTP\",\"captchaid\":\"CROPPED_xxx\",\"pageurl\":\"https://target\"}";
Captcha captcha = client.Decode(Client.DefaultTimeout, new Hashtable { {"type", 14}, {"lemin_params", leminParams} });Official description: Capy Full C# sample: CapyExample.cs
string capyParams = "{\"proxy\":\"http://user:pass@127.0.0.1:1234\",\"proxytype\":\"HTTP\",\"captchakey\":\"PUZZLE_xxx\",\"api_server\":\"https://www.capy.me/\",\"pageurl\":\"https://target\"}";
Captcha captcha = client.Decode(Client.DefaultTimeout, new Hashtable { {"type", 15}, {"capy_params", capyParams} });Official description: Amazon WAF Full C# sample: AmazonWafExample.cs
string wafParams = "{\"proxy\":\"http://user:pass@127.0.0.1:1234\",\"proxytype\":\"HTTP\",\"sitekey\":\"sitekey\",\"pageurl\":\"https://target\",\"iv\":\"iv_value\",\"context\":\"context_value\"}";
Captcha captcha = client.Decode(Client.DefaultTimeout, new Hashtable { {"type", 16}, {"waf_params", wafParams} });Official description: Siara Full C# sample: SiaraExample.cs
string siaraParams = "{\"proxy\":\"http://user:pass@127.0.0.1:1234\",\"proxytype\":\"HTTP\",\"slideurlid\":\"slide_master_url_id\",\"pageurl\":\"https://target\",\"useragent\":\"Mozilla/5.0\"}";
Captcha captcha = client.Decode(Client.DefaultTimeout, new Hashtable { {"type", 17}, {"siara_params", siaraParams} });Official description: MTCaptcha Full C# sample: MtcaptchaExample.cs
string mtcaptchaParams = "{\"proxy\":\"http://user:pass@127.0.0.1:1234\",\"proxytype\":\"HTTP\",\"sitekey\":\"MTPublic-xxx\",\"pageurl\":\"https://target\"}";
Captcha captcha = client.Decode(Client.DefaultTimeout, new Hashtable { {"type", 18}, {"mtcaptcha_params", mtcaptchaParams} });Official description: Cutcaptcha Full C# sample: CutcaptchaExample.cs
string cutcaptchaParams = "{\"proxy\":\"http://user:pass@127.0.0.1:1234\",\"proxytype\":\"HTTP\",\"apikey\":\"api_key\",\"miserykey\":\"misery_key\",\"pageurl\":\"https://target\"}";
Captcha captcha = client.Decode(Client.DefaultTimeout, new Hashtable { {"type", 19}, {"cutcaptcha_params", cutcaptchaParams} });Official description: Friendly Captcha Full C# sample: FriendlycaptchaExample.cs
string friendlyParams = "{\"proxy\":\"http://user:pass@127.0.0.1:1234\",\"proxytype\":\"HTTP\",\"sitekey\":\"FCMG...\",\"pageurl\":\"https://target\"}";
Captcha captcha = client.Decode(Client.DefaultTimeout, new Hashtable { {"type", 20}, {"friendly_params", friendlyParams} });Official description: DataDome Full C# sample: DatadomeExample.cs
string datadomeParams = "{\"proxy\":\"http://user:pass@127.0.0.1:1234\",\"proxytype\":\"HTTP\",\"pageurl\":\"https://target\",\"captcha_url\":\"https://target/captcha\"}";
Captcha captcha = client.Decode(Client.DefaultTimeout, new Hashtable { {"type", 21}, {"datadome_params", datadomeParams} });Official description: Tencent Full C# sample: TencentExample.cs
string tencentParams = "{\"proxy\":\"http://user:pass@127.0.0.1:1234\",\"proxytype\":\"HTTP\",\"appid\":\"appid\",\"pageurl\":\"https://target\"}";
Captcha captcha = client.Decode(Client.DefaultTimeout, new Hashtable { {"type", 23}, {"tencent_params", tencentParams} });Official description: ATB Full C# sample: AtbExample.cs
string atbParams = "{\"proxy\":\"http://user:pass@127.0.0.1:1234\",\"proxytype\":\"HTTP\",\"appid\":\"appid\",\"apiserver\":\"https://cap.aisecurius.com\",\"pageurl\":\"https://target\"}";
Captcha captcha = client.Decode(Client.DefaultTimeout, new Hashtable { {"type", 24}, {"atb_params", atbParams} });Full API-level documentation for selected CAPTCHA types: parameter references, payload schemas, request/response formats, token lifespans, and integration notes.
This repository includes an integrated Selenium sample in DBC_Examples/.
Use this sample when you need a browser-automation flow that extracts sitekey, requests a token using DeathByCaptcha (type 4), injects it into the page, and submits the form.
Quick run:
dotnet run --project DBC_Examples/DBC_Examples.csproj -c Release -f net10.0 \
-p:ExamplesStartupObject=DeathByCaptcha.SeleniumRecaptchaV2ExampleSee detailed usage in SELENIUM_TESTS.md.
β οΈ 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 usernamepassword: Your DBC account passwordtype=4: Type 4 specifies this is the reCAPTCHA v2 Token APItoken_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. 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: Only required for google search tokens. Use the data-s value inside the google search response html. Do not use for regular tokens.
-
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"
}What's the response from the Token image API?
The token will come in the Text property of the Captcha object. It's valid for one use and has a 2 minute lifespan.
"03AOPBWq_RPO2vLzyk0h8gH0cA2X4v3tpYCPZR6Y4yxKy1s3Eo7CHZRQntxrdsaD..."
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, evaluating if user is a bot or human. The website uses the score value (0 to 1) to decide whether to accept the requests. Lower scores near 0 are identified as bot.
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})The API will use "verify" as default value if we don'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.
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 solution comes in the Text property. Refer to Polling for uploaded CAPTCHA status for details. It's valid for one use and has a 1 minute lifespan.
Amazon 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
- C# sample: AmazonWafExample.cs
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 |
pageurl |
Required | Full URL of the page showing the Amazon WAF challenge |
iv |
Required | Value of the iv parameter found in the captcha script |
context |
Required | Value of the context parameter found in the captcha script |
challengejs |
Optional | URL of the challenge.js script referenced on the page |
captchajs |
Optional | URL of the captcha.js script referenced on the page |
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 valid for one use with a 1-minute lifespan. Set it 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.
- Official documentation: deathbycaptcha.com/api/turnstile
- C# sample: TurnstileExample.cs
turnstile_params payload fields:
| Field | Required | Description |
|---|---|---|
proxy |
Optional | Proxy URL with optional credentials |
proxytype |
Required if proxy set |
Proxy connection protocol. Currently only HTTP is supported. |
sitekey |
Required | The Turnstile site key found in data-sitekey attribute or the turnstile.render call |
pageurl |
Required | Full URL of the page hosting the Turnstile challenge |
action |
Optional | Value of the data-action attribute or action option passed to turnstile.render |
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 valid for one use with a 2-minute lifespan. Submit it via the input[name="cf-turnstile-response"] field.
Run only unit tests:
dotnet test DeathByCaptcha/DeathByCaptcha.Tests/DeathByCaptcha.Tests.csproj -c Release --filter "Category!=Integration"Run the whole local test suite:
dotnet test DeathByCaptcha/DeathByCaptcha.Tests/DeathByCaptcha.Tests.csproj -c ReleaseIntegration tests call the live HTTP and Socket APIs and consume account balance.
- Create a local
.envfile from the sample:
cp .env.sample .env- Set credentials in
.env:
DBC_USERNAME='your_username'
DBC_PASSWORD='your_password'
DBC_INTEGRATION_FULL=false- Load variables and run integration tests:
set -a && source .env && set +a
dotnet test DeathByCaptcha/DeathByCaptcha.Tests/DeathByCaptcha.Tests.csproj -c Release --filter "Category=Integration"If DBC_USERNAME and DBC_PASSWORD are not present, integration tests are skipped.
The two "full workflow" tests are disabled by default (slower and more costly). Enable them only when needed:
set -a && source .env && set +a
export DBC_INTEGRATION_FULL=true
dotnet test DeathByCaptcha/DeathByCaptcha.Tests/DeathByCaptcha.Tests.csproj -c Release --filter "Http_FullApiSurface_BasicWorkflow|Socket_FullApiSurface_BasicWorkflow"A .gitlab-ci.yml is included and mirrors all GitHub Actions jobs.
To run the full pipeline locally with gitlab-ci-local:
- Create
.gitlab-ci-local-variables.yml(auto-detected, never commit it):
DBC_USERNAME: "your_username"
DBC_PASSWORD: "your_password"- Run all tests:
gitlab-ci-local --file .gitlab-ci.ymlIntegration and Selenium jobs skip gracefully if the variables file is absent.
Available workflows:
.github/workflows/unit-tests-net6.yml.github/workflows/unit-tests-net8.yml.github/workflows/unit-tests-net10.yml.github/workflows/integration-basic.yml.github/workflows/integration-selenium.yml.github/workflows/coverage.yml.github/workflows/nuget-publish.yml
Set repository secrets DBC_USERNAME and DBC_PASSWORD before running the integration workflow.
The coverage badge is published from workflow .github/workflows/coverage.yml to the badges branch as a Shields endpoint payload.
| Workflow | Status |
|---|---|
| Unit Tests net6 | |
| Unit Tests net8 | |
| Unit Tests net10 | |
| Integration Tests Basic | |
| Integration Tests Selenium | |
| Coverage | |
| NuGet Publish |