Cloudflare - Turnstile Solver

A Python-based Turnstile CAPTCHA solver powered by the Camoufox browser engine. Features multi-threaded execution, RESTful API, automatic cache cleanup, proxy support, and multi-platform Docker deployment (amd64/arm64).

📖 中文文档 · ⚠️ Report Bug · 💡 Request Feature

---

🎁 Donation

• USDT (Arbitrum One): 0x31e16EA02df219562A25636f666fE9038A809105
• BTC: bc1qh423a705lqlpx5ku2ez8d6c3qvgpwwu5vm004y

Note

The donation addresses below belong to the original author of this project (Theyka). If you find this project useful, please consider supporting them!

• USDT (TRC20): TWXNQCnJESt6gxNMX5oHKwQzq4gsbdLNRh
• USDT (Arbitrum One): 0xd8fd1e91c8af318a74a0810505f60ccca4ca0f8c
• BTC: 13iiMaYFpCfNdcyFycSdSVmD2yfQciD7AQ
• LTC: LSrLQe2dfpDhGgVvDTRwW72fSyC9VsXp9g

---

❗ 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

---

⚙️ Installation Instructions

1. Ensure Python 3.8+ is installed on your system.

2. Create a Python virtual environment:

   python -m venv venv

3. Activate the virtual environment:

   • On Windows:

     venv\Scripts\activate

   • On macOS/Linux:

     source venv/bin/activate

4. Install required dependencies:

   pip install -r requirements.txt

5. Start the solver:

   • Run the script (Check 🔧 Command line arguments for configuration):

     python api_solver.py

---

🔧 Command line arguments

Parameter	Default	Type	Description
--thread	1	integer	Number of concurrent browser threads for solving CAPTCHAs.
--proxy	False	boolean	Enable proxy support, randomly selects a proxy from proxies.txt.
--host	0.0.0.0	string	IP address the API server listens on.
--port	5000	integer	Port the API server listens on.
--max_cache_age	3600	integer	Maximum age (in seconds) for cached task results before auto-cleanup.
--debug	False	boolean	Enable debug mode for verbose logging.
--cors	none	string	CORS mode: none = disable, whitelist = allow specific origins, all = allow all origins.
--cors-origins	(empty)	string	Comma-separated allowed origins (only used with --cors whitelist). e.g. https://a.com,https://b.com
--auth-token	(none)	string	API secret token. Clients must send Authorization: Bearer <token> header.
--basic-auth	(none)	string	Basic Auth credentials in user:password format. Clients must send Authorization: Basic <base64> header.

Note: If both --auth-token and --basic-auth are set, either method is accepted. The GET / index page and CORS preflight requests are exempt from authentication.

---

🐳 Docker

Using GitHub Container Registry

Multi-platform images (amd64 & arm64) are automatically built and published via GitHub Actions.

docker pull ghcr.io/taozhiyu/turnstile-solver:latest

Running the Container

docker run -d \
  -p 5000:5000 \
  -e TZ=Asia/Shanghai \
  --name turnstile_solver \
  ghcr.io/taozhiyu/turnstile-solver:latest

You can append any command line arguments after the image name:

docker run -d \
  -p 5000:5000 \
  -e TZ=Asia/Shanghai \
  --name turnstile_solver \
  ghcr.io/taozhiyu/turnstile-solver:latest \
  --host 0.0.0.0 --port 5000 --thread 2 --max_cache_age 7200 \
  --cors all --auth-token your_secret_token

Building Locally

docker build -t turnstile-solver .
docker run -d -p 5000:5000 --name turnstile_solver turnstile-solver

---

📡 API Documentation

Create a Solve Task

POST /turnstile
Content-Type: application/json
Authorization: Bearer <your_token>

Request Body:

{
  "url": "https://example.com",
  "sitekey": "0x4AAAAAAA",
  "action": "login",
  "cdata": "optional-custom-data"
}

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 for additional CAPTCHA parameters.	No
cf_selector	string	Custom CSS selector for the Turnstile widget (default: .cf-turnstile)	No

Response (202 Created):

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

---

Get Result

GET /result?id=<task_id>

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

Response — Pending (202):

{
  "status": "pending"
}

Response — Success (200):

{
  "status": "success",
  "data": {
    "token": "0.KBtT-r...",
    "elapsed_time": 7.625
  }
}

Response — Failed (500):

{
  "status": "error",
  "error": "CAPTCHA_FAIL",
  "elapsed_time": 30.123
}

---

Error Responses

Unauthorized (401) — returned when authentication is enabled and the request is missing or has invalid credentials:

{
  "status": "error",
  "error": "Unauthorized"
}

Bad Request — Invalid JSON (400):

{
  "status": "error",
  "error": "Invalid JSON body or missing Content-Type: application/json"
}

Bad Request — Missing Parameters (400):

{
  "status": "error",
  "error": "Both 'url' and 'sitekey' are required"
}

Not Found — Invalid Task ID (404):

{
  "status": "error",
  "error": "Invalid task ID"
}

---

📜 Credits

Inspired by Turnaround Original code by Theyka Changes by Sexfrance Re-built by taozhiyu