Getting Started with DeathByCaptcha: Solve Your First CAPTCHA

In this article, the third step of the Learning Path, you will go from a blank account to your first solved CAPTCHA. You need nothing more than a browser, a code editor, and a few minutes.

Step 1: Create an Account and Get Credits

1. Go to deathbycaptcha.com and create a free account.
2. New accounts receive 100 free credits to test the API.
3. If you need more, top up with one of the accepted payment methods. Prices start at a few dollars per thousand CAPTCHAs.

Step 2: Get Your Credentials

Your API needs a username and a password. In many projects you will store these in environment variables so you never commit them to source control.

export DBC_USERNAME="your_username"
export DBC_PASSWORD="your_password"

Step 3: Install the Official Client Library

DeathByCaptcha provides official clients for Python, Node.js, PHP, Java, Go, C#, and Ruby. For this example we use Python:

pip install deathbycaptcha

Step 4: Solve Your First Image CAPTCHA

Create a file called first_solve.py:

import os
import deathbycaptcha

client = deathbycaptcha.SocketClient(
    os.environ["DBC_USERNAME"],
    os.environ["DBC_PASSWORD"],
)

with open("captcha.png", "rb") as f:
    captcha = client.decode(f.read(), timeout=60)

if captcha:
    print("Solved text:", captcha.text)
else:
    print("No solution — the CAPTCHA could not be solved in time.")

Place any image CAPTCHA in captcha.png and run:

python first_solve.py

If everything works, you will see the text of the CAPTCHA printed on screen.

The same flow works in every official client. In Node.js:

const DBC = require('deathbycaptcha');
const fs = require('fs');

const client = new DBC.SocketClient(
    process.env.DBC_USERNAME,
    process.env.DBC_PASSWORD,
);

const captcha = await client.decode(fs.readFileSync('captcha.png'), 60);

if (captcha) {
    console.log('Solved text:', captcha.text);
} else {
    console.log('No solution - the CAPTCHA could not be solved in time.');
}

And in C# (NuGet package DeathByCaptcha):

using System;
using System.IO;
using DeathByCaptcha;

Client client = new DeathByCaptcha.HttpClient(
    Environment.GetEnvironmentVariable("DBC_USERNAME"),
    Environment.GetEnvironmentVariable("DBC_PASSWORD")
);

Captcha captcha = client.Decode(File.ReadAllBytes("captcha.png"), Client.DefaultTimeout);

if (captcha != null)
    Console.WriteLine("Solved text: " + captcha.Text);
else
    Console.WriteLine("No solution - the CAPTCHA could not be solved in time.");

Step 5: Solve a Token CAPTCHA

The same client also solves token-based challenges like reCAPTCHA v2. The payload is different:

import os
import deathbycaptcha

client = deathbycaptcha.SocketClient(
    os.environ["DBC_USERNAME"],
    os.environ["DBC_PASSWORD"],
)

result = client.decode({
    "googlekey": "SITE_KEY_FROM_THE_PAGE",
    "pageurl": "https://example.com",
}, type=4, timeout=60)

if result:
    print("Token:", result.text)

The type=4 tells the API this is a reCAPTCHA v2 challenge. Different CAPTCHA types use different type codes and parameters, which we cover in depth in the intermediate articles.

The token flow in Node.js:

const DBC = require('deathbycaptcha');

const client = new DBC.SocketClient(
    process.env.DBC_USERNAME,
    process.env.DBC_PASSWORD,
);

const result = await client.decode({
    googlekey: 'SITE_KEY_FROM_THE_PAGE',
    pageurl: 'https://example.com',
}, 60, 4);

if (result) {
    console.log('Token:', result.text);
}

And in C#:

using System;
using System.Collections;
using DeathByCaptcha;

Client client = new DeathByCaptcha.HttpClient(
    Environment.GetEnvironmentVariable("DBC_USERNAME"),
    Environment.GetEnvironmentVariable("DBC_PASSWORD")
);

string tokenParams = "{\"googlekey\":\"SITE_KEY_FROM_THE_PAGE\",\"pageurl\":\"https://example.com\"}";
Captcha result = client.Decode(Client.DefaultTimeout,
    new Hashtable { { "type", 4 }, { "token_params", tokenParams } });

if (result != null)
    Console.WriteLine("Token: " + result.Text);

Troubleshooting Common Issues

• Wrong credentials: double-check the username and password in your environment.
• Bad payload: for token CAPTCHAs, the sitekey and page URL must match the exact page where the challenge appears.
• Timeout: complex CAPTCHAs can take longer. Increase the timeout or try a different CAPTCHA type.
• Insufficient balance: the free credits may be gone. Top up your account.

Key Takeaways

• Sign up, get your free credits, and grab your API credentials.
• Install the official client for your language.
• Image CAPTCHAs need only the file; token CAPTCHAs need a sitekey and page URL.
• The decode call returns an object with a text field containing your answer.

You have now completed the beginner section. Move on to the intermediate articles to learn the API in depth and integrate solving into real automation.