How to bypass TSPD captcha

Introduction

TSPD is a modern behavioral protection system often used to block automated requests and bots. Unlike classic captchas with visual widgets, a TSPD challenge usually appears as an intermediate blocking page returned by the server instead of the normal content. For automation, this means we don't just need to get a token; we need to pass a complex network challenge by emulating real browser behavior and maintaining the cookies session.

In this guide, we will break down how to automate bypassing TSPD using the 2Captcha API. We will look at the workflow in detail, find the necessary parameters, and integrate the solution into your script.

Workflow

Bypassing TSPD is different from solving regular captchas. Here, we work with network requests and cookies rather than a widget on the page. The process consists of several stages:

1. Initial request. The script makes an HTTP request to the target page via a proxy using browser headers.
2. Getting cookies. Protection cookies are extracted from the server response. If the TSPD_101_DID cookie is present (meaning the protection is already passed) or the cookie format does not match the expected one, the execution stops.
3. Creating a task. The script sends the data to our service to solve the TSPD challenge.
4. Getting the solution. The script waits for the task to be processed via the API and receives updated cookies.
5. Final request. A repeated request is made to the page using the obtained cookies, after which the server returns the normal HTML page.

It is critical that all stages (the initial request, solving via API, and the final request) are executed through the exact same proxy IP address.

How to Find the Required Parameters

When sending a GET request to the TSPD challenge page, you will receive HTML that needs to be encoded in Base64 and passed in the htmlPageBase64 parameter. Also, during the initial request, the server will issue special cookies (for example, TS386a...400d029) — they must be passed in tspdcookie, as they are mandatory for correctly solving TSPD and getting a response from the API.

Important: the htmlPageBase64 and tspdcookie parameters are dynamic. Extract them immediately before submitting the task, otherwise the solution might fail.

Note: if the server returns cookies in a specific format (for example, TS386a400d029=082670...87599c;) and the TSPD_101_DID cookie is missing, it means the request was intercepted by the protection system and a blocking page (TSPD challenge) was issued instead of a normal response. In this situation, you need to pass the received cookies to the service, wait for the solution, and use the updated set for subsequent requests.

API Parameters

To solve TSPD, the tspdtask task type is used. Since the protection is strictly tied to the IP address, using a proxy is mandatory. All parameters that need to be passed when creating a task are presented in the table below:

JSON Request Examples

A request to create a task looks like this:

{
    "clientKey": "YOUR_API_KEY",
    "task": {
        "type": "tspdtask",
        "websiteURL": "https://example.com/login",
        "tspdcookie": "TS386a400d029=082670...010245; TS386a400d078=082670...dbb3b0c",
        "htmlPageBase64": "PCFET0NUWVBFIGh0bWw+...",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36",
        "proxyType": "http",
        "proxyAddress": "1.2.3.4",
        "proxyPort": 8080,
        "proxyLogin": "login",
        "proxyPassword": "password"
    }
}

A request to get the result is standard:

{
    "clientKey": "YOUR_API_KEY",
    "taskId": "TASK_ID_FROM_CREATE_TASK"
}

A successful response from the API will contain the updated cookies for injection:

{
    "errorId": 0,
    "status": "ready",
    "solution": {
        "cookies": "TSPD_101_DID=...; TS386a400d029=..."
    },
    "cost": "0.00299",
    "createTime": 1692863536,
    "endTime": 1692863556
}

Step-by-Step Implementation in Python

To work with TSPD, we will need the requests library to make HTTP requests via a proxy and the official library to work with the API.

Full cycle: from the initial request to getting the content

import requests
import time
import base64
from twocaptcha import TwoCaptcha

API_KEY = "YOUR_API_KEY"
API_HOST = "api.2captcha.com"

# Proxy settings (must be used at all stages!)
PROXY = {
    "http": "http://login:password@1.2.3.4:8080",
    "https": "http://login:password@1.2.3.4:8080"
}
USER_AGENT = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36"
TARGET_URL = "https://example.com/protected-page"

# 1. Initial request to the target page
session = requests.Session()
session.headers.update({"User-Agent": USER_AGENT})
response = session.get(TARGET_URL, proxies=PROXY)

# Check if the TSPD_101_DID cookie is already present (meaning protection is passed)
if "TSPD_101_DID" in session.cookies.get_dict():
    print("Protection already passed!")
else:
    # 2. Extract parameters for solving
    html_page = response.text
    html_base64 = base64.b64encode(html_page.encode('utf-8')).decode('utf-8')
    
    # Form the cookies string from the response
    tspd_cookies = "; ".join([f"{name}={value}" for name, value in session.cookies.get_dict().items()])
    
    # 3. Send the task to the API
    solver = TwoCaptcha(API_KEY, api_hostname=API_HOST)
    
    try:
        result = solver.tspdtask(
            website_url=TARGET_URL,
            tspdcookie=tspd_cookies,
            html_page_base64=html_base64,
            user_agent=USER_AGENT,
            proxy_type="http",
            proxy_address="1.2.3.4",
            proxy_port=8080,
            proxy_login="login",
            proxy_password="password"
        )
        
        # 4. Get new cookies from the solution
        solved_cookies = result.get('cookies', '')
        print(f"Solution received: {solved_cookies}")
        
        # 5. Final request with new cookies
        # Parse the cookies string and add them to the session
        for cookie in solved_cookies.split(';'):
            if '=' in cookie:
                name, value = cookie.strip().split('=', 1)
                session.cookies.set(name, value)
                
        final_response = session.get(TARGET_URL, proxies=PROXY)
        print("Page successfully loaded!")
        print(final_response.text[:500]) # Print the beginning of the content
        
    except Exception as e:
        print(f"Error solving: {e}")

Important Nuances and Best Practices

TSPD is highly sensitive to network fingerprints and IP addresses. If you make the initial request from one IP, solve the task, and send the final request from another, the protection will instantly notice and reject the cookies.

Always use the same residential proxies at all stages: during the initial request, when passing parameters to the API (via proxyType, proxyAddress, etc.), and during the final request for content.

Synchronize the User-Agent. Pass the same User-Agent in the API task parameters that you used for the initial request to the page. If they differ, TSPD might consider the session suspicious.

The htmlPageBase64 and tspdcookie parameters expire very quickly. Extract them immediately before sending the task to the API and do not make unnecessary delays between receiving the challenge and solving it.

Solution Accuracy Reports

If the site returns the blocking page again instead of content after the final request, be sure to report it. This helps the service improve its algorithms and refunds your funds for the failed attempt.

You can submit a report in two ways:

The first way is via the dashboard. Go to the upload statistics section at https://2captcha.com/statistics/uploads. Find the relevant task in the list and click the Report incorrect button.

The second way is via the API. If you are writing an automated script, use the reportIncorrect and reportCorrect endpoints, passing your API key and the taskId of the task.

Troubleshooting Common Issues

If the API returns an ERROR_CAPTCHA_UNSOLVABLE error, the challenge has most likely expired. Make sure you extract htmlPageBase64 and tspdcookie immediately before submitting the task and do not pause between steps.

If the site accepts the cookies but then still returns the blocking page during the final request, the problem is almost certainly the IP address. Check that the proxy used for the initial request, in the API, and for the final request is absolutely identical.

If you get the TSPD_101_DID cookie immediately during the initial request, it means the protection is already passed (for example, the proxy is "clean" and TSPD does not consider you a bot). In this case, there is no need to send a task to the API.

Useful Links

• TSPD API Documentation: https://2captcha.com/api-docs/tspd-captcha
• Upload statistics and sending reports: https://2captcha.com/statistics/uploads
• Support Center: https://2captcha.com/support/tickets/new
• Code examples on GitHub: https://github.com/2captcha.com

Conclusion

Bypassing TSPD via 2Captcha boils down to making an initial request via a proxy, extracting the challenge HTML page and cookies, sending this data to the API, and using the obtained updated cookies for the final request. The main thing to remember is the critical importance of using the same proxy at all stages and executing all steps quickly, as the challenge parameters have a very short lifespan.