The DeathByCaptcha Go client is the official library for integrating the DeathByCaptcha bypass captcha service into your Go applications. Purpose-built as a captcha solver for bots and automation pipelines, it provides a simple, well-documented interface for solving image, audio and modern token-based CAPTCHAs — a particularly common requirement when building scrapers or bots where CAPTCHAs block access to the pages you need to process. 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).

Compatible with Go 1.21+ (tested on Go 1.25 and Go 1.26).

Key features:

• 🧩 Send image, audio and modern token-based CAPTCHA types (reCAPTCHA v2/v3, Turnstile, GeeTest, etc.).
• 🔄 Unified Client interface across HTTP and socket transports — switching implementations is a one-line change.
• 🔐 Built-in support for proxies, timeouts and advanced token parameters for modern CAPTCHA flows.
• ⚡ Concurrent-safe: both clients use sync.Mutex internally.

Quick start example (HTTP):

import dbc "github.com/deathbycaptcha/deathbycaptcha-api-client-go/v4/deathbycaptcha"

client := dbc.NewHttpClient("your_username", "your_password")
defer client.Close()

captcha, err := client.Decode("path/to/captcha.jpg", dbc.DefaultTimeout, map[string]string{})
if err != nil {
    log.Fatal(err)
}
if captcha != nil {
    fmt.Println("Solved:", *captcha.Text)
}

🚌 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
  • From pkg.go.dev (Recommended)
  • From GitHub Repository
• How to Use DBC API Clients
  • Common Clients' Interface
  • Available Methods
  • Concurrent Usage (Goroutines)
• 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)

go get github.com/deathbycaptcha/deathbycaptcha-api-client-go/v4/deathbycaptcha

For the latest development version or to contribute:

git clone https://github.com/deathbycaptcha/deathbycaptcha-api-client-go.git
cd deathbycaptcha-api-client-go
go mod download

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

import dbc "github.com/deathbycaptcha/deathbycaptcha-api-client-go/v4/deathbycaptcha"

// Username + password (HTTPS transport — encrypted, recommended when security matters)
client := dbc.NewHttpClient(username, password)

// Username + password (socket transport — faster, lower latency, recommended for high throughput)
// client := dbc.NewSocketClient(username, password)

// Authtoken (HTTPS transport)
client := dbc.NewHttpClientWithToken(authtoken)

// Authtoken (socket transport)
// client := dbc.NewSocketClientWithToken(authtoken)

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

All methods that return a solved CAPTCHA return a *Captcha struct with the following fields:

// Example result
captcha, err := client.Decode("captcha.jpg", dbc.DefaultTimeout, map[string]string{})
if captcha != nil {
    fmt.Printf("ID: %d  Text: %s  Correct: %v\n",
        captcha.CaptchaID, *captcha.Text, captcha.IsCorrect)
}

package main

import (
    "fmt"
    "log"
    "os"

    dbc "github.com/deathbycaptcha/deathbycaptcha-api-client-go/v4/deathbycaptcha"
)

func main() {
    client := dbc.NewHttpClient(os.Getenv("DBC_USERNAME"), os.Getenv("DBC_PASSWORD"))
    defer client.Close()

    bal, err := client.GetBalance()
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Balance: %.4f US cents\n", bal)

    captcha, err := client.Decode("path/to/captcha.jpg", dbc.DefaultTimeout, map[string]string{})
    if err != nil {
        if _, ok := err.(*dbc.AccessDeniedException); ok {
            log.Fatal("Access denied — check your credentials and/or balance")
        }
        log.Fatal(err)
    }
    if captcha != nil {
        fmt.Printf("Solved CAPTCHA %d: %s\n", captcha.CaptchaID, *captcha.Text)

        // Report only if you are certain the solution is wrong:
        // client.Report(captcha.CaptchaID)
    }
}

Both HttpClient and SocketClient are safe for concurrent use:

• HttpClient — wraps Go's net/http.Client, which is goroutine-safe. A single shared instance works; one-per-goroutine is preferred for maximum throughput.
• SocketClient — serialises all socket operations with an internal sync.Mutex. One instance per goroutine is the recommended pattern (independent TCP connections, no head-of-line blocking).

package main

import (
    "errors"
    "fmt"
    "os"
    "sync"

    dbc "github.com/deathbycaptcha/deathbycaptcha-api-client-go/v4/deathbycaptcha"
)

func httpWorker(username, password, imagePath string, id int, wg *sync.WaitGroup) {
    defer wg.Done()
    client := dbc.NewHttpClient(username, password) // own instance
    defer client.Close()

    captcha, err := client.Decode(imagePath, dbc.DefaultTimeout, map[string]string{})
    if err != nil {
        var ade *dbc.AccessDeniedException
        if errors.As(err, &ade) {
            fmt.Fprintf(os.Stderr, "[HTTP %d] access denied\n", id)
            return
        }
        fmt.Fprintf(os.Stderr, "[HTTP %d] error: %v\n", id, err)
        return
    }
    if captcha != nil {
        fmt.Printf("[HTTP %d] solved %d: %s\n", id, captcha.CaptchaID, *captcha.Text)
    }
}

func main() {
    username := os.Getenv("DBC_USERNAME")
    password := os.Getenv("DBC_PASSWORD")

    var wg sync.WaitGroup
    for i := 1; i <= 4; i++ {
        wg.Add(1)
        go httpWorker(username, password, "images/normal.jpg", i, &wg)
    }
    wg.Wait()
}

Full runnable example: examples/example.Goroutine_Http.go

package main

import (
    "fmt"
    "os"
    "sync"

    dbc "github.com/deathbycaptcha/deathbycaptcha-api-client-go/v4/deathbycaptcha"
)

func socketWorker(username, password, imagePath string, id int, wg *sync.WaitGroup) {
    defer wg.Done()
    client := dbc.NewSocketClient(username, password) // own TCP connection
    defer client.Close()

    captcha, err := client.Decode(imagePath, dbc.DefaultTimeout, map[string]string{})
    if err != nil {
        fmt.Fprintf(os.Stderr, "[SOCKET %d] error: %v\n", id, err)
        return
    }
    if captcha != nil {
        fmt.Printf("[SOCKET %d] solved %d: %s\n", id, captcha.CaptchaID, *captcha.Text)
    }
}

func main() {
    username := os.Getenv("DBC_USERNAME")
    password := os.Getenv("DBC_PASSWORD")

    var wg sync.WaitGroup
    for i := 1; i <= 4; i++ {
        wg.Add(1)
        go socketWorker(username, password, "images/normal.jpg", i, &wg)
    }
    wg.Wait()
}

Full runnable example: examples/example.Goroutine_Socket.go

# HTTP — 4 goroutines, balance-check mode
DBC_USERNAME=user DBC_PASSWORD=pass DBC_THREADS=4 \
  go run examples/example.Goroutine_Http.go

# HTTP — 4 goroutines, decode mode
DBC_USERNAME=user DBC_PASSWORD=pass DBC_THREADS=4 DBC_IMAGE_PATH=examples/images/normal.jpg \
  go run examples/example.Goroutine_Http.go

# Socket — 4 goroutines, decode mode
DBC_USERNAME=user DBC_PASSWORD=pass DBC_THREADS=4 DBC_IMAGE_PATH=examples/images/normal.jpg \
  go run examples/example.Goroutine_Socket.go

// Username + password
client := dbc.NewHttpClient("your_username", "your_password")

// Auth token (from DBC user panel)
client := dbc.NewHttpClientWithToken("your_authtoken")

// Socket variants
client := dbc.NewSocketClient("your_username", "your_password")
client := dbc.NewSocketClientWithToken("your_authtoken")

Never commit real credentials to source control. Use environment variables:

# ① Export credentials in your shell
export DBC_USERNAME=your_username
export DBC_PASSWORD=your_password

# ② Run tests locally (fastest)
go test ./deathbycaptcha/... -v

# ③ Run integration tests with real credentials
DBC_USERNAME=your_user DBC_PASSWORD=your_pass \
  go test -tags=integration ./tests/integration/... -v -timeout 300s

# ④ 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 the library (see Installation)
2. 📂 Navigate to the examples/ directory and run the script for the type you need:

cd examples
go run example.Normal_Captcha.go

# Balance check:
go run get_balance.go

⚠️ Always run examples from the examples/ directory so the images/ folder is accessible to scripts that need it.

Before running any script, add your DBC credentials inside it:

username := "your_username"
password := "your_password"

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

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.

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

captcha, err := client.Decode("images/normal.jpg", dbc.DefaultTimeout, map[string]string{})

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

import "encoding/json"

tokenParams, _ := json.Marshal(map[string]string{
    "proxy":     "http://user:pass@127.0.0.1:1234",
    "proxytype": "HTTP",
    "googlekey": "sitekey",
    "pageurl":   "https://target",
})
captcha, err := client.Decode(nil, dbc.DefaultTokenTimeout, map[string]string{
    "type":         "4",
    "token_params": string(tokenParams),
})

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

import "encoding/json"

tokenParams, _ := json.Marshal(map[string]interface{}{
    "proxy":     "http://user:pass@127.0.0.1:1234",
    "proxytype": "HTTP",
    "googlekey": "sitekey",
    "pageurl":   "https://target",
    "action":    "verify",
    "min_score": 0.3,
})
captcha, err := client.Decode(nil, dbc.DefaultTokenTimeout, map[string]string{
    "type":         "5",
    "token_params": string(tokenParams),
})

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

import "encoding/json"

enterpriseParams, _ := json.Marshal(map[string]string{
    "proxy":     "http://user:pass@127.0.0.1:1234",
    "proxytype": "HTTP",
    "googlekey": "sitekey",
    "pageurl":   "https://target",
})
captcha, err := client.Decode(nil, dbc.DefaultTokenTimeout, map[string]string{
    "type":                    "25",
    "token_enterprise_params": string(enterpriseParams),
})

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

import "encoding/json"

geetestParams, _ := json.Marshal(map[string]string{
    "proxy":     "http://user:pass@127.0.0.1:1234",
    "proxytype": "HTTP",
    "gt":        "gt_value",
    "challenge": "challenge_value",
    "pageurl":   "https://target",
})
captcha, err := client.Decode(nil, dbc.DefaultTokenTimeout, map[string]string{
    "type":           "8",
    "geetest_params": string(geetestParams),
})

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

import "encoding/json"

geetestParams, _ := json.Marshal(map[string]string{
    "proxy":      "http://user:pass@127.0.0.1:1234",
    "proxytype":  "HTTP",
    "captcha_id": "captcha_id",
    "pageurl":    "https://target",
})
captcha, err := client.Decode(nil, dbc.DefaultTokenTimeout, map[string]string{
    "type":           "9",
    "geetest_params": string(geetestParams),
})

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

captcha, err := client.Decode(nil, dbc.DefaultTimeout, map[string]string{
    "type":        "11",
    "textcaptcha": "What is two plus two?",
})

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

import "encoding/json"

turnstileParams, _ := json.Marshal(map[string]string{
    "proxy":     "http://user:pass@127.0.0.1:1234",
    "proxytype": "HTTP",
    "sitekey":   "sitekey",
    "pageurl":   "https://target",
})
captcha, err := client.Decode(nil, dbc.DefaultTokenTimeout, map[string]string{
    "type":             "12",
    "turnstile_params": string(turnstileParams),
})

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

import (
    "encoding/base64"
    "os"
)

audioData, _ := os.ReadFile("images/audio.mp3")
captcha, err := client.Decode(nil, dbc.DefaultTokenTimeout, map[string]string{
    "type":     "13",
    "audio":    base64.StdEncoding.EncodeToString(audioData),
    "language": "en",
})

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

import "encoding/json"

leminParams, _ := json.Marshal(map[string]string{
    "proxy":     "http://user:pass@127.0.0.1:1234",
    "proxytype": "HTTP",
    "captchaid": "CROPPED_xxx",
    "pageurl":   "https://target",
})
captcha, err := client.Decode(nil, dbc.DefaultTokenTimeout, map[string]string{
    "type":         "14",
    "lemin_params": string(leminParams),
})

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

import "encoding/json"

capyParams, _ := json.Marshal(map[string]string{
    "proxy":      "http://user:pass@127.0.0.1:1234",
    "proxytype":  "HTTP",
    "captchakey": "PUZZLE_xxx",
    "api_server": "https://api.capy.me/",
    "pageurl":    "https://target",
})
captcha, err := client.Decode(nil, dbc.DefaultTokenTimeout, map[string]string{
    "type":        "15",
    "capy_params": string(capyParams),
})

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

import "encoding/json"

wafParams, _ := json.Marshal(map[string]string{
    "proxy":     "http://user:pass@127.0.0.1:1234",
    "proxytype": "HTTP",
    "sitekey":   "sitekey",
    "pageurl":   "https://target",
    "iv":        "iv_value",
    "context":   "context_value",
})
captcha, err := client.Decode(nil, dbc.DefaultTokenTimeout, map[string]string{
    "type":       "16",
    "waf_params": string(wafParams),
})

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

import "encoding/json"

siaraParams, _ := json.Marshal(map[string]string{
    "proxy":      "http://user:pass@127.0.0.1:1234",
    "proxytype":  "HTTP",
    "slideurlid": "OXR2LVNvCuXykkZbB8KZIfh162sNT8S2",
    "pageurl":    "https://target",
    "useragent":  "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
})
captcha, err := client.Decode(nil, dbc.DefaultTokenTimeout, map[string]string{
    "type":         "17",
    "siara_params": string(siaraParams),
})

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

import "encoding/json"

mtParams, _ := json.Marshal(map[string]string{
    "proxy":     "http://user:pass@127.0.0.1:1234",
    "proxytype": "HTTP",
    "sitekey":   "MTPublic-xxx",
    "pageurl":   "https://target",
})
captcha, err := client.Decode(nil, dbc.DefaultTokenTimeout, map[string]string{
    "type":             "18",
    "mtcaptcha_params": string(mtParams),
})

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

import "encoding/json"

cutParams, _ := json.Marshal(map[string]string{
    "proxy":     "http://user:pass@127.0.0.1:1234",
    "proxytype": "HTTP",
    "apikey":    "SAs61IAI",
    "miserykey": "56a9e9b989aa8cf99e0cea28d4b4678b84fa7a4e",
    "pageurl":   "https://target",
})
captcha, err := client.Decode(nil, dbc.DefaultTokenTimeout, map[string]string{
    "type":              "19",
    "cutcaptcha_params": string(cutParams),
})

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

import "encoding/json"

friendlyParams, _ := json.Marshal(map[string]string{
    "proxy":     "http://user:pass@127.0.0.1:1234",
    "proxytype": "HTTP",
    "sitekey":   "FCMG...",
    "pageurl":   "https://target",
})
captcha, err := client.Decode(nil, dbc.DefaultTokenTimeout, map[string]string{
    "type":            "20",
    "friendly_params": string(friendlyParams),
})

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

import "encoding/json"

datadomeParams, _ := json.Marshal(map[string]string{
    "proxy":       "http://user:pass@127.0.0.1:1234",
    "proxytype":   "HTTP",
    "pageurl":     "https://target",
    "captcha_url": "https://target/captcha",
})
captcha, err := client.Decode(nil, dbc.DefaultTokenTimeout, map[string]string{
    "type":            "21",
    "datadome_params": string(datadomeParams),
})

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

import "encoding/json"

tencentParams, _ := json.Marshal(map[string]string{
    "proxy":     "http://user:pass@127.0.0.1:1234",
    "proxytype": "HTTP",
    "appid":     "2044554539",
    "pageurl":   "https://target",
})
captcha, err := client.Decode(nil, dbc.DefaultTokenTimeout, map[string]string{
    "type":           "23",
    "tencent_params": string(tencentParams),
})

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

import "encoding/json"

atbParams, _ := json.Marshal(map[string]string{
    "proxy":     "http://user:pass@127.0.0.1:1234",
    "proxytype": "HTTP",
    "appid":     "af23e041b22d000a11e22a230fa8991c",
    "apiserver": "https://cap.aisecurius.com",
    "pageurl":   "https://target",
})
captcha, err := client.Decode(nil, dbc.DefaultTokenTimeout, map[string]string{
    "type":       "24",
    "atb_params": string(atbParams),
})

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

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:

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

  • 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 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
• Go sample: examples/example.Amazon_Waf.go

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:

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..."
}

With optional challengejs and captchajs:

{
  "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...",
  "challengejs": "https://41bcdd4fb3cb.610cd090.us-east-1.token.awswaf.com/41bcdd4fb3cb/0d21de737ccb/cd77baa6c832/challenge.js",
  "captchajs": "https://41bcdd4fb3cb.610cd090.us-east-1.captcha.awswaf.com/41bcdd4fb3cb/0d21de737ccb/cd77baa6c832/captcha.js"
}

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:

c3b50e60-d76c-4d13-ae25-159ec7ec3121:EQoAj4x6fnENAAAA:YIvITdQewAaLmaLXo4r6Es783keXM2ahoP...

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
• Go sample: examples/example.Turnstile.go

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

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 (basic):

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

Example turnstile_params with optional action:

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

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:

0.Ja5ditqqMhsYE6r9okpFeZVg6ixDXZcbSTzxypXJkAeN-D-VxmNaEBR_XfsPGk-nxhJFUwMERSIXk6npwAifIYfKuP5AZHeLgCAm0W6CAyJlc9WvO_t7pGYnR_wwbyUyroooPkOI9mfHeeXb1urRmsTF_kP5pU5kQ05OVx3EyuXK3nl0fd4y1u7SyYThi...

go test ./deathbycaptcha/... -v -timeout 120s

go test ./deathbycaptcha/... -coverprofile=coverage.out -covermode=atomic -timeout 120s
go tool cover -func=coverage.out

DBC_USERNAME=your_user DBC_PASSWORD=your_pass \
  go test -tags=integration ./tests/integration/... -v -timeout 300s

Without credentials, integration tests are automatically skipped.

Coverage badge is served from GitHub Pages at:

https://img.shields.io/endpoint?url=https://deathbycaptcha.github.io/deathbycaptcha-api-client-go/coverage-badge.json

Color thresholds: brightgreen ≥ 85 %, yellow 70–84 %, red < 70 %.

Badge interpretation:

• Unit Tests Go 1.25 / Unit Tests Go 1.26 — main unit test pipeline on Go 1.25 and Go 1.26 passed. Covers build, vet, and all unit tests without network access.
• API Integration — live API test pipeline passed (or skipped when secrets are absent — the badge shows passing in both cases).
• Coverage — latest reported line coverage, updated on each push to main. Accepted threshold: ≥ 80 %.

This project is licensed under the MIT License.

See RESPONSIBLE_USE.md. This library is intended for legitimate automation, testing, and research only. Do not use it to bypass protections on third-party sites without explicit authorization.