Cloudflare - Turnstile Solver

A Python-based solution for solving Cloudflare Turnstile challenges quickly (4-6 seconds solve time). The script uses patchright library to interact with web pages and solve the challenges with optimized browser management.

💬 Discord · 📜 ChangeLog · ⚠️ Report Bug · 💡 Request Feature

⚙️ Installation

• Requires: Python 3.8+
• Make a python virtual environment: python3 -m venv venv
• Source the environment: venv\Scripts\activate (Windows) / source venv/bin/activate (macOS, Linux)
• Install the requirements: pip install -r requirements.txt
• Install chrominium: patchright install chromium / python -m patchright install chromium
• Start: python main.py to access all solvers through an interactive interface

---

🔥 Features

• Multi-Browser Pool System: Manages a pool of up to 10 browsers for concurrent solving
• Page Pooling: Efficient page reuse and management within each browser instance
• Three Solving Modes:
  • Synchronous solver for simple use cases
  • Asynchronous solver for better performance
  • API server for web-based integrations
• Browser Configuration:
  • Headless mode support with user agent customization
  • Automated browser cleanup and session management
  • Custom user agent support for better stealth
• Resource Optimization:
  • Smart browser and page lifecycle management
  • Efficient memory usage and cleanup
  • Automatic resource scaling
• Advanced Features:
  • Cookie support for authentication
  • Custom action and cdata parameters
  • Invisible & visible challenge support
  • Comprehensive error handling
• Developer Tools:
  • Debug logging system
  • Interactive CLI interface
  • Built-in API documentation
  • Performance metrics tracking

---

📹 Preview

---

🚀 Usage Examples

# Synchronous Usage
from sync_solver import get_turnstile_token

result = get_turnstile_token(
    url="https://example.com",
    sitekey="your-site-key",
    invisible=True,
    headless=True,
    user_agent="Mozilla/5.0 ..."
)

# Asynchronous Usage
from async_solver import get_turnstile_token
import asyncio

async def main():
    result = await get_turnstile_token(
        url="https://example.com",
        sitekey="your-site-key",
        invisible=True,
        headless=True,
        user_agent="Mozilla/5.0 ..."
    )

# API Server Usage
curl "http://localhost:5000/turnstile?url=https://example.com&sitekey=your-site-key&invisible=true&headless=true&useragent=Mozilla/5.0..."

---

❗ Disclaimers

• I am not responsible for anything that may happen, such as API Blocking, IP ban, etc.
• This was a quick project that was made for fun and personal use if you want to see further updates, star the repo & create an "issue" here

---

🔧 Command line arguments

Parameter	Default	Type	Description
--headless	False	boolean	Runs the browser in headless mode. Requires the --useragent argument to be set.
--useragent	None	string	Specifies a custom User-Agent string for the browser.
--debug	False	boolean	Enables or disables debug mode for additional logging and troubleshooting.
--persistent	False	boolean	Enables a persistent browser context.
--thread	1	integer	Sets the number of browser threads to use in multi-threaded mode.
--host	127.0.0.1	string	Specifies the IP address the API solver runs on.
--port	5000	integer	Sets the port the API solver listens on.

---

🐳 Docker Image

Running the Container

To start the container, use:

• Change the TZ environment variable and ports to the correct one for yourself:

docker run -d -p 3389:3389 -p 5000:5000 -e TZ=Asia/Baku --name turnstile_solver theyka/turnstile_solver:latest

Connecting to the Container

1. Use an RDP client (like Windows Remote Desktop, Remmina, or FreeRDP)
2. Connect to localhost:3389
3. Login with the default user:
   • Username: root
   • Password: root
4. After this, you can start the solver by navigating to the Turnstile-Solver folder.

---

📡 API Documentation

Solve turnstile

  GET /turnstile?url=https://example.com&sitekey=0x4AAAAAAA

Request Parameters:

Parameter	Type	Description	Required
url	string	The target URL containing the CAPTCHA. (e.g., https://example.com)	Yes
sitekey	string	The site key for the CAPTCHA to be solved. (e.g., 0x4AAAAAAA)	Yes
action	string	Action to trigger during CAPTCHA solving, e.g., login	No
cdata	string	Custom data that can be used for additional CAPTCHA parameters.	No

Response:

If the request is successfully received, the server will respond with a task_id for the CAPTCHA solving task:

{
  "task_id": "d2cbb257-9c37-4f9c-9bc7-1eaee72d96a8"
}

Get Result

  GET /result?id=f0dbe75b-fa76-41ad-89aa-4d3a392040af

Request Parameters:

Parameter	Type	Description	Required
id	string	The unique task ID returned from the /turnstile request.	Yes

Response:

If the CAPTCHA is solved successfully, the server will respond with the following information:

{
  "elapsed_time": 7.625,
  "value": "0.KBtT-r"
}

---

📜 ChangeLog

v0.0.1 ⋮ 21/10/2024
! Initial release

v0.0.2 ⋮ 10/28/2024
! Modified the script, page.html is now in the scripts
! Made it faster and less resource intensive
! Modified the sync logic and made an async version
! Implemented logmagix logging
! Added timer

v0.0.3 ⋮ 11/7/2024
+ Added API server implementation
+ Added web interface for API documentation
+ Improved error handling and logging
+ Added concurrent processing support

v0.0.4 ⋮ 12/7/2024
+ Added cookie support for authentication
+ Added action and cdata parameter support
+ Enhanced invisible Turnstile support
+ Improved browser management

v0.0.5 ⋮ 12/24/2024
+ Implemented browser pooling system
+ Added page pooling for each browser
+ Enhanced browser stealth features
+ Added headless mode with user agent support
+ Improved resource cleanup and management
+ Added comprehensive error handling
+ Optimized browser lifecycle management

v0.0.6 ⋮ 12/31/2024
+ Added custom user agent support
+ Enhanced headless mode stability
+ Improved browser argument handling
+ Added automatic scaling for resources
+ Enhanced error reporting system
+ Optimized page cleanup process

v0.1.0 ⋮ 11/7/2024
+ Added API server implementation
+ Added web interface for API documentation
+ Improved error handling and logging
+ Added concurrent processing support

v0.1.1 ⋮ 15/2/2025
+ Added --headless argument
+ Added --debug argument
+ Added --useragent argument
! Modified logging method to use the logging library

v0.1.2 ⋮ 19/02/2025
+ Added optional action and cData parameters, similar to sitekey and url.

v0.1.3 ⋮ 22/02/2025
+ Added persistent context browser for improved security
+ Implemented multi-threaded mode for enhanced performance
+ Added method to configure host and port for API server

---

Inspired by Turnaround Original code by Theyka Changes by Sexfrance